├── .ansible-lint
├── .gitignore
├── vars
    ├── Debian.yml
    └── RedHat.yml
├── .github
    ├── FUNDING.yml
    └── workflows
    │   ├── release.yml
    │   ├── ci.yml
    │   └── stale.yml
├── molecule
    └── default
    │   ├── requirements.yml
    │   ├── xdebug-test.php
    │   ├── molecule.yml
    │   └── converge.yml
├── .yamllint
├── defaults
    └── main.yml
├── templates
    └── xdebug.ini.j2
├── tasks
    ├── configure.yml
    └── main.yml
├── meta
    └── main.yml
├── LICENSE
└── README.md


/.ansible-lint:
--------------------------------------------------------------------------------
1 | skip_list:
2 |   - 'yaml'
3 |   - 'role-name'
4 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | *.retry
2 | */__pycache__
3 | *.pyc
4 | .cache
5 | 
6 | 


--------------------------------------------------------------------------------
/vars/Debian.yml:
--------------------------------------------------------------------------------
1 | ---
2 | __php_xdebug_module_path: /usr/lib/php7/modules
3 | __php_xdebug_config_filename: 20-xdebug.ini
4 | 


--------------------------------------------------------------------------------
/vars/RedHat.yml:
--------------------------------------------------------------------------------
1 | ---
2 | __php_xdebug_module_path: /usr/lib64/php/modules
3 | __php_xdebug_config_filename: xdebug.ini
4 | 


--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
1 | # These are supported funding model platforms
2 | ---
3 | github: geerlingguy
4 | patreon: geerlingguy
5 | 


--------------------------------------------------------------------------------
/molecule/default/requirements.yml:
--------------------------------------------------------------------------------
1 | ---
2 | - src: geerlingguy.repo-remi
3 | - src: geerlingguy.php-versions
4 | - src: geerlingguy.php
5 | 


--------------------------------------------------------------------------------
/.yamllint:
--------------------------------------------------------------------------------
 1 | ---
 2 | extends: default
 3 | 
 4 | rules:
 5 |   line-length:
 6 |     max: 120
 7 |     level: warning
 8 | 
 9 | ignore: |
10 |   .github/workflows/stale.yml
11 | 


--------------------------------------------------------------------------------
/molecule/default/xdebug-test.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | /**
 4 |  * @file
 5 |  * Test if Xdebug is available and working.
 6 |  */
 7 | 
 8 | $success = FALSE;
 9 | 
10 | // Simple check; this function should return an empty array.
11 | $test = xdebug_get_code_coverage();
12 | if ($test === array()) {
13 |   $success = TRUE;
14 |   print "Xdebug working properly.\r\n";
15 |   exit(0);
16 | }
17 | 
18 | if (!$success) {
19 |   print "Xdebug not working properly.\r\n";
20 |   exit(1);
21 | }
22 | 


--------------------------------------------------------------------------------
/defaults/main.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | workspace: /root
 3 | 
 4 | php_xdebug_version: 3.3.2
 5 | 
 6 | php_xdebug_coverage_enable: 1
 7 | php_xdebug_default_enable: 1
 8 | 
 9 | php_xdebug_remote_enable: "false"
10 | php_xdebug_remote_connect_back: "false"
11 | php_xdebug_remote_host: localhost
12 | php_xdebug_remote_port: "9000"
13 | php_xdebug_remote_log: /tmp/xdebug.log
14 | php_xdebug_remote_autostart: "false"
15 | 
16 | php_xdebug_idekey: sublime.xdebug
17 | 
18 | php_xdebug_max_nesting_level: 256
19 | 
20 | # Only used on Debian/Ubuntu.
21 | php_xdebug_cli_disable: false
22 | 


--------------------------------------------------------------------------------
/molecule/default/molecule.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | role_name_check: 1
 3 | dependency:
 4 |   name: galaxy
 5 |   options:
 6 |     ignore-errors: true
 7 | driver:
 8 |   name: docker
 9 | platforms:
