{{last_updated_at}} by {{last_updated_by}}

Debugging CiviCRM cheatsheet¶

Command-line runs of PHPUnit:¶

From a buildkit civiroot, run a specific file's tests::

CIVICRM_UF=UnitTests phpunit5 tests/phpunit/CRM/Core/BAO/AddressTest.php

You can also limit to a single test by filtering on name:

CIVICRM_UF=UnitTests phpunit5 tests/phpunit/CRM/Core/BAO/AddressTest.php --filter testShared

With XDebug¶

Web Browser¶

• Install the xdebug extension (e.g. sudo apt install php7.4-xdebug).
• Configure xdebug by copying the values below to /etc/php/7.4/fpm/conf.d/xdebug.ini:

xdebug.mode=debug,develop
xdebug.start_with_request=trigger
xdebug.client_port=9000
xdebug.client_host = "127.0.0.1"
xdebug.log=/var/log/xdebug.log
#xdebug.mode=profile
#xdebug.output_dir = "/home/jon/temp/xdebug"

• Install a plugin for your browser, like "XDebug Helper for Firefox".

  • In the plugin's configuration, set the IDE key to VSCODE.

• If one does not already exist, create a launch.json file within the .vscode folder (make a new folder if it does not yet exist) at the root of your codebase. What goes into the launch.json file depends on whether you are debugging a a site created with the civibuild command or one that was not built with that command. Here are examples of a civibuild launch.json and a non-civibuild launch.json. Note that the "max-depth" on the "Listen for XDebug" configuration can be changed to delve deeper into the values that are returned (i.e. a depth of 6 will return more levels of a nested array than a depth of 3).

To debug, you must turn on the debugger in VS Code, then enable debugging in the address bar for the requests in question.

Web Browser - remote debugging¶

To debug on a remote server, ensure you have local debugging working first.

Server-side setup¶

• sudo apt install php{{php_version}}-xdebug (I should add this to group_vars/all.yml so it's everywhere).
• Need to add this somewhere that makes sense in PHP config:

xdebug.mode=debug
xdebug.start_with_request=trigger

• Restart PHP.

Client side setup¶

• In your VS Code plugins screen, you need to select Install in SSH for the PHP Debug and PHP Intelephense plugins.
• Using the new Remote Explorer sidebar icon in VS Code, select the server you'd like to connect to.
• If you've already debugged on this site before, you should be able to expand the server and see a workspace file (see screenshot below). Click one of the connect icons.
• If you haven't debugged on this site before, follow First Time instructions below. Otherwise, debug as normal (make sure your Firefox "debug" icon is turned on).

First Time¶

• Click Open Folder and navigate to the site's gitroot (usually the same as webroot, but for D8+ it's the folder above web so you can also debug in vendor).
• Select File menu » Save Workspace As and store a workspace file in your home directory.
• Go to your Extensions sidebar, search for php and click Install in SSH next to PHP Debug and PHP Intelephense.
  • For Drupal sites, also Install in SSH the Drupal Syntax Highlighting extension or you can't debug .module files.
• Go to the VS Code "debug" sidebar. Click create a launch.json file and then select workspace, then PHP.
• (Optional) in the Remote Explorer sidebar, under the server you're connected to, right-click the entry that doesn't say "Workspace" in it and select Remove from Recent List to only keep workspace entries.

civicrm-buildkit (mod_php)¶

The instructions above assume php-fpm. To also debug mod_php (e.g. civicrm-buildkit), do the following:

• Use the same configuration file as under "Web Browser", but at /etc/php/7.4/apache2/conf.d/xdebug.ini.
• Edit /etc/php/7.4/apache2/conf.d/xdebug.ini and change the client port from 9000 to 9001.

Command Line (phpunit)¶

• You need to have XDebug otherwise configured for CLI. Use the same configuration file as under "Web Browser", but at /etc/php/7.4/cli/conf.d/xdebug.ini.

  • Also change xdebug.mode=debug,develop to avoid some unnecessary warning noise.

• You need to start a debugging session in VS Code with "Listen for XDebug".

• Depending on your VS Code setup, you may need to listen on a different port (I can use the same port for FPM but not mod_php).

Once you've got all that:

env CIVICRM_UF=UnitTests XDEBUG_SESSION=VSCODE phpunit7 /home/jon/local/civicrm-buildkit/build/dmaster/web/sites/all/modules/civicrm/tests/phpunit/CRM/Core/BAO/ActionScheduleTest.php --filter testMembershipJoinDateMinutesUnit

phpunit for extensions:¶

This is for core extensions, I'll figure out (again) non-core extensions later. But from your civiroot:

CIVICRM_UF=UnitTests phpunit8 --bootstrap ext/afform/mock/tests/phpunit/bootstrap.php ext/afform/mock/tests/phpunit/api/v4/AfformContactUsageTest.php 

Command-line runs of standalone scripts¶

env XDEBUG_SESSION=VSCODE php myscript.php

Debugging REST API calls in Ansible/curl¶

Add an additional POST argument XDEBUG_SESSION=VSCODE. In curl, just add -d 'XDEBUG_SESSION=VSCODE' anywhere in your command.

For Ansible, this might look like:

  - name: Shut up about Civi extensions (warnings only, 7 days)
    uri:
      url: "{{ primary_url }}/{{ endpoint }}"
      method: POST
      body:
        XDEBUG_SESSION: VSCODE
        entity: StatusPreference
        action: create
        json: "{{ {'name': 'checkExtensionsUpdates', 'ignore_severity': 3, 'hush_until': seven_days_hence } | to_json }}"
        api_key: "{{ crm_api_key }}"
        key: "{{ crm_site_key }}"
      body_format: form-urlencoded
      return_content: yes

Debugging in PHP file_get_contents() (e.g. check_civicrm.php)¶

Add XDEBUG_SESSION=VSCODE as a GET argument, it works even on a POST request. Pairs well with a remote debugging session.
e.g.:

$url = "$prot://$host_address/$path/System/check?XDEBUG_SESSION=VSCODE";

Debugging JavaScript¶

While you can open up the Developer Tools on a browser (by right clicking on the window and then clicking Inspect) and debug the code directly there, it might be preferable to set up a debugging environment within an IDE, i.e. Visual Studio Code. To do so:

1. Open up your launch.json file (Need to set one up? There are non-civibuild and Civibuild options)
2. Within the ”configurations:” array, add a comma after the last curly brace and then paste in:

    {
      "type": "msedge",
      "request": "attach",
      "name": "Attach to browser",
      "port": 9222
    }

• If you’d prefer to debug on chrome, use ”type”: “chrome”
  1. Within your terminal, run the following command:

/usr/bin/google-chrome --remote-debugging-port=9222 –user-data-dir=remote-debug-profile

• /usr/bin/google-chrome is the path of the Google Chrome Binary on Linux. For other operating systems, check out this comment, but note that the exact name might be different (i.e. google-chrome1 vs google-chrome). You can always cd through the path it recommends to find the exact match for either Chrome or MSEdge.

1. Within VS Code, go to the Run and Debug tab, and from the drop down menu at the top, select “Attach to browser” and start the debugger.

   • Note that the command given in the previous step is configured to open up a new browser, but these arguments (and more) can be customized. See the documentation

2. The new browser window (or tab, depending on your settings) is now configured to be the debuggee-yes, that’s the technical term- so you can set breakpoints and debug within VS Code!