|
| 1 | +--- |
| 2 | +title: Setting up PhpStorm |
| 3 | +tags: |
| 4 | + - PhpStorm |
| 5 | + - Tools |
| 6 | +--- |
| 7 | +<!-- markdownlint-disable MD029 --> |
| 8 | +[PhpStorm](http://www.jetbrains.com/phpstorm/) is a commercial IDE, it is arguably the best IDE for PHP developers with features such as code completion, code inspection, phpunit support, Behat support, database editor, debugger, etc. |
| 9 | + |
| 10 | +## Installation |
| 11 | + |
| 12 | +### OS X |
| 13 | + |
| 14 | +Do not install Java manually, download a PhpStorm package with bundled java instead. |
| 15 | + |
| 16 | +## General settings |
| 17 | + |
| 18 | +- Uncheck "Missing @throws tag(s)" setting in "Preferences / Editor / Inspections / PHP / PHPDoc" |
| 19 | +- Check "Strip trailing whitespace on Modified Lines" in "Preferences / Editor / General" |
| 20 | +- Check "Show line numbers" in "Preferences / Editor / Appearance" |
| 21 | +- Add Moodle database prefix by create file .phpstorm.meta.php in the project root directory, put the code below to enable PhpStorm recognized {table_name} as Database table: |
| 22 | + |
| 23 | +```php |
| 24 | +<?php |
| 25 | + |
| 26 | +namespace PHPSTORM_META { |
| 27 | + override( |
| 28 | + // Virtual function to indicate that all SQL |
| 29 | + // injections will have the following replacement rules. |
| 30 | + sql_injection_subst(), |
| 31 | + map([ |
| 32 | + '{' => "mdl_", // all `{` in injected SQL strings will be replaced with a prefix |
| 33 | + '}' => '', // all `}` will be replaced with an empty string |
| 34 | + ])); |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +## Bug tracker integration |
| 39 | + |
| 40 | +- Add tracker linking in "Preferences / Version control / Issue Navigation" |
| 41 | +- Set Issue ID to "MDL-\d+|CONTRIB-\d+|MOBILE-\d+|MDLSITE-d+|MDLQA-\d+|UX-\d+|MDLNET-\d+|WPQA-\d+" and Issue link to "https://tracker.moodle.org/browse/$0" or just click on 'add Jira pattern' and paste "https://tracker.moodle.org" |
| 42 | + |
| 43 | +## Code formatting |
| 44 | + |
| 45 | +- Setup coding style to use all rules from [Coding style](/general/development/policies/codingstyle) in "Preferences / Code Style / PHP" (or simply import from https://github.com/enovation/moodle-utils/blob/master/phpstorm-config/Moodle.xml) - this will allow you to use automatic code formatting and it does nice code formatting on copy/paste. |
| 46 | +- Set line separator to "Unix and OS X (\n)" in "Preferences / Code Style / General". |
| 47 | +- Set right margin to 132 or 180 in "Preferences / Code Style / General". |
| 48 | + |
| 49 | +## Tips & Tricks |
| 50 | + |
| 51 | +- Use `/** @var admin_root $ADMIN */` to autofill $ADMIN->... |
| 52 | +- Remove SQL syntax inspection errors for Moodle tables surrounded by curly brackets (like: `SELECT * FROM {user}`) by adding `\{(\w+)\}` to Tools > Databases > user parameters |
| 53 | +(more info: https://blog.jetbrains.com/phpstorm/2014/11/database-language-injection-configuration/ , and a "feature request" to improve it: https://youtrack.jetbrains.com/issue/WI-4123 ) |
| 54 | +- You can deactivate warnings for specific exceptions (in particular the coding_exception, which is unlikely to be catched in your code) by going to Settings > PHP and add them to 'Unchecked Exceptions' under the 'Analysis' tab |
| 55 | + |
| 56 | +## Moodle code checker |
| 57 | + |
| 58 | +Follow the instructions in the [README](https://github.com/moodlehq/moodle-local_codechecker/blob/master/README.md#ide-integration) |
| 59 | + |
| 60 | +## PHPUnit integration |
| 61 | + |
| 62 | +1. Install [PHPUnit](https://docs.moodle.org/dev/PHPUnit) via Composer |
| 63 | +1. Tell PHPStorm where is composer - go to "Preferences / PHP / Composer", fill in "Path to PHP executable", "Path to composer.phar", "Path to composer.json" and make sure the option "Add packages as libraries" is enabled. |
| 64 | +1. Go to "Run / Edit configurations" |
| 65 | +1. Add PHPUnit configuration by clicking on "+" |
| 66 | +1. Click "Use alternative configuration file" and select your phpunit.xml file |
| 67 | +1. Go to "Run / Run ..." and select your new PHPUnit configuration to run |
| 68 | + |
| 69 | +## Database editor |
| 70 | + |
| 71 | +1. Click on the "Database" tab to see the database window |
| 72 | +1. Click "+" in the top left and add "Database source" for your database |
| 73 | +1. Note: click on the link to download the necessary drivers directly from IDE |
| 74 | + |
| 75 | +## JavaScript Development |
| 76 | + |
| 77 | +You can work on JavaScript development by add Grunt configuration: |
| 78 | + |
| 79 | +1. Install Watchman - https://facebook.github.io/watchman/docs/install.html |
| 80 | +1. From the main Moodle directory open terminal and run: |
| 81 | + |
| 82 | +```shell |
| 83 | +npm install -g grunt-cli |
| 84 | +npm install |
| 85 | +``` |
| 86 | + |
| 87 | +3. Open "Edit configuration" |
| 88 | +3. Add new Grunt Task |
| 89 | +3. Verify that the node version is set with proper version for the current Moodle version |
| 90 | +3. In Tasks select watch |
| 91 | +3. Save the Grunt task |
| 92 | +3. Verify that in config.php the setting is not comment |
| 93 | + |
| 94 | +```php |
| 95 | +$CFG->cachejs = false; |
| 96 | +``` |
| 97 | + |
| 98 | +9. Click on run icon |
| 99 | +9. Happy JavaScript development |
| 100 | + |
| 101 | +## Debugging with Xdebug with docker containers |
| 102 | + |
| 103 | +This is very helpful when developing locally and you need to go step by step on the execution path of something of your interest. |
| 104 | + |
| 105 | +If you're using [moodle-docker](https://github.com/moodlehq/moodle-docker), please refer to its section about [live debugging](https://github.com/moodlehq/moodle-docker#using-xdebug-for-live-debugging) before taking this section. If you are using a custom docker container, the web server container should be based on Debian-like to have the following instructions compatible. |
| 106 | + |
| 107 | +These are the steps for configuring Xdebug to live debugging your code: |
| 108 | + |
| 109 | +1. Be sure containers are stopped. |
| 110 | +1. If you're using Docker on Mac or Windows, you can omit this step. So, only if you're using Docker on linux: Create a file named `add-host.docker.internal-to-etc-hosts` with execution rights on the Moodle root: |
| 111 | + |
| 112 | +```php |
| 113 | +#!/bin/bash |
| 114 | +apt update |
| 115 | +apt install -y iproute2 |
| 116 | +apt clean |
| 117 | +apt auto-clean |
| 118 | +HOST_DOMAIN="host.docker.internal" |
| 119 | +ping -q -c1 $HOST_DOMAIN > /dev/null 2>&1 |
| 120 | +if [ $? -ne 0 ]; then |
| 121 | + HOST_IP=$(ip route | awk 'NR==1 {print $3}') |
| 122 | + echo -e "$HOST_IP\t$HOST_DOMAIN" >> /etc/hosts |
| 123 | +fi |
| 124 | +``` |
| 125 | + |
| 126 | +3. Edit the `base.yml</syntaxhighlight> from the moodle-docker root (or equivalent from your custom docker container) to append these lines into the <syntaxhighlight lang="php">webserver: environment:` section: |
| 127 | + |
| 128 | +```php |
| 129 | + XDEBUG_CONFIG: |
| 130 | + idekey=phpstorm |
| 131 | + remote_enable=1 |
| 132 | + remote_mode=req |
| 133 | + remote_port=9000 |
| 134 | + remote_host=host.docker.internal |
| 135 | + remote_connect_back=0 |
| 136 | + PHP_IDE_CONFIG: |
| 137 | + serverName=moodle-local |
| 138 | +``` |
| 139 | + |
| 140 | +4. The result for the `webserver` service should be like this (this example is from moodle-docker): |
| 141 | + |
| 142 | +```php |
| 143 | + webserver: |
| 144 | + image: "moodlehq/moodle-php-apache:${MOODLE_DOCKER_PHP_VERSION}" |
| 145 | + depends_on: |
| 146 | + - db |
| 147 | + volumes: |
| 148 | + - "${MOODLE_DOCKER_WWWROOT}:/var/www/html" |
| 149 | + - "${ASSETDIR}/web/apache2_faildumps.conf:/etc/apache2/conf-enabled/apache2_faildumps.conf" |
| 150 | + environment: |
| 151 | + MOODLE_DOCKER_DBTYPE: pgsql |
| 152 | + MOODLE_DOCKER_DBNAME: moodle |
| 153 | + MOODLE_DOCKER_DBUSER: moodle |
| 154 | + MOODLE_DOCKER_DBPASS: "m@0dl3ing" |
| 155 | + MOODLE_DOCKER_BROWSER: firefox |
| 156 | + MOODLE_DOCKER_WEB_HOST: "${MOODLE_DOCKER_WEB_HOST}" |
| 157 | + XDEBUG_CONFIG: |
| 158 | + idekey=phpstorm |
| 159 | + remote_enable=1 |
| 160 | + remote_mode=req |
| 161 | + remote_port=9000 |
| 162 | + remote_host=host.docker.internal |
| 163 | + remote_connect_back=0 |
| 164 | + PHP_IDE_CONFIG: |
| 165 | + serverName=moodle-local |
| 166 | +``` |
| 167 | + |
| 168 | +5. Start the moodle-docker containers, or your custom ones. |
| 169 | +1. Only if you're using Docker on linux: From a PhpStorm terminal, run: `docker exec -it moodledocker_webserver_1 ./add-host.docker.internal-to-etc-hosts`. You have to see how packages are installed. |
| 170 | +1. In any type of host (Mac, Windows or linux): Check that `/etc/hosts</syntaxhighlight> has a line with <syntaxhighlight lang="php">host.docker.internal</syntaxhighlight>. You can do that with the command <syntaxhighlight lang="php">docker exec -it moodledocker_webserver_1 cat /etc/hosts` (if you have a custom container name, use the name for the webserver container). The result should be something like this: |
| 171 | + |
| 172 | +```php |
| 173 | +127.0.0.1 localhost |
| 174 | +::1 localhost ip6-localhost ip6-loopback |
| 175 | +fe00::0 ip6-localnet |
| 176 | +ff00::0 ip6-mcastprefix |
| 177 | +ff02::1 ip6-allnodes |
| 178 | +ff02::2 ip6-allrouters |
| 179 | +172.20.0.6 17dff32616ac |
| 180 | +172.20.0.1 host.docker.internal |
| 181 | +``` |
| 182 | + |
| 183 | +8. Go to your PhpStorm and go to `Run -> Edit configurations</syntaxhighlight> and select new <syntaxhighlight lang="php">PHP Remove Debug` |
| 184 | +1. Name: "xdebug localhost" (or what you want to) |
| 185 | +1. Configuration: check "Filter debug connection by IDE key" |
| 186 | +1. IDE key(session id): "phpstorm" |
| 187 | +1. Define a new server: |
| 188 | +1. Name: must be "moodle-local" |
| 189 | +1. Host: localhost |
| 190 | +1. Port: must be the port you're using for the web server. |
| 191 | +1. Debugger: use the default (Xdebug) |
| 192 | +1. Check "Use path mappings (...)" |
| 193 | +1. Set for your "Project files" Moodle root the "Absolute path on the server" as "/var/www/html" |
| 194 | +1. Apply and OK on this screen. This screen will be closed. |
| 195 | +1. Apply and OK on the next screen. Settings screen will be closed. |
| 196 | +1. Now, test that live debugging works. To do so, please: |
| 197 | +1. Put a breakpoint on /index.php file. |
| 198 | +1. Press telephone icon with a red symbol with title "Start listening for PHP Debug Connections": telephone should appear with some waves now. |
| 199 | +1. Open your browser and open your localhost Moodle site. |
| 200 | +1. Happy debugging ;-) |
| 201 | + |
| 202 | +Final note: Every time you start the webserver container, ONLY if you're using a linux host, you have to run the script for adding the host.docker.internal. |
| 203 | +Final note 2: This method also works if your docker containers are in a different host from localhost: you just need to specify the proper server name and port. |
| 204 | +Final note 3: This configuration also allows you to debug CLI scripts. |
| 205 | + |
| 206 | +## Useful plugins |
| 207 | + |
| 208 | +1. Php Inspections (EA Extended) - https://plugins.jetbrains.com/plugin/7622-php-inspections-ea-extended-/ |
| 209 | +1. SonarLint - https://plugins.jetbrains.com/plugin/7973-sonarlint/ |
| 210 | +1. Diff / Patch File Support - https://plugins.jetbrains.com/plugin/11957-diff--patch-file-support/ |
| 211 | +1. Handlebars/Mustache - https://plugins.jetbrains.com/plugin/6884-handlebars-mustache/ |
| 212 | +1. Markdown Navigator - https://plugins.jetbrains.com/plugin/7896-markdown-navigator/ |
| 213 | +1. PHP composer.json support - https://plugins.jetbrains.com/plugin/7631-php-composer-json-support/ |
| 214 | +1. PHP Advanced AutoComplete - https://plugins.jetbrains.com/plugin/7276-php-advanced-autocomplete/ |
0 commit comments