Project

General

Profile

Debugging CiviCRM cheatsheet » History » Version 27

Brienne Kordis, 02/15/2023 07:09 PM

1 7 Jon Goldberg
{{last_updated_at}} by {{last_updated_by}}
2
3 1 Jon Goldberg
# Debugging CiviCRM cheatsheet
4
5
### Command-line runs of PHPUnit:
6
7
From a buildkit civiroot, run a specific file's tests::
8
9 2 Jon Goldberg
```shell
10
CIVICRM_UF=UnitTests phpunit5 tests/phpunit/CRM/Core/BAO/AddressTest.php
11
```
12 1 Jon Goldberg
13
You can also limit to a single test by filtering on name:
14
15 2 Jon Goldberg
```shell
16
CIVICRM_UF=UnitTests phpunit5 tests/phpunit/CRM/Core/BAO/AddressTest.php --filter testShared
17
```
18 3 Jon Goldberg
19
### With XDebug
20 9 Jon Goldberg
21 14 Jon Goldberg
#### Web Browser
22
* Install the xdebug extension (e.g. `sudo apt install php7.4-xdebug`).
23
* Configure xdebug by copying the values below to `/etc/php/7.4/fpm/conf.d/xdebug.ini`:
24 2 Jon Goldberg
25 1 Jon Goldberg
```
26 12 Jon Goldberg
xdebug.mode=debug,develop
27
xdebug.start_with_request=trigger
28 1 Jon Goldberg
xdebug.client_port=9000
29
xdebug.client_host = "127.0.0.1"
30 10 Jon Goldberg
xdebug.log=/var/log/xdebug.log
31 12 Jon Goldberg
#xdebug.mode=profile
32 1 Jon Goldberg
#xdebug.output_dir = "/home/jon/temp/xdebug"
33
```
34 14 Jon Goldberg
35
* Install a plugin for your browser, like "XDebug Helper for Firefox".
36
 * In the plugin's configuration, set the IDE key to `VSCODE`.
37
38 22 Brienne Kordis
* 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](https://hq.megaphonetech.com/projects/commons/wiki/Launchjson_for_civibuild_sites) and a [non-civibuild launch.json](https://hq.megaphonetech.com/projects/commons/wiki/Launchjson_for_non-civibuild_sites). 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).
39 19 Brienne Kordis
40 14 Jon Goldberg
To debug, you must turn on the debugger in VS Code, then enable debugging in the address bar for the requests in question.
41
42 18 Jon Goldberg
#### civicrm-buildkit (mod_php)
43
The instructions above assume php-fpm.  To also debug mod_php (e.g. civicrm-buildkit), do the following:
44
* Use the same configuration file as under "Web Browser", but at `/etc/php/7.4/apache2/conf.d/xdebug.ini`.
45
* Edit `/etc/php/7.4/apache2/conf.d/xdebug.ini` and change the client port from `9000` to `9001`.
46
47 14 Jon Goldberg
#### Command Line (phpunit)
48
49 1 Jon Goldberg
* 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`.
50 15 Jon Goldberg
 * Also change `xdebug.mode=debug,develop` to avoid some unnecessary warning noise.
51 14 Jon Goldberg
52 5 Jon Goldberg
* You need to start a debugging session in VS Code with "Listen for XDebug".
53 1 Jon Goldberg
* 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).
54 2 Jon Goldberg
55
Once you've got all that:
56 1 Jon Goldberg
```shell
57 15 Jon Goldberg
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
58 2 Jon Goldberg
```
59 6 Jon Goldberg
60 8 Jon Goldberg
### Command-line runs of standalone scripts
61 6 Jon Goldberg
```shell
62 13 Jon Goldberg
env XDEBUG_SESSION=VSCODE php myscript.php
63 6 Jon Goldberg
```
64 16 Jon Goldberg
65
### Debugging REST API calls in Ansible/curl
66 17 Jon Goldberg
Add an additional POST argument `XDEBUG_SESSION=VSCODE`.  In curl, just add `-d 'XDEBUG_SESSION=VSCODE'` anywhere in your command.
67
68
For Ansible, this might look like:
69 16 Jon Goldberg
70
```yaml
71
  - name: Shut up about Civi extensions (warnings only, 7 days)
72
    uri:
73
      url: "{{ primary_url }}/{{ endpoint }}"
74
      method: POST
75
      body:
76
        XDEBUG_SESSION: VSCODE
77
        entity: StatusPreference
78
        action: create
79
        json: "{{ {'name': 'checkExtensionsUpdates', 'ignore_severity': 3, 'hush_until': seven_days_hence } | to_json }}"
80
        api_key: "{{ crm_api_key }}"
81
        key: "{{ crm_site_key }}"
82
      body_format: form-urlencoded
83
      return_content: yes
84
```
85 23 Jon Goldberg
86
### Debugging in PHP `file_get_contents()` (e.g. `check_civicrm.php`)
87
Add `XDEBUG_SESSION=VSCODE` as a `GET` argument, it works even on a `POST` request. Pairs well with a remote debugging session.
88
e.g.:
89
```php
90
$url = "$prot://$host_address/$path/System/check?XDEBUG_SESSION=VSCODE";
91
```
92 24 Brienne Kordis
93
### Debugging JavaScript
94
95
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:
96
97 27 Brienne Kordis
1. Open up your launch.json file (Need to set one up? There are [non-civibuild](https://hq.megaphonetech.com/projects/commons/wiki/Launchjson_for_non-civibuild_sites) and [Civibuild](https://hq.megaphonetech.com/projects/commons/wiki/Launchjson_for_civibuild_sites) options)
98 24 Brienne Kordis
1. Within the  `”configurations:”` array, add a comma after the last curly brace and then paste in:
99
100
``` json
101
    {
102
      "type": "msedge",
103
      "request": "attach",
104
      "name": "Attach to browser",
105
      "port": 9222
106
    }
107
```
108
   * If you’d prefer to debug on chrome, use `”type”: “chrome”`
109
1. Within your terminal, run the following command:
110
111
```bash
112 26 Brienne Kordis
/usr/bin/google-chrome --remote-debugging-port=9222 –user-data-dir=remote-debug-profile
113 24 Brienne Kordis
```
114
  * `/usr/bin/google-chrome` is the path of the Google Chrome Binary on Linux. For other operating systems, check out this [comment](https://forum.katalon.com/t/unknown-error-cannot-find-chrome-binary/9008/5), 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.
115
116
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. 
117
   * 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](https://code.visualstudio.com/docs/nodejs/browser-debugging#_launch-configuration-attributes)
118
119
1. 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!