10 |   - name: instance
11 |     image: "geerlingguy/docker-${MOLECULE_DISTRO:-rockylinux9}-ansible:latest"
12 |     command: ${MOLECULE_DOCKER_COMMAND:-""}
13 |     volumes:
14 |       - /sys/fs/cgroup:/sys/fs/cgroup:rw
15 |     cgroupns_mode: host
16 |     privileged: true
17 |     pre_build_image: true
18 | provisioner:
19 |   name: ansible
20 |   playbooks:
21 |     converge: ${MOLECULE_PLAYBOOK:-converge.yml}
22 | 


--------------------------------------------------------------------------------
/templates/xdebug.ini.j2:
--------------------------------------------------------------------------------
 1 | [XDebug]
 2 | zend_extension="{{ php_xdebug_module_path }}/xdebug-{{ php_xdebug_version }}.so"
 3 | 
 4 | xdebug.coverage_enable={{ php_xdebug_coverage_enable }}
 5 | xdebug.default_enable={{ php_xdebug_default_enable }}
 6 | 
 7 | xdebug.remote_enable={{ php_xdebug_remote_enable }}
 8 | xdebug.remote_connect_back={{ php_xdebug_remote_connect_back }}
 9 | xdebug.remote_host={{ php_xdebug_remote_host }}
10 | xdebug.remote_port={{ php_xdebug_remote_port }}
11 | xdebug.remote_log={{ php_xdebug_remote_log }}
12 | xdebug.remote_autostart={{ php_xdebug_remote_autostart }}
13 | 
14 | xdebug.idekey="{{ php_xdebug_idekey }}"
15 | 
16 | xdebug.max_nesting_level={{ php_xdebug_max_nesting_level }}
17 | 


--------------------------------------------------------------------------------
/molecule/default/converge.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | - name: Converge
 3 |   hosts: all
 4 |   #become: true
 5 | 
 6 |   vars:
 7 |     php_enable_webserver: false
 8 | 
 9 |   pre_tasks:
10 |     - name: Update apt cache.
11 |       apt: update_cache=true cache_valid_time=600
12 |       when: ansible_facts.os_family == 'Debian'
13 | 
14 |   roles:
15 |     - role: geerlingguy.repo-remi
16 |       when: ansible_facts.os_family == 'RedHat'
17 |     - role: geerlingguy.php-versions
18 |     - role: geerlingguy.php
19 |     - role: geerlingguy.php-xdebug
20 | 
21 |   post_tasks:
22 |     - name: Run test script to confirm XDebug is working.
23 |       script: xdebug-test.php
24 |       args:
25 |         executable: php
26 |       changed_when: false
27 | 


--------------------------------------------------------------------------------
/tasks/configure.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | - name: Copy xdebug ini into main extension config folder.
 3 |   template:
 4 |     src: xdebug.ini.j2
 5 |     dest: "{{ item }}/{{ php_xdebug_config_filename }}"
 6 |     owner: root
 7 |     group: root
 8 |     mode: 0644
 9 |   when: "'cli' not in item or ('cli' in item and not php_xdebug_cli_disable)"
10 |   with_items: "{{ php_extension_conf_paths }}"
11 |   notify:
12 |     - restart webserver
13 |     - restart php-fpm
14 | 
15 | - name: Disable xdebug for PHP CLI.
16 |   file:
17 |     path: "/etc/php/{{ php_version }}/cli/conf.d/{{ php_xdebug_config_filename }}"
18 |     state: absent
19 |   when: ansible_facts.os_family == 'Debian' and php_xdebug_cli_disable
20 |   notify:
21 |     - restart webserver
22 |     - restart php-fpm
23 | 


--------------------------------------------------------------------------------
/meta/main.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | dependencies:
 3 |   - geerlingguy.php
 4 | 
 5 | galaxy_info:
 6 |   role_name: php-xdebug
 7 |   author: geerlingguy
 8 |   description: PHP XDebug for Linux
 9 |   company: "Midwestern Mac, LLC"
