All rules and guidelines in this document apply to PHP files unless otherwise noted. References to PHP/HTML files can be interpreted as files that primarily contain HTML, but use PHP for templating purposes.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Most sections are broken up into two parts:
- Overview of all rules with a quick example
- Each rule called out with examples of do's and don'ts
Icon Legend:
· Space, ⇥ Tab, ↵ Enter/Return
- Files
- Skeleton
- PHP Tags
- End of File
- Namespaces
- Comments
- Includes
- Formatting
- Functions
- Control Structures
- Classes
- Best Practices
This section describes the format and naming convention of PHP files.
- Character encoding MUST be set to UTF-8 without BOM
- Sublime.app →
File›Save with Encoding›UTF-8
- Sublime.app →
- Line endings MUST be set to Unix (LF)
- Sublime.app →
View›Line Endings›Unix
- Sublime.app →
- Letters MUST be all lowercase
- e.g.
autoloader.php
- e.g.
- Words MUST be separated with a hyphen
- e.g.
app-config.php
- e.g.
This section showcases a barebones PHP file with its minimum requirements.
Line by line breakdown:
- Line 1: PHP open tag
- Line 2: Blank line
- Line 3: Your code
- Line 4: Blank line
- Line 5: End-of-file comment
- Line 6: Blank line
<?php
// your code
// EOF
This section describes the use of PHP tags in PHP and PHP/HTML files.
- Open tag MUST be on its own line and MUST be followed by a blank line
- i.e.
<?php↵↵...
- i.e.
- Close tag MUST NOT be used in PHP files
- i.e. no
?>
- i.e. no
- Open/close tag MUST be on one line in PHP/HTML files
- i.e.
<?php ... ?>
- i.e.
- Short open tag MUST NOT be used
- i.e.
<?→<?php
- i.e.
- Short echo tag SHOULD be used in PHP/HTML files
- i.e.
<?php echo→<?=
- i.e.
Open tag MUST be on its own line and MUST be followed by a blank line.
<?php print_welcome_message();↳ Incorrect because <?php is not on its own line.
<?php
print_welcome_message();↳ Incorrect because <?php is not followed by a blank line.
<?php
print_welcome_message();▲ PHP Tags
Close tag MUST NOT be used in PHP files.
<?php
print_welcome_message();
?>↳ Incorrect because ?> was used.
<?php
print_welcome_message();▲ PHP Tags
Open/close tag MUST be on one line in PHP/HTML files.
<div>
<h1><?php
print_welcome_message();
?></h1>
</div>↳ Incorrect because <?php and ?> are not on one line.
<div>
<h1><?php print_welcome_message(); ?></h1>
</div>▲ PHP Tags
Short open tag MUST NOT be used.
<?
print_welcome_message();↳ Incorrect because <? was used instead of <?php.
<?php
print_welcome_message();▲ PHP Tags
Short echo tag SHOULD be used in PHP/HTML files.
<div>
<p><?php echo get_welcome_message(); ?></p>
</div>↳ Acceptable, but <?= should be used over <?php echo when possible.
<div>
<p><?= get_welcome_message(); ?></p>
</div>▲ PHP Tags
This section describes how every PHP file must end.
End-of-file comment:
- MUST be included at the end of a file
- i.e.
// EOF
- i.e.
- MUST be on its own line
- i.e.
↵// EOF
- i.e.
- MUST be surrounded by blank lines
- i.e.
...↵↵// EOF↵
- i.e.
<?php
print_welcome_message();↳ Incorrect because // EOF is missing.
<?php
print_welcome_message(); // EOF↳ Incorrect because // EOF is not on its own line.
<?php
print_welcome_message();
// EOF↳ Incorrect because // EOF is not surrounded by blank lines.
<?php
print_welcome_message();
// EOF
This section describes how to use one or more namespaces and their naming convention.
- Namespace declaration MUST be the first statement and MUST be followed by a blank line
- i.e.
<?php↵↵namespace MyCompany;↵↵...
- i.e.
- Namespace name MUST start with a capital letter and MUST be camelcase
- e.g.
namespace MyCompany;
- e.g.
- Multiple namespaces MUST use the curly brace syntax
- i.e.
namespace MyCompany { ... }
- i.e.
- Magic constant SHOULD be used to reference the namespace name
- i.e.
__NAMESPACE__
- i.e.
Namespace declaration MUST be the first statement and MUST be followed by a blank line.
<?php
print_welcome_message();
namespace MyCompany;
// EOF
↳ Incorrect because namespace MyCompany; is not the first statement.
<?php
namespace MyCompany;
print_welcome_message();
// EOF
↳ Incorrect because namespace MyCompany; is not followed by a blank line.
<?php
namespace MyCompany;
print_welcome_message();
// EOF
Namespace name MUST start with a capital letter and MUST be camelcase.
<?php
namespace myCompany;
// EOF
↳ Incorrect because myCompany does not start with a capital letter.
<?php
namespace MyCOMPANY;
// EOF
↳ Incorrect because MyCOMPANY is not written in camelcase.
<?php
namespace MyCompany;
// EOF
Multiple namespaces MUST use the curly brace syntax.
<?php
namespace MyCompany\Model;
namespace MyCompany\View;
// EOF
↳ Incorrect because there are two namespaces and the curly brace syntax was not used.
<?php
namespace MyCompany\Model {
// model body
}
namespace MyCompany\View {
// view body
}
// EOF
Magic constant SHOULD be used to reference the namespace name.
<?php
namespace MyCompany\Model {
// model body
}
namespace MyCompany\View {
$welcome_message = MyCompany\View\get_welcome_message();
}
// EOF
↳ Acceptable, but using __NAMESPACE__ instead of MyCompany\View is preferred.
<?php
namespace MyCompany\Model {
// ModuleOne body
}
namespace MyCompany\View {
$welcome_message = __NAMESPACE__ . '\\' . get_welcome_message();
}
// EOF
This section describes how comments should be formatted and used.
- Single-line comments MUST use two forward slashes
- e.g.
// My comment
- e.g.
- Multi-line comments MUST use the block format
- i.e.
/**↵* My comment↵*/
- i.e.
- Header comments SHOULD use the block format
- i.e.
/**↵* Name of code section↵*/
- i.e.
- Divider comments SHOULD use the block format with asterisks in between
- i.e.
/**75 asterisks*/
- i.e.
- Comments MUST be on their own line
- i.e.
↵// My comment
- i.e.
- Blocks of code SHOULD be explained or summarized
- e.g.
// Compare user accounts from export against expired accounts in system
- e.g.
- Ambiguous numbers MUST be clarified
- e.g.
// 1,000 processable records per hour API limit
- e.g.
- External variables MUST be clarified
- e.g.
// Database object included in file.php
- e.g.
Single-line comments MUST use two forward slashes.
<?php
/* This is a comment */
// EOF
↳ Incorrect because it uses /* and */ for a single-line comment.
<?php
// This is a comment
// EOF
▲ Comments
Multi-line comments MUST use the block format.
<?php
// This is a
// multi-line
// comment
// EOF
↳ Incorrect because it uses // for a multi-line comment.
<?php
/**
* This is a
* multi-line
* comment
*/
// EOF
▲ Comments
Header comments SHOULD use the block format.
<?php
/**
* Global application settings
*/
define('SETTING_ONE', '');
define('SETTING_TWO', '');
define('SETTING_THREE', '');
// EOF
▲ Comments
Divider comments SHOULD use the block format with 75 asterisks in between.
<?php
/**#######################################################################*/
// EOF
↳ Incorrect because it uses # instead of *.
<?php
/*************/
// EOF
↳ Incorrect because it uses 10 instead of 75 *.
<?php
/**
* Beginning + Middle + End
* 3 spaces + 75 spaces + 2 spaces = 80 character line limit
*/
/******************************************************************************/
// EOF
▲ Comments
Comment MUST be on their own line.
<?php
print_welcome_message(); // Prints welcome message
// EOF
↳ Incorrect because // Prints welcome message is not on its own line.
<?php
// Prints welcome message
print_welcome_message();
// EOF
▲ Comments
Blocks of code SHOULD be explained or summarized.
<?php
foreach ($users as $user) {
if ($expr1) {
// ...
} else {
// ...
}
if ($expr2) {
// ...
} elseif ($expr3) {
// ...
} else {
// ...
}
// ...
}
// EOF
↳ Acceptable, but block of code should be explained or summarized.
<?php
/**
* Get active website bloggers with profile photo for author page.
* If no photo exists on website, check intranet.
* If neither location has photo, send user email to upload one.
*/
foreach ($users as $user) {
if ($expr1) {
// ...
} else {
// ...
}
if ($expr2) {
// ...
} elseif ($expr3) {
// ...
} else {
// ...
}
// ...
}
// EOF
▲ Comments
Ambiguous numbers MUST be clarified.
<?php
while ($expr && $x < 1000) {
// ...
}
// EOF
↳ Incorrect because 1000 is not clarified.
<?php
// Script times out after 1,000 records
while ($expr && $x < 1000) {
// ...
}
// EOF
▲ Comments
External variables MUST be clarified.
<?php
include_once 'some-file.php';
// ...
foreach($users as $user) {
// ...
}
// EOF
↳ Incorrect because source of $users is not clear.
<?php
include_once 'some-file.php';
// ...
// $users from some-file.php
foreach($users as $user) {
// ...
}
// EOF
▲ Comments
This section describes the format for including and requiring files.
- Include/require once SHOULD be used
- i.e.
include→include_once,require→require_once
- i.e.
- Parenthesis MUST NOT be used
- e.g.
include_once('file.php');→include_once 'file.php';
- e.g.
- Purpose of include MUST be documented with a comment
- e.g.
// Provides WordPress environment↵require_once 'wp-load.php';
- e.g.
Include/require once SHOULD be used.
<?php
include 'some-file.php';
require 'some-other-file.php';
// EOF
↳ Acceptable, but _once should be appended to include and require if possible.
<?php
include_once 'some-file.php';
require_once 'some-other-file.php';
// EOF
▲ Includes
Parenthesis MUST NOT be used.
<?php
include_once('some-file.php');
require_once('some-other-file.php');
// EOF
↳ Incorrect because include_once and require_once are used with parenthesis.
<?php
include_once 'some-file.php';
require_once 'some-other-file.php';
// EOF
▲ Includes
Purpose of include MUST be documented with a comment.
<?php
require_once 'some-file.php';
// EOF
↳ Incorrect because there is no comment as to what some-file.php does or provides.
<?php
// Provides XYZ framework
require_once 'some-file.php';
// EOF
▲ Includes
This section outline various, general formatting rules related to whitespace and text.
- Line length MUST NOT exceed 80 characters, unless it is text
- i.e.
|---- 80+ chars ----|→ refactor expression and/or break list values
- i.e.
- Line indentation MUST be accomplished using tabs
- i.e.
function func() {↵⇥...↵}
- i.e.
- Blank lines SHOULD be added between logical blocks of code
- i.e.
...↵↵...
- i.e.
- Text alignment MUST be accomplished using spaces
- i.e.
$var···= ...;
- i.e.
- Trailing whitespace MUST NOT be present after statements or serial comma break or on blank lines
- i.e. no
...··↵·↵...
- i.e. no
- Keywords MUST be all lowercase
- e.g.
false,true,null, etc.
- e.g.
- Variables MUST be all lowercase and words MUST be separated by an underscore
- e.g.
$welcome_message
- e.g.
- Global variables MUST be declared one variable per line and MUST be indented after the first
- e.g.
global $var1,↵⇥$var2;
- e.g.
- Constants MUST be all uppercase and words MUST be separated by an underscore
- e.g.
WELCOME_MESSAGE
- e.g.
- Statements MUST be placed on their own line and MUST end with a semicolon
- e.g.
welcome_message();
- e.g.
- Operators MUST be surrounded by a space
- e.g.
$total = 15 + 7;,$var .= '';
- e.g.
- Unary operators MUST be attached to their variable or integer
- e.g.
$index++,--$index
- e.g.
- Concatenation period MUST be surrounded by a space
- e.g.
echo 'Read:' . $welcome_message;
- e.g.
- Single quotes MUST be used
- e.g.
echo 'Hello, World!';
- e.g.
- Double quotes SHOULD NOT be used
- e.g.
echo "Read: $welcome_message";→echo 'Read: ' . $welcome_message;
- e.g.
Line length MUST NOT exceed 80 characters, unless it is text.
<?php
if(in_array('Slumdog Millionaire', $movies) && in_array('Silver Linings Playbook', $movies) && in_array('The Lives of Others', $movies) && in_array('The Shawshank Redemption', $movies)) {
// if body
}
// EOF
↳ Incorrect because expression exceeds 80 characters and should be refactored.
<?php
$my_movies = array('Slumdog Millionaire', 'Silver Linings Playbook', 'The Lives of Others', 'The Shawshank Redemption');
// EOF
↳ Incorrect because arguments exceed 80 characters and should be placed on their own line.
<?php
$text = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec posuere rutrum tincidunt. Duis lacinia laoreet diam, nec consectetur magna facilisis eget. Quisque elit mauris, auctor quis vulputate id, sagittis nec tortor. Praesent fringilla lorem eu massa convallis ultricies. Maecenas lacinia porta purus, sollicitudin condimentum felis mollis a. Proin sed augue purus. Quisque scelerisque eros vitae egestas porta. Suspendisse vitae purus justo. Pellentesque justo nunc, luctus quis magna sit amet, venenatis rutrum ante. Nam eget nisi ultricies, sodales lectus vel, luctus dui. Cras pellentesque augue vitae nulla laoreet convallis. Mauris ut turpis mollis, elementum arcu eu, semper risus. Mauris vel urna ut felis blandit dictum. Aliquam sit amet tincidunt arcu. Nunc et elit quam. Aliquam hendrerit magna ut lacus semper consequat blandit eu ipsum.';
// EOF
↳ Acceptable because line length was exceeded due to text, not code.
<?php
$my_movies = array(
'Slumdog Millionaire',
'Silver Linings Playbook',
'The Lives of Others',
'The Shawshank Redemption'
);
$has_all_movies = true;
foreach($my_movies as $my_movie) {
if(!in_array($my_movie, $movies)) {
$has_all_movies = false;
}
}
if($has_all_movies) {
// if body
}
$some_long_variable = get_something_else(
'from_some_other_function',
'another_long_argument'
);
// EOF
Line indentation MUST be accomplished using tabs.
<?php
function print_welcome_message() {
echo WELCOME_MESSAGE;
}
// EOF
↳ Incorrect because spaces are used to indent echo WELCOME_MESSAGE; instead of a tab.
<?php
function print_welcome_message() {
echo WELCOME_MESSAGE;
}
// EOF
Blank lines SHOULD be added between logical blocks of code.
<?php
$my_movies = array(
'Slumdog Millionaire',
'Silver Linings Playbook',
'The Lives of Others',
'The Shawshank Redemption'
);
$has_all_movies = true;
foreach($my_movies as $my_movie) {
if(!in_array($my_movie, $movies)) {
$has_all_movies = false;
}
}
if($has_all_movies) {
// if body
}
// EOF↳ Acceptable, but can make scanning code more difficult.
<?php
$my_movies = array(
'Slumdog Millionaire',
'Silver Linings Playbook',
'The Lives of Others',
'The Shawshank Redemption'
);
$has_all_movies = true;
foreach($my_movies as $my_movie) {
if(!in_array($my_movie, $movies)) {
$has_all_movies = false;
}
}
if($has_all_movies) {
// if body
}
// EOF
Text alignment MUST be accomplished using spaces.
<?php
$movie_quotes = array(
'slumdog_millionaire' => 'When somebody asks me a question, I tell them the answer.',
'silver_linings_playbook' => 'I opened up to you, and you judged me.',
'the_lives_of_others' => 'To think that people like you ruled a country.',
'the_shawshank_redemption' => 'Get busy living, or get busy dying.'
);
// EOF
↳ Incorrect because tabs are used instead of spaces to vertically align =>.
<?php
$movie_quotes = array(
'slumdog_millionaire' => 'When somebody asks me a question, I tell them the answer.',
'silver_linings_playbook' => 'I opened up to you, and you judged me.',
'the_lives_of_others' => 'To think that people like you ruled a country.',
'the_shawshank_redemption' => 'Get busy living, or get busy dying.'
);
// EOF
↳ Incorrect because spaces are used instead of tabs to indent array keys.
<?php
$movie_quotes = array(
'slumdog_millionaire' => 'When somebody asks me a question, I tell them the answer.',
'silver_linings_playbook' => 'I opened up to you, and you judged me.',
'the_lives_of_others' => 'To think that people like you ruled a country.',
'the_shawshank_redemption' => 'Get busy living, or get busy dying.'
);
// EOF
Trailing whitespace MUST NOT be present after statements or serial comma break or on blank lines.
<?php
$quotes_exist = false;
print_welcome_message();
// EOF
↳ Incorrect because there are two spaces after $quotes_exist = false;.
<?php
$my_movies = array(
'Slumdog Millionaire',
'Silver Linings Playbook',
'The Lives of Others',
'The Shawshank Redemption'
);
// EOF
↳ Incorrect because there is a space after ,.
<?php
$quotes_exist = false;
print_welcome_message();
// EOF
↳ Incorrect because there are two spaces on the blank line below $quotes_exist = false;.
<?php
$quotes_exist = false;
print_welcome_message();
// EOF
<?php
$my_movies = array(
'Slumdog Millionaire',
'Silver Linings Playbook',
'The Lives of Others',
'The Shawshank Redemption'
);
// EOF
Keywords MUST be all lowercase.
<?php
$is_true = FALSE;
$is_false = TRUE:
$movie_quote = NULL;
// EOF
↳ Incorrect because FALSE, TRUE and NULL are not all lowercase.
<?php
$is_true = false;
$is_false = true:
$movie_quote = null;
// EOF
Variables MUST be all lowercase and words MUST be separated by an underscore.
<?php
$welcome_Message = '';
$Welcome_Message = '';
$WELCOME_MESSAGE = '';
// EOF
↳ Incorrect because $welcome_Message, $Welcome_Message and $WELCOME_MESSAGE are not all lowercase.
<?php
$welcomemessage = '';
// EOF
↳ Incorrect because welcome and message are not separated with an underscore.
<?php
$welcome_message = '';
// EOF
Global variables MUST be declared one variable per line and MUST be indented after the first.
<?php
global $app_config, $cache, $db_connection;
// EOF
↳ Incorrect because $app_config, $cache and $db_connection are together on one line.
<?php
global $app_config,
$cache,
$db_connection;
// EOF
↳ Incorrect because $db_connection and $cache are not indentend once.
<?php
global $app_config,
$cache,
$db_connection;
// EOF
Constants MUST be all uppercase and words MUST be separated by an underscore.
<?php
define('welcome_Message', '');
define('Welcome_Message', '');
define('welcome_message', '');
// EOF
↳ Incorrect because welcome_Message, Welcome_Message and welcome_message are not all uppercase.
<?php
define('WELCOMEMESSAGE', '');
// EOF
↳ Incorrect because WELCOME and MESSAGE are not separated with an underscore.
<?php
define('WELCOME_MESSAGE', '');
// EOF
Statements MUST be placed on their own line and MUST end with a semicolon.
<?php
$quotes_exist = false; print_welcome_message();
// EOF
↳ Incorrect because $quotes_exist = false; and print_welcome_message(); are on one line.
<div>
<h1><?= print_welcome_message() ?></h1>
</div>↳ Incorrect because print_welcome_message() is missing a semicolon.
<?php
$quotes_exist = false;
print_welcome_message();
// EOF
<div>
<h1><?= print_welcome_message() ?></h1>
</div>Operators MUST be surrounded a space.
<?php
$total=3+14;
$string='Hello, World! ';
$string.='Today is a good day!';
// EOF
↳ Incorrect because there is no space surrounding the =, + or .= sign.
<?php
$total = 3 + 14;
$string = 'Hello, World! ';
$string .= 'Today is a good day!';
// EOF
Unary operators MUST be attached to their variable or integer.
<?php
$index ++;
-- $index;
// EOF
↳ Incorrect because there is a space before ++ and after --.
<?php
$index++;
--$index;
// EOF
Concatenation period MUST be surrounded by a space.
<?php
echo 'Hello, World! Today is '.$date.'!';
// EOF
↳ Incorrect because there is no space surrounding ..
<?php
echo 'Hello, World! Today is ' . $date . '!';
// EOF
Single quotes MUST be used.
<?php
echo "Hello, World!";
// EOF
↳ Incorrect because "Hello, World!" is not written with single quotes.
<?php
echo 'Hello, World!';
// EOF
Double quotes SHOULD NOT be used.
<?php
echo "Hello, World! Today is $date!";
// EOF
↳ Acceptable, but burries the $date variable, which is why single quotes are preferred.
<?php
echo "Hello, World! He's watching movies and she's reading books.";
// EOF
↳ Acceptable when long pieces of text have apostrophies that would need to be escaped.
<?php
echo 'Hello, World! Today is ' . $date . '!';
echo 'Hello, World! He\'s watching movies and she\'s reading books.';
// EOF
This section describes the format for function names, calls, arguments and declarations.
- Function name MUST be all lowercase and words MUST be separated by an underscore
- e.g.
function welcome_message() {
- e.g.
- Function prefix MUST start with verb
- e.g.
get_,add_,update_,delete_,convert_, etc.
- e.g.
- Function call MUST NOT have a space between function name and open parenthesis
- e.g.
func();
- e.g.
- Function arguments
- MUST NOT have a space before the comma
- MUST have a space after the comma
- MAY use line breaks for long arguments
- MUST then place each argument on its own line
- MUST then indent each argument once
- MUST be ordered from required to optional first
- MUST be ordered from high to low importance second
- MUST use descriptive defaults
- MUST use type hinting
- e.g.
func($arg1, $arg2 = 'asc', $arg3 = 100);
- Function declaration MUST be documented using phpDocumentor tag style and SHOULD include
- Short description
- Optional long description, if needed
- @access:
privateorprotected(assumedpublic) - @author: Author name
- @global: Global variables function uses, if applicable
- @param: Parameters with data type, variable name, and description
- @return: Return data type, if applicable
- Function return
- MUST occur as early as possible
- MUST be initialized prior at top
- MUST be preceded by blank line, except inside control statement
- i.e.
if (!$expr) { return false; }
Function name MUST be all lowercase and words MUST be separated by an underscore.
<?php
get_Welcome_Message();
Get_Welcome_Message();
GET_WELCOME_MESSAGE();
// EOF
↳ Incorrect because the function names are not all lowercase.
<?php
getwelcomemessage();
// EOF
↳ Incorrect because get, welcome and message are not separated with an underscore.
<?php
get_welcome_message();
// EOF
Function prefix MUST start with verb.
<?php
active_users();
network_location($location1, $location2);
widget_form($id);
// EOF
↳ Incorrect because functions are not prefixed with a verb.
<?php
get_active_users();
move_network_location($location1, $location2);
delete_widget_form($id);
// EOF
Function call MUST NOT have a space between function name and open parenthesis.
<?php
print_welcome_message ();
// EOF
↳ Incorrect because there is a space between get_welcome_message and ().
<?php
print_welcome_message();
// EOF
Function arguments:
- MUST NOT have a space before the comma
- MUST have a space after the comma
- MAY use line breaks for long arguments
- MUST then place each argument on its own line
- MUST then indent each argument once
- MUST be ordered from required to optional first
- MUST be ordered from high to low importance second
- MUST use descriptive defaults
- MUST use type hinting
<?php
my_function($arg1 , $arg2 , $arg3);
// EOF
↳ Incorrect because there is a space before ,.
<?php
my_function($arg1,$arg2,$arg3);
// EOF
↳ Incorrect because there is no space after ,.
<?php
my_other_function($arg1_with_a_really_long_name,
$arg2_also_has_a_long_name,
$arg3
);
// EOF
↳ Incorrect because $arg1_with_a_really_long_name is not on its own line.
<?php
my_other_function(
$arg1_with_a_really_long_name,
$arg2_also_has_a_long_name,
$arg3
);
// EOF
↳ Incorrect because arguments are not indented once.
<?php
function get_objects($type, $order = 'asc', $limit) {
// ...
}
// EOF
↳ Incorrect because $type, $order and $limit are not in order of required to optional.
<?php
function get_objects($limit, $order, $type) {
// ...
}
// EOF
↳ Incorrect because $limit, $order and $type are not in order of importance.
<?php
function get_objects($type, $order = true, $limit = 100) {
// ...
}
// EOF
↳ Incorrect because true is not a descriptive default for $order.
<?php
function add_users_to_office($users, $office) {
// ...
}
// EOF
↳ Incorrect because $users and $office are missing their data type.
<?php
my_function($arg1, $arg2, $arg3);
my_other_function(
$arg1_with_a_really_long_name,
$arg2_also_has_a_long_name,
$arg3
);
function get_objects($type, $order = 'asc', $limit = 100) {
// ...
}
function add_users_to_office(array $users, Office $office) {
// ...
}
// EOF
Function declaration MUST be documented using phpDocumentor tag style and SHOULD include:
- Short description
- Optional long description, if needed
- @access:
privateorprotected(assumedpublic) - @author: Author name
- @global: Global variables function uses, if applicable
- @param: Parameters with data type, variable name, and description
- @return: Return data type, if applicable
<?php
function my_function($id, $type, $width, $height) {
// ...
return $Photo;
}
// EOF
↳ Incorrect because my_function is not documented.
<?php
/**
* Get photo from blog author
*
* Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut id volutpat
* orci. Etiam pharetra eget turpis non ultrices. Pellentesque vitae risus
* sagittis, vehicula massa eget, tincidunt ligula.
*
* @access private
* @author Firstname Lastname
* @global object $post
* @param int $id Author ID
* @param string $type Type of photo
* @param int $width Photo width in px
* @param int $height Photo height in px
* @return object Photo
*/
function my_function($id, $type, $width, $height) {
// ...
return $Photo;
}
// EOF
Function return:
- MUST occur as early as possible
- MUST be initialized prior at top
- MUST be preceded by blank line, except inside control statement
<?php
function get_object() {
$var = false;
if($expr1) {
// ...
if($expr2) {
// ...
}
}
return $var;
}
// EOF
↳ Incorrect because get_object does not return as early as possible.
<?php
function get_movies() {
// ...
return $movies;
}
// EOF
↳ Incorrect because $movies is not initialized at top.
<?php
function get_movies() {
$movies = array();
// ...
return $movies;
}
// EOF
↳ Incorrect because return $movies is not preceded by blank line.
<?php
function get_object() {
$var = false;
if (!$expr1) {
return $var;
}
if (!$expr2) {
return $var;
}
// ...
return $var;
}
// EOF
<?php
function get_movies() {
$movies = array();
// ...
return $movies;
}
// EOF
This section defines the layout and usage of control structures. Note that this section is separated into rules that are applicable to all structures, followed by specific rules for individual structures.
- Keyword MUST be followed by a space
- e.g.
if (,switch (,do {,for (
- e.g.
- Opening parenthesis MUST NOT be followed by a space
- e.g.
($expr,($i
- e.g.
- Closing parenthesis MUST NOT be preceded by a space
- e.g.
$expr),$i++),$value)
- e.g.
- Opening brace MUST be preceded by a space and MUST be followed by a new line
- e.g.
$expr) {,$i++) {
- e.g.
- Structure body MUST be indented once and MUST be enclosed with curly braces (no shorthand)
- e.g.
if ($expr) {↵⇥...↵}
- e.g.
- Closing brace MUST start on the next line
- i.e.
...↵}
- i.e.
- Nesting MUST NOT exceed three levels
- e.g. no
if ($expr1) { if ($expr2) { if ($expr3) { if ($expr4) {...}}}}
- e.g. no
In addition to the rules above, some control structures have additional requirements:
- If, Elseif, Else
elseifMUST be used instead ofelse ifelseifandelseMUST be between}and{on one line
- Switch, Case
- Case statement MUST be indented once
- i.e.
⇥case 1:
- i.e.
- Case body MUST be indented twice
- i.e.
⇥⇥func();
- i.e.
- Break keyword MUST be indented twice
- i.e.
⇥⇥break;
- i.e.
- Case logic MUST be separated by one blank line
- i.e.
case 1: ... break;↵↵case 2: ... break;
- i.e.
- Case statement MUST be indented once
- While, Do While
- For, Foreach
- Try, Catch
catchMUST be between}and{on one line
elseifMUST be used instead ofelse ifelseifandelseMUST be between}and{on one line
<?php
if ($expr1) {
// if body
} else if ($expr2) {
// elseif body
} else {
// else body
}
// EOF
↳ Incorrect because else if was used instead of elseif.
<?php
if ($expr1) {
// if body
}
elseif ($expr2) {
// elseif body
}
else {
// else body
}
// EOF
↳ Incorrect because elseif and else are not between } and { on one line.
<?php
$result1 = if ($expr1) ? true : false;
if($expr2)
$result2 = true;
// EOF
↳ Incorrect because structure body is not wrapped in curly braces.
<?php
if ($expr1) {
// if body
} elseif ($expr2) {
// elseif body
} else {
// else body
}
if ($expr1) {
$result1 = true;
} else {
$result1 = false;
}
if ($expr2) {
$result2 = true;
}
// EOF
- Case statement MUST be indented once
- Case body MUST be indented twice
- Break keyword MUST be indented twice
- Case logic MUST be separated by one blank line
<?php
switch ($expr) {
case 0:
echo 'First case, with a break';
break;
case 1:
echo 'Second case, which falls through';
// no break
case 2:
case 3:
case 4:
echo 'Third case, return instead of break';
return;
default:
echo 'Default case';
break;
}
// EOF
↳ Incorrect because case 0 thru default are not indented once.
<?php
switch ($expr) {
case 0:
echo 'First case, with a break';
break;
case 1:
echo 'Second case, which falls through';
// no break
case 2:
case 3:
case 4:
echo 'Third case, return instead of break';
return;
default:
echo 'Default case';
break;
}
// EOF
↳ Incorrect because echo, break and return are not indented twice.
<?php
switch ($expr) {
case 0:
echo 'First case, with a break';
break;
case 1:
echo 'Second case, which falls through';
// no break
case 2:
case 3:
case 4:
echo 'Third case, return instead of break';
return;
default:
echo 'Default case';
break;
}
// EOF
↳ Incorrect because case 0, case 1 thru case 4, and default are not separated by one blank line.
<?php
switch ($expr) {
case 0:
echo 'First case, with a break';
break;
case 1:
echo 'Second case, which falls through';
// no break
case 2:
case 3:
case 4:
echo 'Third case, return instead of break';
return;
default:
echo 'Default case';
break;
}
// EOF
<?php
while ($expr) {
// structure body
}
do {
// structure body;
} while ($expr);
// EOF
<?php
for ($i = 0; $i < 10; $i++) {
// for body
}
foreach ($iterable as $key => $value) {
// foreach body
}
// EOF
<?php
try {
// try body
}
catch (FirstExceptionType $e) {
// catch body
}
catch (OtherExceptionType $e) {
// catch body
}
// EOF
↳ Incorrect because catch is not between } and { on one line.
<?php
try {
// try body
} catch (FirstExceptionType $e) {
// catch body
} catch (OtherExceptionType $e) {
// catch body
}
// EOF
This section describes class files, names, definitions, properties, methods and instantiation.
- Class file MUST only contain one definition and MUST be prefixed with
class-- i.e.
class User→class-user.php,class Office→class-office.php
- i.e.
- Class namespace MUST be defined and MUST include vendor name
- e.g.
namespace MyCompany\Model;,namespace MyCompany\View;,namespace MyCompany\Controller;
- e.g.
- Class name MUST start with a capital letter and MUST be camelcase
- e.g.
MyCompany
- e.g.
- Class documentation MUST be present and MUST use phpDocumentor tag style
- i.e.
@author,@global,@package
- i.e.
- Class definition MUST place curly braces on their own line
- i.e.
class User↵{↵...↵}
- i.e.
- Class properties
- MUST follow variable standards
- MUST specify visibility
- MUST NOT be prefixed with an underscore if private or protected
- e.g.
$var1;,private $var2;,protected $var3;
- Class methods
- MUST follow function standards
- MUST specify visibility
- MUST NOT be prefixed with an underscore if private or protected
- e.g.
func1(),private func2(),protected func3()
- Class instance
- MUST start with capital letter
- MUST be camelcase
- MUST include parenthesis
- e.g.
$user = new User();,$OfficeProgram = new OfficeProgram();
Class file MUST only contain one definition and MUST be prefixed with class-.
Filename: class-user.php
<?php
namespace MyCompany\Model;
class User
{
// ...
}
class Office
{
// ...
}
// EOF
↳ Incorrect because User and Office are defined in one file.
Filename: user.php
<?php
namespace MyCompany\Model;
class User
{
// ...
}
// EOF
↳ Incorrect because filename is not prefixed with class-.
Filename: class-user.php
<?php
namespace MyCompany\Model;
class User
{
// ...
}
// EOF
Filename: class-office.php
<?php
namespace MyCompany\Model;
class Office
{
// ...
}
// EOF
▲ Classes
Class namespace MUST be defined and MUST include vendor name.
<?php
class User
{
// ...
}
// EOF
↳ Incorrect because there is no namespace defined.
<?php
namespace Model;
class User
{
// ...
}
// EOF
↳ Incorrect because vendor name is missing in the namespace name.
<?php
namespace MyCompany\Model;
class User
{
// ...
}
// EOF
▲ Classes
Class name MUST start with a capital letter and MUST be camelcase.
<?php
namespace MyCompany\Model;
class officeProgram
{
// ...
}
// EOF
↳ Incorrect because officeProgram does not start with a capital letter.
<?php
namespace MyCompany\Model;
class Officeprogram
{
// ...
}
// EOF
↳ Incorrect because Officeprogram is not camelcase.
<?php
namespace MyCompany\Model;
class OfficeProgram
{
// ...
}
// EOF
▲ Classes
Class documentation MUST be present and MUST use phpDocumentor tag style.
<?php
namespace MyCompany\Model;
class User
{
// ...
}
// EOF
↳ Incorrect because User is missing documentation.
<?php
namespace MyCompany\View;
/**
* User View
*/
class User
{
// ...
}
// EOF
↳ Incorrect because User is missing phpDocumentor tags.
<?php
namespace MyCompany\View;
/**
* User View
*
* @author Firstname Lastname
* @global object $post
* @package MyCompany\API
*/
class User
{
// ...
}
// EOF
▲ Classes
Class definition MUST place curly braces on their own line.
<?php
namespace MyCompany\Model;
class User {
// ...
}
// EOF
↳ Incorrect because { is not on its own line.
<?php
namespace MyCompany\Model;
class User
{
// ...
}
// EOF
▲ Classes
Class properties:
- MUST follow variable standards
- MUST specify visibility
- MUST NOT be prefixed with an underscore if private or protected
<?php
namespace MyCompany\Model;
class User
{
// Public
$var1;
// Protected
$var2;
// Private
$var3;
}
// EOF
↳ Incorrect because visibility is not specified for $var1, $var2 and $var3.
<?php
namespace MyCompany\Model;
class User
{
public $var1;
protected $_var2;
private $_var3;
}
// EOF
↳ Incorrect because protected and private properties are prefixed with _.
<?php
namespace MyCompany\Model;
class User
{
public $var1;
protected $var2;
private $var3;
}
// EOF
▲ Classes
Class methods:
- MUST follow function standards
- MUST specify visibility
- MUST NOT be prefixed with an underscore if private or protected
<?php
namespace MyCompany\Model;
class User
{
// ...
// Public
function get_var1() {
return $this->var1;
}
// Protected
function get_var2() {
return $this->var2;
}
// Private
function get_var3() {
return $this->var3;
}
}
// EOF
↳ Incorrect because visibility is not specified for get_var1(), get_var2() and get_var3().
<?php
namespace MyCompany\Model;
class User
{
// ...
public function get_var1() {
return $this->var1;
}
protected function _get_var2() {
return $this->var2;
}
private function _get_var3() {
return $this->var3;
}
}
// EOF
↳ Incorrect because protected and private methods are prefixed with _.
<?php
namespace MyCompany\Model;
class User
{
// ...
public function get_var1() {
return $this->var1;
}
protected function get_var2() {
return $this->var2;
}
private function get_var3() {
return $this->var3;
}
}
// EOF
▲ Classes
Class instance:
- MUST follow variable standards
- MUST include parenthesis
<?php
$office_program = new OfficeProgram;
// EOF
↳ Incorrect because new OfficeProgram is missing parenthesis.
<?php
$office_program = new OfficeProgram();
// EOF
▲ Classes
- Variable initialization SHOULD occur prior to use and SHOULD occur early
- e.g.
$var1 = '';,$var2 = 0;
- e.g.
- Initialization/declaration order
- MUST lead with globals, follow with constants, conclude with local variables
- MUST lead with properties and follow with methods in classes
- MUST lead with
public, follow withprotected, conclude withprivatemethods in classes - SHOULD be alphabetical within their type
- i.e.
global $var1;,define('VAR2', '');,$var3 = 0;
- Globals SHOULD NOT be used
- i.e. no
global $var;
- i.e. no
- Explicit expressions SHOULD be used
- e.g.
if ($expr === false),while ($expr !== true)
- e.g.
- E_STRICT reporting MUST NOT trigger errors
- i.e. do not use deprecated functions, etc.
Variable initialization SHOULD occur prior to use and SHOULD occur early.
<?php
$movies = get_movies();
// EOF
↳ Acceptable, but $movies should be initialized prior to use.
<?php
if ($expr) {
// ....
}
$movies = array();
$movies = get_movies();
// EOF
↳ Acceptable, but $movies should be initialized earlier.
<?php
$movies = array();
if ($expr) {
// ....
}
$movies = get_movies();
// EOF
Initialization/declaration order:
- MUST lead with globals, follow with constants, conclude with local variables
- MUST lead with properties and follow with methods in classes
- MUST lead with
public, follow withprotected, conclude withprivatemethods in classes - SHOULD be alphabetical within their type
<?php
define('ENVIRONMENT', 'PRODUCTION');
$id = 0;
global $app_config;
// EOF
↳ Incorrect because $app_config is not first, ENVIRONMENT not second, and $id not third.
<?php
namespace MyCompany\Model;
class Office
{
public function get_name() {
// ...
}
private $name;
}
// EOF
↳ Incorrect because get_name() is declared before $name.
<?php
namespace MyCompany\Model;
class Office
{
private $id;
private $name;
private $status;
private function get_name() {
// ...
}
public function get_id() {
// ...
}
protected function get_status() {
// ...
}
}
// EOF
↳ Incorrect because get_id() is not first, get_status() not second, and get_name() not third.
<?php
global $db_connection,
$app_config,
$cache;
define('MODE', 1);
define('ENVIRONMENT', 'PRODUCTION');
$id = 0;
$firstname = '';
$lastname = '';
// EOF
↳ Acceptable, but the globals and constants should be in alphabetical order.
<?php
function get_movies() {
// ...
}
function get_actors() {
// ...
}
// EOF
↳ Acceptable, but get_actors should be declared before get_movies.
<?php
global $app_config,
$cache,
$db_connection;
define('ENVIRONMENT', 'PRODUCTION');
define('MODE', 1);
$id = 0;
$firstname = '';
$lastname = '';
// EOF
<?php
namespace MyCompany\Model;
class Office
{
private $id;
private $name;
private $status;
public function get_id() {
// ...
}
protected function get_status() {
// ...
}
private function get_name() {
// ...
}
}
// EOF
<?php
function get_actors() {
// ...
}
function get_movies() {
// ...
}
// EOF
Globals SHOULD NOT be used.
<?php
$pdo = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
function get_user($id) {
global $pdo;
// ...
}
// EOF
↳ Acceptable, but global variables should be avoided.
<?php
function get_database_object() {
return new PDO('mysql:host=localhost;dbname=test', $user, $pass);
}
function get_user($id) {
$pdo = get_database_object();
// ...
}
// EOF
Explicit expressions SHOULD be used.
<?php
if ($expr == true) {
// ...
}
// EOF
↳ Acceptable, but === could be used here instead.
<?php
if ($expr === true) {
// ...
}
// EOF
E_STRICT reporting MUST NOT trigger errors.
<?php
$firstname = call_user_method('get_firstname', $User);
// EOF
↳ Incorrect because call_user_method (deprecated) will cause E_STRICT warning.
<?php
$firstname = call_user_func(array($User, 'get_firstname'));
// EOF
Inspired in part by style guides from:
CodeIgniter, Drupal, Horde, Pear, PSR-1, PSR-2, Symfony, and WordPress.
Thank you very much for this work.