Updated 2 months ago by Brienne Kordis

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.client_host = ""
#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.

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

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)
      url: "{{ primary_url }}/{{ endpoint }}"
      method: POST
        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

Updated by Brienne Kordis 2 months ago · 22 revisions