Joomla Developer Manual
Manual Index
Coding Standards
An AI Overview¶
Coding standards are important for software development because they:
-
Improve code quality
- Coding standards help ensure that code is reliable, secure, and safe. They can also help reduce performance issues and security concerns that might arise from poor coding practices.
-
Make code more readable and maintainable
- Coding standards help make code easier to understand, read, and maintain. This can also make it easier for new developers to work with the code.
-
Speed up development
- Coding standards can help developers avoid common mistakes that can slow down coding processes.
-
Improve collaboration
- Coding standards can help facilitate collaboration among developers, even in large teams.
-
Ensure consistency
- Coding standards help ensure that code is consistent across projects. This can make it easier for developers to work together on the same projects.
-
Improve scalability
- Coding standards can help ensure that code can scale without becoming unmanageable.
-
Provide clear criteria for code reviews
- Coding standards can help provide clear criteria for code reviews, which can lead to more effective feedback.
Coding standards often include rules for indentation, line length, brace placement, and spacing.
Joomla uses the PSR-12 coding standard. You can enable this coding standard in your IDE and get hints if you're not following the coding standard or use an auto fix, too. We recommend that you follow this standard when developing your own extensions to stay compatible with core and to ensure your code will hopefully work with future versions.
PHP Code Sniffer¶
Please consult the current PHP_CodeSniffer source for information on this utility and how to install it. Be aware that the original source is abandoned but it may be listed by search engines. There are two scripts:
- phpcs detects violations of a coding standard and produces a report.
- phpcbf attempts to correct coding standards violations and produces a report on what it has done.
You can install the individual scripts or use composer to install them. You can also find them in a Joomla clone located in libraries/vendor/bin along with some other useful utilities.
Testing PHP Code Sniffer¶
If you put a global installation in your $PATH you can run the code sniffer from the command line in the root of a project. Try this to display a list of coding standards:
phpcs -i
The installed coding standards are MySource, PEAR, PSR1, PSR2, PSR12, Squiz and Zend
As an example the following command was used in an older project folder that used the former Joomla custom coding standard. Amongst other things it used tabs rather than spaces for layout. Many similar lines have been omitted below for brevity.
phpcs --standard=PSR12 .
FILE: /Users/ceford/git/j4xdemos-plg-toc/j4xdemostoc/j4xdemostoc.php
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 132 ERRORS AND 3 WARNINGS AFFECTING 116 LINES
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1 | WARNING | [ ] A file should declare new symbols (classes, functions, constants, etc.) and cause no other side effects, or it should execute logic with side effects, but should not do both. The
| | first symbol is defined on line 22 and the first side effect is on line 10.
1 | ERROR | [x] Header blocks must be separated by a single blank line
22 | ERROR | [ ] Each class must be in a namespace of at least one level (a top-level vendor name)
24 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
25 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
26 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
...
42 | ERROR | [x] Expected 1 space after closing parenthesis; found newline
...
48 | ERROR | [x] No space found after comma in argument list
48 | ERROR | [x] Expected 1 space after closing parenthesis; found newline
...
67 | ERROR | [x] Expected 0 spaces before closing parenthesis; 1 found
...
75 | ERROR | [x] Space after opening parenthesis of function call prohibited
75 | ERROR | [x] Expected 0 spaces before closing parenthesis; 1 found
...
138 | WARNING | [ ] Line exceeds 120 characters; contains 168 characters
139 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
139 | WARNING | [ ] Line exceeds 120 characters; contains 141 characters
...
156 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
157 | ERROR | [x] Expected 1 newline at end of file; 0 found
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 131 MARKED SNIFF VIOLATIONS AUTOMATICALLY
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Time: 123ms; Memory: 8MB
The previous example project contained a single php file and no css or js files. phpcs produces a report for each php, css and js file in a project. Here are some examples for css and js files:
FILE: /Users/ceford/git/j4x-demos-com-mediacat/com_mediacat/media/css/mediacat.css
----------------------------------------------------------------------------------
FOUND 33 ERRORS AFFECTING 32 LINES
----------------------------------------------------------------------------------
3 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
...
51 | ERROR | [x] Whitespace found at end of line
...
79 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
----------------------------------------------------------------------------------
PHPCBF CAN FIX THE 33 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------
FILE: /Users/ceford/git/j4x-demos-com-mediacat/com_mediacat/media/css/file-icon-classic.min.css
-----------------------------------------------------------------------------------------------
FOUND 0 ERRORS AND 1 WARNING AFFECTING 1 LINE
-----------------------------------------------------------------------------------------------
1 | WARNING | File appears to be minified and cannot be processed
-----------------------------------------------------------------------------------------------
FILE: /Users/ceford/git/j4x-demos-com-mediacat/com_mediacat/media/js/mediacat-site.js
-------------------------------------------------------------------------------------
FOUND 38 ERRORS AFFECTING 30 LINES
-------------------------------------------------------------------------------------
3 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
5 | ERROR | [x] Expected 1 space after FUNCTION keyword; 0 found
6 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
...
13 | ERROR | [x] Opening brace should be on a new line
...
29 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
29 | ERROR | [x] Expected at least 1 space before "+"; 0 found
29 | ERROR | [x] Expected at least 1 space after "+"; 0 found
...
36 | ERROR | [x] Spaces must be used to indent lines; tabs are not allowed
-------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 38 MARKED SNIFF VIOLATIONS AUTOMATICALLY
-------------------------------------------------------------------------------------
Command Variations¶
You can obtain help with phpcs commands:
phpcs --help
Exclude one or more files¶
Use a comma separated list of file patterns to exclude files from code style validation. Example
phpcs --standard=PSR12 --ignore='libraries/*' .
Exclude one or more rules¶
Joomla allows longer lines than the PSR standard, 560 instead of 120. The following command can be used to omit the long line warnings:
phpcs --standard=PSR12 --ignore='libraries/*' --exclude=Generic.Files.LineLength .
You can find the rule that is being violated with this command:
phpcs -s yourfile.php
Joomla Exceptions¶
For development of an extension using an IDE you may decide to use the PSR12 standard without any exceptions. Joomla has a custom ruleset that allows many exceptions. It is used for validation of the entire Joomla installation during system testing.
Fixing Violations¶
The single php file that FOUND 132 ERRORS AND 3 WARNINGS AFFECTING 116 LINES shown above can be mostly fixed as follows:
phpcbf --standard=PSR12 .
PHPCBF RESULT SUMMARY
-----------------------------------------------------------------------------------
FILE FIXED REMAINING
-----------------------------------------------------------------------------------
/Users/ceford/git/j4xdemos-plg-toc/j4xdemostoc/j4xdemostoc.php 131 4
-----------------------------------------------------------------------------------
A TOTAL OF 131 ERRORS WERE FIXED IN 1 FILE
-----------------------------------------------------------------------------------
Time: 232ms; Memory: 8MB
Running the phpcs utility again shows which problems remain:
phpcs --standard=PSR12 .
FILE: /Users/ceford/git/j4xdemos-plg-toc/j4xdemostoc/j4xdemostoc.php
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AND 3 WARNINGS AFFECTING 4 LINES
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1 | WARNING | A file should declare new symbols (classes, functions, constants, etc.) and cause no other side effects, or it should execute logic with side effects, but should not do both. The first
| | symbol is defined on line 23 and the first side effect is on line 11.
23 | ERROR | Each class must be in a namespace of at least one level (a top-level vendor name)
132 | WARNING | Line exceeds 120 characters; contains 168 characters
133 | WARNING | Line exceeds 120 characters; contains 141 characters
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Time: 127ms; Memory: 8MB
Conclusion: an extension coded for an earlier Joomla version and using different coding standard now needs some work!
Installation in IDEs¶
Most Integrated Development Environments can use the code sniffer as you work or when you save a file.
Installation in VSCode¶
In VSCode (and/or VScodium), select the Extensions icon, search for PHP_CodeSniffer and install it. It needs configuration:
- In Settings find PHP_CodeSniffer
- Set the PHP Code Sniffer → Exec: field to suit the location of your phpcs binary.
- In the PHP Code Sniffer: Standard list select PSR12.
Close and you are ready for action.
Some of the problems shown above can be fixed with PSR1 directives.
<?php
/**
* @package Whatever
*
* @phpcs:disable PSR1.Classes.ClassDeclaration.MissingNamespace
*/
use joomla\CMS\...
// phpcs:disable PSR1.Files.SideEffects
\defined('_JEXEC') or die;
// phpcs:enable PSR1.Files.SideEffects
Others need some thought!
After installation in VSCode, code style violations will be detected and marked with a red squiggle underline. Hover over the problem to see a message and potential solution, as in this example:
Header blocks must be separated by a single blank line
PHP_CodeSniffer(PSR12.Files.FileHeader.SpacingAfterBlock)
Installation in PhpStorm¶
Code Sniffer is supported out of the box in PhpStorm. Go to Settings and under Editor → Inspections you will see the list of sniffers you have installed.
Set Path to Code Sniffer¶
- Open Settings (CTRL-ALT-S / CMD-,)
- Go to Languages & Frameworks
- Click on PHP
- Click on Quality Tools
- Click on PHP cs fixer dropdown arrow
- The configuration is set to Local by default
- Click on the 3 dots behind it to open the configuration screen
- The first option is the PHP Code Sniffer (phpcs) path
- Click on the 3 dots behind the path to select the location of the phpcs file. See above on where phpcs may be installed on your site
- Click on Validate to make sure the path is correct and phpcs is working
- Click OK
Activating the Code Style¶
- Open Settings (CTRL-ALT-S / CMD-,)
- Go to Editor
- Click on Inspections
- In the list, go to PHP
- Click on PHP Code Sniffer Validation
- Click on the check box behind it to activate it
- Click the Reload button (2 arrows) to force a reload of rules from disk
- Joomla should now be available in the list. See following image.
- Click OK
Installation in Netbeans¶
Netbeans has the sniffer functionality integrated into the core system.
- Start your Netbeans IDE
- Open Tools → Options → PHP → Code Analysis → Code Sniffer
- You have to set the path to phpcs.bat from the installed PHP_CodeSniffer PEAR package
- For Unix based systems the path is something like /usr/bin/phpcs
- In XAMPP (windows) you can find the file in the PHP root folder (e.g. C:\xampp\php\phpcs.bat)
- As "Default Standard," choose "Joomla" to use the Joomla! standard
- Now you can click OK to start sniffing
- Open from the top menu Source → Inspect...
- Enjoy
Installation in Eclipse¶
- Help → Install New Software...
- Work with Fill in one of the update site URLs.
- Select the desired tools.
- Restart Eclipse.
- Window → Preferences
- PHP Tools → PHP CodeSniffer
You are now able to sniff for code violations against common standards.
Installation in Geany¶
- Open a PHP file. (Otherwise the build menu is not accessible.)
- On the top menu, select Build → Set Build Commands.
- Select the second field and name it as you wish. Enter this code in the Command:
phpcs --standard=Joomla "%f" | sed -e 's/^/%f |/' | egrep 'WARNING|ERROR' - Enter this code in the Error Regular Expression field:
(.+) [|]\s+([0-9]+) - Select OK.
- If the Message Window is not open, display it by selecting it in the top View menu.
- When viewing any PHP file, press F9 to see the errors found.
Installation in Atom¶
- Install phpcs and the Joomla standards as described above.
- In Atom → Preferences → Install install linter-phpcs and all its requirements.
- In Atom → Preferences → Packages → linter-phpcs → Settings adjust
- Executable Path to the path of your phpcs
- Code Standard Or Config File: PSR12
- Tab Width: 4