Be a Better PHP Developer: PEAR Coding Standards!

The PEAR coding standard is the most prevalent among the PHP community. The latest version ensures great flexibility for developer style. However, it’s good practice for PHP developers to follow the PEAR coding standards which will ensure better readability and consistency of coding among the members who are developing the software.

Maintaining the best PEAR coding standard is a must for PHP developers who are building packages for official PEAR distributions. However, it is a good practice for PHP software/application developers to follow these PEAR coding standards. Following a unified coding standard ensures consistency and better readability of the codes. Also, when working on larger projects with multiple developers, it helps to keep the diffs fewer in a version control system.

pear_coding-714x1024

Code indentation
For indenting codes, spaces should be used, not tabs. This helps the code to remain unaltered between different IDEs, version control systems, and annotations. A typical indentation consists of four spaces. So one indent is four spaces (not one tab) and two indents are eight spaces (not two tabs) and so on. Using tabs has some negative impact. Suppose your IDE is configured to occupy 4 spaces per tab and some other person’s IDE is configured to occupy 8 spaces per tab. Now if the other person writes some PHP codes and you open the file in your IDE, you will see a double tabbed code for each tab the other person has used. So using spaces is always better. Many IDE allows you to configure the code formatting so that when you use the tab key, it will automatically insert the number of spaces you set there. Also, you need not worry about how many spaces you have to type for multiple nested blocks, i.e. twelve spaces for third nesting! Almost every IDE places the cursor to the next line with the preceding spaces/ tabs copied from the previous line.

Line Length
The recommended standard of character length per line as set by PEAR is 75-85 characters for the sake of better code readability. Though there are different thoughts and debates on this, however, setting this limit obviously has some valid reasons.

PHP Tag
Always use a full PHP opening and closing tag, not the <? /* code goes here */ ?> shorthand tag. This eliminates the scope of using short echo. The tag is per the PEAR compliance and doesn’t leave any server configuration dependency. To use short <? ?> tag you need to have the PHP short open tag enabled in PHP.ini, where you may not always have access, e.g. in shared hostings. So this is the most accurate way.

Code Commenting
While coding, one should always try to describe what the purpose is of each block of code. There are two types of commenting in a PHP script file. One is docblock comments, usually found in the file’s header section, the other is non-documentation comments. As per PEAR standards, non-documentation comments are highly encouraged. Both the following commenting styles can be used:

C style commenting /* */
C++ style commenting //
Shell type commenting, i.e. # is discouraged

Naming conventions – Constant, Variable, Function, Class, Method
Constants should be defined in the uppercase letters with the underscore to separate the words.

2015-08-24_1235

Variables can either be in lower camelcase without underscores in them or can be in lowercase with underscores to separate the words. E.g. use either $thisIsMyVariable or $this_is_my_variable.

2015-08-24_1237

The class name should not be used with abbreviated words and the first letter should always be in uppercase. Also, if the class name consists of multiple words, then those can be separated by underscores, but the first letter of each word should be in uppercase. Public and protected class variables, i.e. properties and method names should be in camelcase, and private class properties and methods should be preceded by a single underscore.

2015-08-24_1310

Control Structures
Control structure statements, like if, else, for, foreach, while, do, switch etc. should have a space between the control keyword and the opening parenthesis as a difference to the function definitions which do not have any space between the function name and an opening parenthesis. Though you are technically allowed to use control statements without curly braces, but as per PEAR coding standard, it is highly encouraged to always use curly braces for the sake of readability and less logical errors. The opening curly brace should be in the same line with the control statement with space after closing parenthesis and the closing curly brace should be in a new line. There should be a space on each side of the operators used in control statements.

2015-08-23_1257

Split Code in Multiple Lines
Splitting the code into multiple lines is a good idea when the line is very long. For example; there may be multiple complex conditions under multiple parenthesis blocks. Those can be separated into multiple lines.

2015-08-24_1333

Long ternary operators can also be distributed over several lines.

2015-08-24_1341

If function calling with multiple parameters becomes a very long line, then the same can be split into multiple lines as well.

2015-08-24_1335

Function Calls
Typical function call should meet the following standards:

  • One space on the both side of the equals operator ( = ) that is used to assign the function return value to a variable.
  • No spaces between the function name and the opening parenthesis.
  • No spaces between the opening parenthesis and the first parameter.
  • No spaces between the parameter and comma.
  • One space between each comma and the next parameter.
  • No spaces between the last parameter, the closing parenthesis, and the semicolon.

2015-08-14_1745

For better readability, we can add more spaces before the equals operator in a block of related assignments.

2015-08-14_2018

Also, we can add more spaces after the comma and before the next parameter to align the parameters of subsequent calls.

2015-08-14_2038

Class Definitions
Class names should always start with a capitalized letter and the opening and closing braces should be in new lines. The first line of a class file should be the class namespace if you are using a namespace. Then the use class statements with a line for each. The namespace statement, the use class statements, and the class definition should have a line gap between them.

2015-08-23_1213

Function Definitions
Function definition standard follows the K&R indent pattern, the style used in Brian Kernighan and Dennis Ritchie’s book The C Programming Language. Following are the main points that fall under this pattern:

  • No spaces between the function name and the opening parenthesis.
  • No spaces between the opening parenthesis and the first argument.
  • No spaces between the arguments and the corresponding comma.
  • One space between each comma and the next argument.
  • No spaces between the last argument and the closing parenthesis.
  • Arguments with default value go at the end of the argument list.
  • The opening brace goes to the next line of the function name with the same indent level.
  • The closing brace also goes to a new line after the last statement of the function and with the opening brace indent level.

And the thumb rule of any function definitions is to return a meaningful value, if not, return a boolean.

Arrays
The assignments of the values to the keys should be aligned and separated in new lines for multiple assignments. Also, the last element of the array should have a trailing comma for fewer diffs in version control and keep valid syntax once more elements are added.

2015-08-23_1225

Script Inclusion
Rule of thumb for script inclusions are, if you are including a class file without any condition, then you should use require, and if you are including a class file conditionally, then you can use include. Though PEAR standard defines to use require_once and include_once, but Rasmus Lerdorf mentioned on his blog about using include and require only for faster performance. Also as per the standard, require and include should not be written as functions, because these are statements. Writing as a function doesn’t create any error, warning, or notice.

2015-08-18_0009

 
Written by:
Supratim is a technical enthusiast with over ten years of work experience in the IT industry. His specialisation is web development technology. After graduating in Computer Applications from Indira Gandhi National Open University, he started his career in 2005 as a junior software developer. After six years, he completed his masters from Sikkim Manipal University and now works as the Director of Technology at CodeClouds IT Solutions Pvt. Ltd. He loves listening to music, watching action movies and discovery channel, amateur photography, and reading technical journals. Supratim is passionate about adventure sports as well.
 

Comments