10 |   license: "license (BSD, MIT)"
11 |   min_ansible_version: 2.10
12 |   platforms:
13 |     - name: GenericUNIX
14 |       versions:
15 |         - all
16 |     - name: Fedora
17 |       versions:
18 |         - all
19 |     - name: opensuse
20 |       versions:
21 |         - all
22 |     - name: GenericBSD
23 |       versions:
24 |         - all
25 |     - name: FreeBSD
26 |       versions:
27 |         - all
28 |     - name: Ubuntu
29 |       versions:
30 |         - all
31 |     - name: SLES
32 |       versions:
33 |         - all
34 |     - name: GenericLinux
35 |       versions:
36 |         - all
37 |     - name: Debian
38 |       versions:
39 |         - all
40 |   galaxy_tags:
41 |     - development
42 |     - web
43 |     - php
44 |     - xdebug
45 |     - debug
46 |     - profile
47 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2017 Jeff Geerling
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of
 6 | this software and associated documentation files (the "Software"), to deal in
 7 | the Software without restriction, including without limitation the rights to
 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 9 | the Software, and to permit persons to whom the Software is furnished to do so,
10 | subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21 | 


--------------------------------------------------------------------------------
/.github/workflows/release.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | # This workflow requires a GALAXY_API_KEY secret present in the GitHub
 3 | # repository or organization.
 4 | #
 5 | # See: https://github.com/marketplace/actions/publish-ansible-role-to-galaxy
 6 | # See: https://github.com/ansible/galaxy/issues/46
 7 | 
 8 | name: Release
 9 | 'on':
10 |   push:
11 |     tags:
12 |       - '*'
13 | 
14 | defaults:
15 |   run:
16 |     working-directory: 'geerlingguy.php-xdebug'
17 | 
18 | jobs:
19 | 
20 |   release:
21 |     name: Release
22 |     runs-on: ubuntu-latest
23 |     steps:
24 |       - name: Check out the codebase.
25 |         uses: actions/checkout@v4
26 |         with:
27 |           path: 'geerlingguy.php-xdebug'
28 | 
29 |       - name: Set up Python 3.
30 |         uses: actions/setup-python@v5
31 |         with:
32 |           python-version: '3.13'  # Can't go to 3.14+ until Ansible 13.x
33 | 
34 |       - name: Install Ansible.
35 |         run: pip3 install ansible-core
36 | 
37 |       - name: Trigger a new import on Galaxy.
38 |         run: >-
39 |           ansible-galaxy role import --api-key ${{ secrets.GALAXY_API_KEY }}
40 |           $(echo ${{ github.repository }} | cut -d/ -f1) $(echo ${{ github.repository }} | cut -d/ -f2)
41 | 


--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: CI
 3 | 'on':
 4 |   pull_request:
 5 |   push:
 6 |     branches:
 7 |       - master
 8 |   schedule:
 9 |     - cron: "0 7 * * 4"
10 | 
11 | defaults:
12 |   run:
13 |     working-directory: 'geerlingguy.php-xdebug'
14 | 
15 | jobs:
16 | 
17 |   lint:
18 |     name: Lint
19 |     runs-on: ubuntu-latest
20 |     steps:
21 |       - name: Check out the codebase.
22 |         uses: actions/checkout@v4
23 |         with:
24 |           path: 'geerlingguy.php-xdebug'
25 | 
26 |       - name: Set up Python 3.
27 |         uses: actions/setup-python@v5
28 |         with:
29 |           python-version: '3.13'  # Can't go to 3.14+ until Ansible 13.x
30 | 
31 |       - name: Install test dependencies.
32 |         run: pip3 install yamllint
33 | 
34 |       - name: Lint code.
35 |         run: |
36 |           yamllint .
37 | 
38 |   molecule:
39 |     name: Molecule
40 |     runs-on: ubuntu-latest
41 |     strategy:
42 |       matrix:
43 |         distro:
44 |           - rockylinux9
45 |           - ubuntu2204
46 |           - debian11
47 | 
48 |     steps:
49 |       - name: Check out the codebase.
50 |         uses: actions/checkout@v4
51 |         with:
52 |           path: 'geerlingguy.php-xdebug'
53 | 
54 |       - name: Set up Python 3.
55 |         uses: actions/setup-python@v5
56 |         with:
57 |           python-version: '3.13'  # Can't go to 3.14+ until Ansible 13.x
58 | 
59 |       - name: Install test dependencies.
60 |         run: pip3 install ansible molecule molecule-plugins[docker] docker
61 | 
62 |       - name: Run Molecule tests.
63 |         run: molecule test
64 |         env:
65 |           PY_COLORS: '1'
66 |           ANSIBLE_FORCE_COLOR: '1'
67 |           MOLECULE_DISTRO: ${{ matrix.distro }}
68 | 


