general/coding_standards.html

<!doctype html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" href="./../assets/css/combined.css?20170912">
	<link rel="shortcut icon" href="./../favicon.ico" />
	<script src="https://www.google.com/jsapi" type="text/javascript"></script>
	<script type="text/javascript">
		var path = './../';
	</script>
	<script src="./../assets/js/combined.js?20170912"></script>
	<title>Coding Standards - General - FuelPHP Documentation</title>
</head>
<body>
	<div id="container">
		<header id="header">
			<div class="table">
				<div id="cse">
					<gcse:searchbox-only newWindow="true"></gcse:searchbox-only>
				</div>
				<h1>
					<a href="https://fuelphp.com"><img height="37px" width="147px" src="./../assets/img/fuel.png" /></a>
					<strong>Documentation</strong>
				</h1>
			</div>
			<nav>
				<div class="clear"></div>
			</nav>
			<a href="#" id="toc_handle">table of contents</a>
			<div class="clear"></div>
		</header>

		<div id="main">

			<h2>Coding Standards</h2>

			<p>These standards for code formatting and documentation must be followed by anyone contributing to Fuel. Any
				contributions that do not meet these guidelines will not be accepted.</p>

			<h3 id="file_formatting">File Formatting</h3>

			<h5 id="closing_php_tag">Closing PHP Tag</h5>

			<p>Files containing only PHP code should always omit the closing PHP tag (?>). This prevents many of the
				elusive white screens of death.</p>

			<h5 id="indentation">Indentation</h5>

			<p>All indentation should be done using real tabs, NOT spaces.<br />
				But aligning things after the indentation should be done using spaces, NOT tabs.</p>

			<pre class="php"><code>		// indented 2 tabs
		$var       = 'something';  // indented with tabs and aligned value &amp; comments
		$variable  = 'else';       // with those above/below using spaces</code></pre>

			<h5 id="line_endings">Line Endings</h5>

			<p>Line endings should be Unix-style LF.</p>

			<h5 id="file_naming">File Naming</h5>

			<p>All file names must be all lower case. No exceptions.</p>

			<h5 id="encoding">Encoding</h5>

			<p>Files should be saved with UTF-8 encoding and the BOM should not be used.</p>

			<h3 id="naming_conventions">Naming Conventions</h3>

			<h5 id="namespaces">Namespaces</h5>

			<p>All core classes must be under the Fuel\Core namespace.</p>

			<pre class="php"><code>namespace Fuel\Core;</code></pre>

			<h5 id="classes">Classes</h5>

			<p>Class names should use underscores to separate words, and each word in the class name should begin with a
				capital letter. The use of camelcase is discouraged but cannot be prevented in some cases when putting
				the class in a subdirectory makes absolutely no sense. If possible, this should be avoided.
			</p>

			<pre class="php"><code>namespace Fuel\Core;

class Session
{

}</code></pre>

			<pre class="php"><code>namespace Fuel\Core;

class Session_Cookie extends Session_Driver
{

}</code></pre>

			<p>
				Every class should be defined into its own file. Any underscores in the class name will be converted to a directory
				separator during autoloading, so this must be reflected in the name and location of the class file. For the classes
				above, their names wouldresult in the following file path:
			</p>

			<pre class="php"><code>COREPATH/classes/session.php
COREPATH/classes/session/cookie.php</code></pre>

			<h5 id="methods_standards">Methods</h5>

			<p>Like class names, method names should use underscores to separate words, not CamelCase. Method names should
				also be all lower case. Visibility should always be included (public, protected, private).<br />
				An underscore can be used at the beginning of the name to make it clear the method is protected/private or
				to signify it should be considered as such when you need it public.</p>

			<pre class="php"><code>class Session
{

	public static function get_flash($name, $data)
	{
		// Some code here
	}

}</code></pre>

			<pre class="php"><code>class View
{

	// Array of global view data
	protected static $_global_data = array();

	protected static function capture($view_filename, array $view_data)
	{
		// Some code here
	}

}</code></pre>

			<h5 id="variables">Variables</h5>

			<p>Variable names should be concise and contain only lower case letters and underscores. Loop iterators should
				be short, preferably a single character.</p>

			<pre class="php"><code>$first_name
