Skip to content

Commit bc583c5

Browse files
committed
[Docs] Migrate phpstorm docs page
1 parent c95a39c commit bc583c5

File tree

4 files changed

+230
-0
lines changed

4 files changed

+230
-0
lines changed

data/migratedPages.yml

+3
Original file line numberDiff line numberDiff line change
@@ -1399,6 +1399,9 @@ Security:Unauthorised_access:
13991399
Sending_custom_Push_Notifications_to_the_Moodle_App:
14001400
- filePath: "/docs/moodleapp/development/custom-push-notifications.md"
14011401
slug: "/docs/moodleapp/development/custom-push-notifications"
1402+
Setting_up_PhpStorm:
1403+
- filePath: "/docs/guides/devtools/phpstorm"
1404+
slug: "/docs/guides/devtools/phpstorm"
14021405
Setting_up_development_environment:
14031406
- filePath: "general/development/gettingstarted.md"
14041407
slug: "general/development/gettingstarted"

docs/guides/devtools/index.md

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

project-words.txt

+4
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Ionicons
2222
JWKS
2323
MAINNODE
2424
MDL
25+
MDLNET
2526
MDLQA
2627
MDLSITE
2728
Moodle
@@ -52,6 +53,7 @@ TODO
5253
Triaged
5354
Untriaged
5455
WCAG
56+
WPQA
5557
Xdebug
5658
XMLDB
5759
XMPPHP
@@ -72,6 +74,7 @@ calculatedmulti
7274
calculatedsimple
7375
capabilityname
7476
captype
77+
catched
7578
classname
7679
clientid
7780
clsx
@@ -181,6 +184,7 @@ passwordunmask
181184
pdftoppm
182185
perfdebug
183186
pgsql
187+
phar
184188
phpcs
185189
phpdoc
186190
phpdocs

0 commit comments

Comments
 (0)