--------------------------------------------------------------------------------
/.github/workflows/stale.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: Close inactive issues
 3 | 'on':
 4 |   schedule:
 5 |     - cron: "55 1 * * 6"  # semi-random time
 6 | 
 7 | jobs:
 8 |   close-issues:
 9 |     runs-on: ubuntu-latest
10 |     permissions:
11 |       issues: write
12 |       pull-requests: write
13 |     steps:
14 |       - uses: actions/stale@v8
15 |         with:
16 |           days-before-stale: 120
17 |           days-before-close: 60
18 |           exempt-issue-labels: bug,pinned,security,planned
19 |           exempt-pr-labels: bug,pinned,security,planned
20 |           stale-issue-label: "stale"
21 |           stale-pr-label: "stale"
22 |           stale-issue-message: |
23 |             This issue has been marked 'stale' due to lack of recent activity. If there is no further activity, the issue will be closed in another 30 days. Thank you for your contribution!
24 |             
25 |             Please read [this blog post](https://www.jeffgeerling.com/blog/2020/enabling-stale-issue-bot-on-my-github-repositories) to see the reasons why I mark issues as stale.
26 |           close-issue-message: |
27 |             This issue has been closed due to inactivity. If you feel this is in error, please reopen the issue or file a new issue with the relevant details.
28 |           stale-pr-message: |
29 |             This pr has been marked 'stale' due to lack of recent activity. If there is no further activity, the issue will be closed in another 30 days. Thank you for your contribution!
30 |             
31 |             Please read [this blog post](https://www.jeffgeerling.com/blog/2020/enabling-stale-issue-bot-on-my-github-repositories) to see the reasons why I mark issues as stale.
32 |           close-pr-message: |
33 |             This pr has been closed due to inactivity. If you feel this is in error, please reopen the issue or file a new issue with the relevant details.
34 |           repo-token: ${{ secrets.GITHUB_TOKEN }}
35 | 


--------------------------------------------------------------------------------
/tasks/main.yml:
--------------------------------------------------------------------------------
 1 | ---
 2 | - name: Include OS-specific variables.
 3 |   include_vars: "{{ ansible_facts.os_family }}.yml"
 4 | 
 5 | - name: Define php_xdebug_module_path.
 6 |   set_fact:
 7 |     php_xdebug_module_path: "{{ __php_xdebug_module_path }}"
 8 |   when: php_xdebug_module_path is not defined
 9 | 
10 | - name: Define php_xdebug_config_filename.
11 |   set_fact:
12 |     php_xdebug_config_filename: "{{ __php_xdebug_config_filename }}"
13 |   when: php_xdebug_config_filename is not defined
14 | 
15 | - name: Ensure dependencies for building from source are installed (RedHat).
16 |   yum:
17 |     name: '@development'
18 |     state: present
19 |   when: ansible_facts.os_family == 'RedHat'
20 | 
21 | - name: Ensure dependencies for building from source are installed (Debian).
22 |   apt:
23 |     name: build-essential
24 |     state: present
25 |   when: ansible_facts.os_family == 'Debian'
26 | 
27 | - name: Untar Xdebug.
28 |   unarchive:
29 |     src: "https://xdebug.org/files/xdebug-{{ php_xdebug_version }}.tgz"
30 |     dest: "{{ workspace }}"
31 |     creates: "{{ workspace }}/xdebug-{{ php_xdebug_version }}"
32 |     copy: false
33 |     mode: 0755
34 | 
35 | - name: Build Xdebug.
36 |   command: >
37 |     {{ item }}
38 |     chdir={{ workspace }}/xdebug-{{ php_xdebug_version }}
39 |     creates={{ workspace }}/xdebug-{{ php_xdebug_version }}/modules/xdebug.so
40 |   with_items:
41 |     - phpize
42 |     - ./configure
43 |     - make
44 | 
45 | - name: Ensure Xdebug module path exists.
46 |   file:
47 |     path: "{{ php_xdebug_module_path }}"
48 |     state: directory
49 |     owner: root
50 |     group: root
51 |     mode: 0755
52 | 
53 | - name: Move Xdebug module into place.
54 |   copy:
55 |     src: "{{ workspace }}/xdebug-{{ php_xdebug_version }}/modules/xdebug.so"
56 |     dest: "{{ php_xdebug_module_path }}/xdebug-{{ php_xdebug_version }}.so"
57 |     remote_src: true
58 |     mode: 0644
59 |   notify: restart webserver
60 | 
61 | - include_tasks: configure.yml
62 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Ansible Role: PHP-XDebug
 2 | 
 3 | [![CI](https://github.com/geerlingguy/ansible-role-php-xdebug/actions/workflows/ci.yml/badge.svg)](https://github.com/geerlingguy/ansible-role-php-xdebug/actions/workflows/ci.yml)
 4 | 
 5 | Installs PHP [XDebug](http://xdebug.org/) on Linux servers.
 6 | 
 7 | ## Requirements
 8 | 
 9 | Prior to running this role, make sure the `php-devel` and `@Development Tools` (for RHEL/CentOS) or `php5-dev` + `build-essential` packages (for Debian/Ubuntu) are present on the system, as they are required for the build of Xdebug.
10 | 
11 | ## Role Variables
12 | 
13 | Available variables are listed below, along with default values (see `defaults/main.yml`):
14 | 
15 |     workspace: /root
16 | 
17 | Where Xdebug setup files will be downloaded and built.
18 | 
19 |     php_xdebug_version: 3.3.2
20 | 
21 | The version of Xdebug to be installed (see [Updates](https://xdebug.org/updates.php) for a current listing).
22 | 
23 |     php_xdebug_default_enable: 1
24 |     php_xdebug_coverage_enable: 1
25 | 
26 | Whether to enable XDebug coverage and default exception handling or not. Disable these for slightly improved PHP performance, enable these to use XDebug to the fullest extent.
27 | 
28 |     php_xdebug_module_path: /usr/lib64/php/modules
29 | 
30 | The path where `xdebug.so` will be installed.
31 | 
32 |     php_xdebug_remote_enable: "false"
33 | 
34 | Whether remote debugging is enabled.
35 | 
36 |     php_xdebug_remote_connect_back: "false"
37 | 
38 | If this is set to true, Xdebug will respond to any request from any IP address; use only for local development on non-public installations!
39 | 
40 |     php_xdebug_remote_host: localhost
41 |     php_xdebug_remote_port: "9000"
42 | 
43 | The host and port on which Xdebug will listen.
44 | 
45 |     php_xdebug_remote_log: /tmp/xdebug.log
46 | 
47 | The location of the xdebug log (useful if you're having trouble connecting).
48 | 
49 |     php_xdebug_idekey: sublime.xdebug
50 | 
51 | The IDE key to use in the URL when making Xdebug requests (e.g. `http://example.local/?XDEBUG_SESSION_START=sublime.xdebug`).
52 | 
53 |     php_xdebug_max_nesting_level: 256
54 | 
55 | The maximimum function nesting level before Xdebug bails and throws a fatal exception.
56 | 
57 |     php_xdebug_cli_disable: false
58 | 
59 | (Debian/Ubuntu ONLY) Disable xdebug for the CLI SAPI.
60 | 
61 | ## Dependencies
62 | 
63 |   - geerlingguy.php
64 | 
65 | ## Example Playbook
66 | 
67 |     - hosts: webservers
68 |       roles:
69 |         - { role: geerlingguy.php-xdebug }
70 | 
71 | ## License
72 | 
73 | MIT / BSD
74 | 
75 | ## Author Information
76 | 
77 | This role was created in 2014 by [Jeff Geerling](http://www.jeffgeerling.com/), author of [Ansible for DevOps](https://www.ansiblefordevops.com/).
78 | 


--------------------------------------------------------------------------------