$buffer
for ($i = 0; $i &lt; $max; $i++)</code></pre>

			<p>
				Except for the PHP global system constant that doesn't have a Fuel wrapper (for example <kbd>$_ENV</kbd>), global
				variables should never been used. If you have a legitemate use for such a constant, please inform the team so a
				wrapper can be created to allow consistent and immutable access to that constant.<br />
				Use of the keyword <kbd>global</kbd> to create or import global variables into a local variable scope is
				<strong>explicitly</strong> forbidden!
			</p>

			<h5 id="constants">Constants</h5>

			<p>Constants follow the same guide lines as variables with the exception that constants should be all upper
				case.</p>

			<pre class="php"><code>MY_CONSTANT
TEMPLATE_PATH
TEXT_DEFAULT</code></pre>

			<p>
				The use of global constants is discouraged and should be kept to an absolute minimum. If you need one, be prepend to
				defend your use case before the Fuel team will accept your proposal!. Where possible, use class constants to make
				their scope, usage and meaning clear.
			</p>

			<h3 id="keywords">Keywords</h3>

			<p>Keywords such as <kbd>true</kbd>, <kbd>false</kbd>, <kbd>null</kbd>, <kbd>as</kbd>, etc should be all lower case, as upper case is reserved for
				constants. Same goes for primitive types like <kbd>array</kbd>, <kbd>integer</kbd>, <kbd>string</kbd>.</p>

			<pre class="php"><code>$var = true;
$var = false;
$var = null;
foreach ($array as $key => $value)
public function my_function(array $array)
function my_function($arg = null)</code></pre>

			<h3 id="type_casting">Type casting</h3>

			<p>
				The use of type casting is discouraged. PHP is a weakly typed language with at times very vague type conversion rules. They may
				cause unintended behaviour, which may introduce very hard to find bugs. Instead, do a content check before you convert to make
				sure the variable contains an expected value.
			</p>

			<h3 id="control_structures">Control Structures</h3>

			<p>The structure keywords such as <kbd>if</kbd>, <kbd>for</kbd>, <kbd>foreach</kbd>, <kbd>while</kbd>, <kbd>switch</kbd> should be followed by a space as should
				parameter/argument lists and values. Braces should be placed on a new line, and <kbd>break</kbd> should have the same
				tab as its case.</p>

			<pre class="php"><code>if ($arg === true)
{
	//do something here
}
elseif ($arg === null)
{
	//do something else here
}
else
{
	//catch all do something here
}

foreach ($array as $key => $value)
{
	//loop here
}

for ($i = 0; $i &lt; $max; $i++)
{
	//loop here
}

while ($i &lt; $max)
{
	//loop here
}

do
{
	//loop here
}
while ($i &lt; $max)

switch ($var)
{
	case 'value1':
		//do something here
	break;
	default :
		//do something here
	break;
}</code></pre>

			<h5 id="alternative_if">Alternative if statements</h5>

			<p>In some cases, a full <kbd>if</kbd> statement is a bit too much code for a simple conditional assignment or function
				call. In those cases, you can use PHP's execution logic to use a shorter boolean-operator based syntax.
				Using <kbd>and</kbd> means the second part only gets evaluated if the first part were true, using
				<kbd>or</kbd> means the second part only gets executed if the first part were false.<br />
				Don't use this when both <kbd>if</kbd> and <kbd>else</kbd> are needed, just in cases like single conditional statements.</p>

			<pre class="php"><code>// instead of if (isset($var)) { Config::set('var', $var); }
isset($var) and Config::set('var', $var);

// instead of if ( ! isset($var)) { $var = Config::get('var'); }
isset($var) or $var = Config::get('var');

// DON'T DO THIS
Uri::segment(3) and $var = Uri::segment(3);
Uri::segment(3) or $var = 'default';

// This is better:
if (Uri::segment(3))
{
	$var = Uri::segment(3);
}
else
{
	$var = 'default';
}

// Or this:
$var = Uri::segment(3) ? Uri::segment(3) : 'default';

