Coding Style Guide
PHP
CodeIgniter4 defines a set of coding conventions in its PHP Coding Style Guide, which is based on the PHP-FIG PSR-1: Basic Coding Standard and PSR-2: Coding Style Guide, but with some differences. While there is no requirement to follow these conventions in application code, the CodeIgniter community recommends it.
The main difference between the CodeIgniter4 Coding Style Guide, PSR-1, PSR-2, and many other contemporary style guides is that they recommend using tabs instead of spaces for indentation. This is rather uncommon these days, with spaces being the far more popular choice.
To remove the burden of choice, we can lint and format our PHP code against the CodeIgniter standard (including HTML within <?php tags) using the PHP_CodeSniffer library.
PHP_CodeSniffer analyses PHP files and detects violations of defined coding standards and can, in some cases, fix them.
CodeIgniter4 provides its style guide as a coding standard for use with PHP_CodeSniffer in the CodeIgniter4-Standard repo.
To get automatic linting and code formatting working in VS Code, several installation and set-up steps must be carried out. Unfortunately, it is a bit of a pain to install, but worth the effort to help ensure coding consistency.
Note: we can script these steps relatively easily as part of the Ansible playbook or a simple bash script.
1. Install PHP_CodeSniffer
Install the library globally within WSL using composer:
composer global require "squizlabs/php_codesniffer=*"
This will install the two required executable scripts (phpcs and phpcbf) into the ~/.config/composer/vendor/bin directory.
We need to add this bin directory to our PATH in WSL. Do this by adding the following to your ~/.profile:
if [ -d "$HOME/.config/composer/vendor/bin" ] ; then
PATH="$HOME/.config/composer/vendor/bin:$PATH"
fi
Reload the profile by issuing the following command:
. ~/.profile
Finally, check phpcs is working by issuing the phpcs -i command. You should see something like the following:
$ phpcs -i
The installed coding standards are PSR2, PEAR, PSR12, MySource, Squiz, Zend and PSR1
2. Install the CodeIgniter4-Standard
Install the standard globally using composer:
composer global require codeigniter4/codeigniter4-standard
Create a symbolic link to the newly installed CodeIgniter4 standard from the PHP_CodeSniffer Standards directory:
ln -s ~/.config/composer/vendor/codeigniter4/codeigniter4-standard/CodeIgniter4/ \
~/.config/composer/vendor/squizlabs/php_codesniffer/src/Standards/CodeIgniter4
Check to see if the new CodeIgniter4 standard is available to phpcs:
$ phpcs -i
The installed coding standards are PSR2, PEAR, PSR12, MySource, Squiz, CodeIgniter4, Zend and PSR1
3. Install PHP Sniffer extension in VS Code
VS Code has several PHP_CodeSniffer extensions of varying quality. I have tried a few and PHP Sniffer by wongjn appears to offer a good balance of reliability and features.
First, install PHP Sniffer into VS Code.
Next, configure the extension to reference the CodeIgniter4 standard we installed. Do this by opening VS Code settings (hit Ctrl+,) then search for phpSniffer.standard.
Select the Remote tab to apply the setting to the WSL instance rather than globally as a User setting or as a Workspace setting (note, we can add this setting to Workspace settings once we have scripted installation of PHP_CodeSniffer; until we do that, we don’t want to commit the setting to git, therefore we add the setting to Remote rather than Workspace).
Tip: hover over the settings tabs to see exactly where a given VS Code settings file is stored.
Set the PHP Sniffer: Standard setting to CodeIgniter4.
Check the Remote settings JSON file by hitting Ctrl+Shift+P and searching for Preferences: Open Remote Settings. It should have the following in there:
{
"phpSniffer.standard": "CodeIgniter4"
}
You can tell whether VS Code is using the CodeIgniter4 standard by opening a PHP file and checking the problems pane. When PHP Sniffer detects problems, it will provide details in this pane along with a reference to which standard the problem is defined in.
4. Install Recommended Extensions
VS Code can advise developers of recommended extensions for a loaded workspace by specifying them in the [workspace]/.vscode/extensions.json file.
You can inspect and install these recommended extensions by opening the command palette (Ctrl+Shift+P) and searching for Show Recommended Extensions. The list will appear in the extensions pane.
Rationale for recommended extensions
- Better Comments: provides syntax highlighting for comments, including DocBlocks. Makes working with these comments clearer and easier.
- EditorConfig for VS Code: overrides user/workspace settings with settings found in the
.editorconfigfile which brings consistency to code. Works in many code editors, not just VS Code. - GitLens: Greatly enhanced Git capabilities in VS Code negating (to a certain extent) the need for a separate GUI and/or CLI Git commands.
- PHP DocBlocker: CodeIgniter4 makes extensive use of structured PHP DocBlocks, and the coding standard requires them. This extension helps with writing and structuring them correctly.
- PHP Intelephense: High performance PHP code intellisense. A great improvement over the older PHP IntelliSense extension.
- PHP Sniffer: Implementation of PHP_CodeSniffer in VS Code. This is essential for linting and formatting against CodeIgniter4 Coding Style Guide.
- Prettier: The de facto standard code formatter and style guide for JavaScript. It is highly opinionated but extremely popular. In addition to JavaScript it includes a formatter for JSON, CSS, SCSS, HTML, Markdown, and YAML (among others).
- Rewrap: Reformats comments, comment blocks, and text (e.g., Markdown) to wrap at a configured column (typically column 80). It can also automatically hard-wrap comment lines at the configured column by setting
"rewrap.autoWrap.enabled": true. See the Rewrap website for an explanation and demo of features and auto-wrap. It is extremely useful for composing and reformatting comment blocks and Markdown.
HTML, CSS, JavaScript, Markdown
HTML in a CodeIgniter4 application is primarily embedded into PHP files, which are linted and formatted by PHP_CodeSniffer.
Standalone HTML, CSS, SCSS, JavaScript (including JSON), and Markdown files are formatted by the default Prettier settings (as long as the Prettier extension is installed).
Prettier respects .editorconfig settings and, in this project, these are the only settings that deviate from the Prettier defaults.