Hello! This is Naomi again, one of Commude’s interns. You may have read my blog post before about fetching data with jQuery and AJAX, that I recommend you to check out if you haven’t already and if you want a simple tutorial on that topic. I’m writing another article today that has always been an intriguing topic for me. I’ve always wondered if there were a set of coding conventions or standard practices for PHP when I first started learning about backend development using PHP. After researching online about it, I stumbled upon something that was exactly what I needed. There is a list of PHP coding standards known as the PHP Standard Recommendation or PSR, in short, which was published by an organization called the PHP Framework Interop Group.
You might ask how the rules are exactly established. Each rule is actually suggested by members. And these suggestions are voted accordingly, using a set of bylaws established by community members from all around the world. Currently, there have been 22 submitted rules, but not all have been accepted. Below is an overview on some of the accepted guidelines that I based from (mainly from PSR-12, which contains extensive information about the current coding conventions) along with other common standards used by many organizations:
1. Code must begin with only the <?php and <?= tags – This concept is pretty easy to understand. Using the shorthand format is also acceptable, but you should still be careful in ensuring that shorthand tags are not disabled, especially when running it in Apache.
2. Closing PHP tag must be omitted from files that contain only PHP – This was established as a standard to avoid the possibility of accidentally adding code after the closing tag. We don’t want this since the code after the closing tag will be interpreted as HTML.
3. Use four spaces for indentations – When I first read about this, I wasn’t too happy as it has been a habit for me to press the tab key for quicker typing. I found that many people online also share the same opinion as I do, and some even argue that tabs should be recommended instead to cater more towards the visually impaired people. Although, that’s a whole argument we don’t want to focus too much on, so we can stay on topic. One of the main reasons why space indenting is endorsed is because different editors use different tab spacings. This creates the ugly result of having inconsistent file formats across different programs and editors.
Naming Conventions and Important Keywords:
1. Method names must be defined in camelCase
2. Class constants should be defined in all uppercase with underscore separators
3. Class names must be defined using PascalCase
4. PHP constants (true, false, null) should be in lower case
5. PHP keywords must also be in lower case
6. Package names are usually written in PascalCase
Line Length:
There is no hard limit that should be enforced on line length. However, there is a soft limit of keeping the character limit to 120 characters. Lines should also be around 80 characters or less.
This one is also pretty straightforward, but there should only be one statement per line. This improves the code readability, not only for others but also for ourselves.
Finally, don’t be afraid to use blank lines to make the code more readable, but be careful not to leave any trailing whitespaces at the end of lines that contain code.
Documentation:
PHP files and classes must always include a DocBlock header to help other developers understand your code easily, which is a common standard for all the other notable programming languages out there.
A DocBlock should also be implemented when defining properties, constants, functions, and methods for the same reason as above. In the example below, I’ve written a DocBlock for a simple function that provides a brief description of what it does, which is to connect to a database, its parameters, and what value it will return. As you can see, if the connection is successful with the parameters given, then it will return the link variable I’ve set, but if not, it won’t return anything, hence the void keyword.
PHP Linting & Github Actions:
If you want a quick and easy way to check if your code follows the PSRs, you can always use a handy PHP linter that will do just that. Linters will automatically detect if your code doesn’t adhere to common coding standards. There are lots of PHP linters that you can start using. In the example image below, I’m using php cs-fixer, which is also what our system/app director likes to use. However, as I’ve said, there are tons of options you’re free to choose out there.
Additionally, there’s also the option to utilize Github Actions for linting. You can use something like Lint Action from Github Marketplace that will check if the code follows the standards upon sending pull requests.
Conclusion:
Although coding standards can vary for every individual, group, or company, it’s still evident that most of the coding conventions used are usually derived from PHP Framework Interop Group’s PSR. The PSRs are guidelines that are considered as standard practices, followed by the vast majority of people. There are also other coding conventions formed by well-known organizations like the Laminas Framework (continuation of the Zend Framework Group), Pear, and WordPress. At the end of the day, it’s up to you or your employer to choose whatever may be best suited for the organization you’re a part of and your projects. Some rules may be tweaked, but it’s ideal to get an idea of these conventions as they are widely used by most developers. If you need to read more about PSRs, you can check out this link:
https://www.php-fig.org/psr/
Other Resource/s:
https://www.php-fig.org/psr/psr-12/