// Or even better, this:
$var = Uri::segment(3) ?: 'default';</code></pre>

			<h3 id="comparison_logical">Comparisons, Logical operators</h3>

			<p>Comparing function/method returns and variables should be type aware, for example some functions may return
				<kbd>false</kbd>, and when comparing this return the type sensitive operators such as <kbd>===</kbd> or <kbd>!==</kbd>. Additionally, use of
				<kbd>and</kbd> or <kbd>or</kbd> is preferred over <kbd>&amp;&amp;</kbd> or <kbd>||</kbd> for readability. In some cases, this cannot be avoided and the use of
				<kbd>&amp;&amp;</kbd> or <kbd>||</kbd> as it's required may be used. The <kbd>!</kbd> should have spaces on both sides when used.</p>

			<pre class="php"><code>if ($var == false and $other_var != 'some_value')
if ($var === false or my_function() !== false)
if ( ! $var)</code></pre>

			<h5 id="class_interface">Class/Interface Declarations</h5>

			<p>Class/interface declarations have the opening brace on the following line:</p>

			<pre class="php"><code>class Session
{

}</code></pre>
			<p>In case the class is empty, braces will be on the same line as the definition:</p>

			<pre class="php"><code>class Empty_Class { }</code></pre>

			<h5 id="function_method">Function/Method/Closure Declarations</h5>

			<p>The function/method/closure opening brace must always begin on a new line and have the same indentation as its
				structure.</p>

			<pre class="php"><code>class Session
{

	public static function get_flash($name, $data)
	{
		$closure = function($a, $b)
		{
			// Your closure code here
		}
	}

}</code></pre>

			<h5 id="variables">Variables</h5>

			<p>When initializing variables, one variable should be declared per line. To enhance code readability, these
				should each be on a separate line. Align values and comments when appropriate.</p>

			<pre class="php"><code>$var        = ''; // do each on its own line
$other_var  = ''; // do each on its own line</code></pre>

			<h5 id="brackets_parenthesis">Brackets and Parenthesis</h5>

			<p>No space should come before or after the initial bracket/parenthesis. There should not be a space before closing bracket/parenthesis.</p>

			<pre class="php"><code>$array = array(1, 2, 3, 4);
$array['my_index'] = 'something';
for ($i = 0; $i < $max; $i++)</code></pre>

			<h5 id="quotation">String quotation</h5>

			<p>Single quotes are preferred over double quotes. It prevents unwanted or unintended expansion of variables and control characters.</p>

			<h5 id="concatenation">Concatenation</h5>

			<p>String concatenation should not contain spaces around the joined parts.</p>

			<pre class="php"><code>//yes
$string = 'my string '.$var.' the rest of my string';

//no
$string = 'my string ' . $var . ' the rest of my string';</code></pre>

			<h5 id="operators">Operators</h5>

			<pre class="php"><code>$var = 'something';
if ($var == 'something') //space before and after logical operator
$var = $some_var + $other_var; //space before and after math operator
$var++; // no space before increment
++$var; //no space after increment</code></pre>

			<h5 id="dot-notation">Array dot-notation</h5>

			<p>
				Although strictly speaking it's not a coding standard, it's used a lot within the frameworks classes and this documentation,
				and since it's not a common PHP notation, it might confuse people new to the framework.
			</p>
			<pre class="php"><code>// when you see "always_load.packages = array()", it is shorthand for:
array("always_load" => array("packages" => array(...) ) );
</code></pre>

			<p>This notation is used by the Arr class, but also the Lang, Config and Session classes, to quickly access individual elements from a multi-dimensional array.</p>
			<pre class="php"><code>// when you have an array structure like this
$array = array(
    "always_load" => array(
        "packages" => array(
            "orm",
            "package" => "/my/special/package.php",
        )
     )
);

// then this will return "/my/special/package.php":
$path = Arr::get($array, 'always_load.packages.package');
</code></pre>

		</div>

		<footer>
			<p>
				&copy; FuelPHP Development Team 2010-2025 - <a href="https://fuelphp.com">FuelPHP</a> is released under the MIT license.
			</p>
		</footer>
	</div>
</body>
</html>