<div class="codebox"><pre>

{TAB}$mode{TAB}{TAB}= $request->variable('mode', '');

<p>If entered with tabs (replace the {TAB}) both equal signs need to be on the same column.</p>

* For full copyright and license information, please see

* the docs/CREDITS.txt file.

*

<p>Please see the <a href="#locations">File Locations section</a> for the correct package name.</p>

/**

*/

<h4>Files containing only functions:</h4>

/**

* {DOCUMENTATION}

*/

<a name="locations"></a><h3>1.iii. File Locations</h3>

{

foo($i, $j);

}

<h4>Function Names:</h4>

<p>Functions should also be named descriptively. We're not programming in C here, we don't want to write functions called things like "stristr()". Again, all lower-case names with words separated by a single underscore character in PHP, and camel caps in JavaScript. Function names should be prefixed with "phpbb_" and preferably have a verb in them somewhere. Good function names are <code>phpbb_print_login_status()</code>, <code>phpbb_get_user_data()</code>, etc. Constructor functions in JavaScript should begin with a capital letter.</p>

dir/

class_name.php

subdir/

<div class="codebox"><pre>

\phpbb\class_name - phpbb/class_name.php

\phpbb\dir\class_name - phpbb/dir/class_name.php

<h4>Summary:</h4>

do_stuff();

for ($i = 0; $i &lt; size; $i++)

<p class="good">// These are all right. </p>

<div class="codebox"><pre>

for ($i = 0; $i &lt; size; $i++)

{

do_stuff();

<h4>Where to put the braces:</h4>

<p>In PHP code, braces always go on their own line. The closing brace should also always be at the same column as the corresponding opening brace, examples:</p>

function do_stuff()

{

...

<p>In JavaScript code, braces always go on the same line:</p>

function do_stuff() {

...

<h4>Use spaces between tokens:</h4>

<p>This is another simple, easy step that helps keep code readable without much effort. Whenever you write an assignment, expression, etc.. Always leave <em>one</em> space between the tokens. Basically, write code as if it was English. Put spaces between variable names and operators. Don't put spaces just after an opening bracket or before a closing bracket. Don't put spaces just before a comma or a semicolon. This is best shown with a few examples, examples:</p>

for ($i = 0; $i &lt; $size; $i++) ...

$i=($j &lt; $size)?0:1;

<h4>Operator precedence:</h4>

<p>Do you know the exact precedence of all the operators in PHP? Neither do I. Don't guess. Always make it obvious by using brackets to force the precedence of an equation so you know what it does. Remember to not over-use this, as it may harden the readability. Basically, do not enclose single expressions. Examples:</p>

<p class="bad">// what's the result? who knows. </p>

<p class="bad">// now you can be certain what I'm doing here.</p>

<p class="good">// But this one is even better, because it is easier on the eye but the intention is preserved</p>

<h4>Quoting strings:</h4>

<p>There are two different ways to quote strings in PHP - either with single quotes or with double quotes. The main difference is that the parser does variable interpolation in double-quoted strings, but not in single quoted strings. Because of this, you should <em>always</em> use single quotes <em>unless</em> you specifically need variable interpolation to be done on that string. This way, we can save the parser the trouble of parsing a bunch of strings where no interpolation needs to be done.</p>

<div class="codebox"><pre>

$str = "This is a really long string with no variables for the parser to find.";

<p class="good">// right</p>

<div class="codebox"><pre>

$str = 'This is a really long string with no variables for the parser to find.';

<p class="bad">// Sometimes single quotes are just not right</p>

<div class="codebox"><pre>

<p class="good">// Double quotes are sometimes needed to not overcrowd the line with concatenations.</p>

<div class="codebox"><pre>

<p>In SQL statements mixing single and double quotes is partly allowed (following the guidelines listed here about SQL formatting), else one should try to only use one method - mostly single quotes.</p>

$foo = array(

'bar' => 42,

'boo' => 23

<p class="good">// right </p>

<div class="codebox"><pre>

$foo = array(

'bar' => 42,

'boo' => 23,

<h4>Associative array keys:</h4>

<p>In PHP, it's legal to use a literal string as a key to an associative array without quoting that string. We don't want to do this -- the string should always be quoted to avoid confusion. Note that this is only when we're using a literal, not when we're using a variable, examples:</p>

<p class="bad">// wrong</p>

<p class="good">// right </p>

<p class="bad">// wrong</p>

<p class="good">// right </p>

<h4>Comments:</h4>

<p>Each complex function should be preceded by a comment that tells a programmer everything they need to know to use that function. The meaning of every parameter, the expected input, and the output are required as a minimal comment. The function's behaviour in error conditions (and what those error conditions are) should also be present - but mostly included within the comment about the output.<br /><br />Especially important to document are any assumptions the code makes, or preconditions for its proper operation. Any one of the developers should be able to look at any part of the application and figure out what's going on in a reasonable amount of time.<br /><br />Avoid using <code>/* */</code> comment blocks for one-line comments, <code>//</code> should be used for one/two-liners.</p>

<p class="bad">// wrong </p>

<div class="codebox"><pre>

$array[++$i] = $j;

<p class="good">// right </p>

<div class="codebox"><pre>

$array[$i] = $j;

$array[$i] = $k;

<h4>Inline conditionals:</h4>

<p>Inline conditionals should only be used to do very simple things. Preferably, they will only be used to do assignments, and not for function calls or anything complex at all. They can be harmful to readability if used incorrectly, so don't fall in love with saving typing by using them, examples:</p>

<p class="bad">// Bad place to use them</p>

<div class="codebox"><pre>

<p class="good">// OK place to use them </p>

<div class="codebox"><pre>

<h4>Don't use uninitialized variables.</h4>

<p>For phpBB3, we intend to use a higher level of run-time error reporting. This will mean that the use of an uninitialized variable will be reported as a warning. These warnings can be avoided by using the built-in isset() function to check whether a variable has been set - but preferably the variable is always existing. For checking if an array has a key set this can come in handy though, examples:</p>

<p class="bad">// Wrong </p>

<p class="good">// Right </p>

<p class="good">// Also possible</p>

<p>The <code>empty()</code> function is useful if you want to check if a variable is not set or being empty (an empty string, 0 as an integer or string, NULL, false, an empty array or a variable declared, but without a value in a class). Therefore empty should be used in favor of <code>isset($array) &amp;&amp; sizeof($array) &gt; 0</code> - this can be written in a shorter way as <code>!empty($array)</code>.</p>

case 'mode2':

// I am doing something completely different here

break;

<p class="good">// Good </p>

<div class="codebox"><pre>

default:

// Always assume that a case was not caught

break;

<p class="good">// Also good, if you have more code between the case and the break </p>

<div class="codebox"><pre>

// Always assume that a case was not caught

break;

<p>Even if the break for the default case is not needed, it is sometimes better to include it just for readability and completeness.</p>

// Always assume that a case was not caught

break;

<h4>Class Members</h4>

<p>Use the explicit visibility qualifiers <code>public</code>, <code>private</code> and <code>protected</code> for all properties instead of <code>var</code>.

<p class="bad">//Wrong </p>

<div class="codebox"><pre>

var $x;

<p class="good">// Right </p>

<div class="codebox"><pre>

public $x;

<h4>Constants</h4>

<p>Prefer class constants over global constants created with <code>define()</code>.</p>

&lt;-one tab-&gt;WHERE a = 1

&lt;-two tabs-&gt;AND (b = 2

&lt;-three tabs-&gt;OR b = 3)

<p>Here the example with the tabs applied:</p>

WHERE a = 1

AND (b = 2

OR b = 3)

<h4>SQL Quotes: </h4>

<p>Use double quotes where applicable. (The variables in these examples are typecasted to integers beforehand.) Examples: </p>

<div class="codebox"><pre>

"UPDATE " . SOME_TABLE . " SET something = something_else WHERE a = $b";

<p class="good">// These are right. </p>

<div class="codebox"><pre>

'UPDATE ' . SOME_TABLE . " SET something = something_else WHERE a = $b";

<p>In other words use single quotes where no variable substitution is required or where the variable involved shouldn't appear within double quotes. Otherwise use double quotes.</p>

<div class="codebox"><pre>

$sql = 'SELECT *

FROM ' . SOME_TABLE . '

<p class="good">// This is right. </p>

<div class="codebox"><pre>

$sql = 'SELECT *

FROM ' . SOME_TABLE . '

<h4>Common DBAL methods: </h4>

<div class="codebox"><pre>

$sql = 'SELECT *

FROM ' . SOME_TABLE . "

<h4>sql_query_limit():</h4>

'moredata' =&gt; $another_int,

);

<p>To complete the example, this is how an update statement would look like:</p>

$sql = 'UPDATE ' . SOME_TABLE . '

SET ' . $db-&gt;sql_build_array('UPDATE', $sql_ary) . '

WHERE user_id = ' . (int) $user_id;

<p>The <code>$db-&gt;sql_build_array()</code> function supports the following modes: <code>INSERT</code> (example above), <code>INSERT_SELECT</code> (building query for <code>INSERT INTO table (...) SELECT value, column ...</code> statements), <code>UPDATE</code> (example above) and <code>SELECT</code> (for building WHERE statement [AND logic]).</p>

'moredata' =&gt; $another_int_2,

);

<h4>sql_in_set():</h4>

$sql = 'SELECT *

FROM ' . FORUMS_TABLE . '

WHERE ' . $db-&gt;sql_in_set('forum_id', $forum_ids);

<p>Based on the number of values in $forum_ids, the query can look differently.</p>

<p class="good">// SQL Statement if $forum_ids = array(1, 2, 3);</p>

<div class="codebox"><pre>

<p class="good">// SQL Statement if $forum_ids = array(1) or $forum_ids = 1</p>

<div class="codebox"><pre>

<p>Of course the same is possible for doing a negative match against a number of values:</p>

$sql = 'SELECT *

FROM ' . FORUMS_TABLE . '

WHERE ' . $db-&gt;sql_in_set('forum_id', $forum_ids, <strong>true</strong>);

<p>Based on the number of values in $forum_ids, the query can look differently here too.</p>

<p class="good">// SQL Statement if $forum_ids = array(1, 2, 3);</p>

<div class="codebox"><pre>

<p class="good">// SQL Statement if $forum_ids = array(1) or $forum_ids = 1</p>

<div class="codebox"><pre>

<p>If the given array is empty, an error will be produced.</p>

'ORDER_BY' =&gt; 'left_id',

);

<p>The possible first parameter for sql_build_query() is SELECT or SELECT_DISTINCT. As you can see, the logic is pretty self-explaining. For the LEFT_JOIN key, just add another array if you want to join on to tables for example. The added benefit of using this construct is that you are able to easily build the query statement based on conditions - for example the above LEFT_JOIN is only necessary if server side topic tracking is enabled; a slight adjustement would be:</p>

// Here we read the cookie data

}

<a name="optimizing"></a><h3>2.iv. Optimizations</h3>

for ($i = 0; $i &lt; sizeof($post_data); $i++)

{

do_something();

<p class="good">// You are able to assign the (not changing) result within the loop itself</p>

<div class="codebox"><pre>

for ($i = 0, $size = sizeof($post_data); $i &lt; $size; $i++)

{

do_something();

<h4>Use of in_array(): </h4>

<p>Try to avoid using in_array() on huge arrays, and try to not place them into loops if the array to check consist of more than 20 entries. in_array() can be very time consuming and uses a lot of cpu processing time. For little checks it is not noticeable, but if checked against a huge array within a loop those checks alone can take several seconds. If you need this functionality, try using isset() on the arrays keys instead, actually shifting the values into keys and vice versa. A call to <code>isset($array[$var])</code> is a lot faster than <code>in_array($var, array_keys($array))</code> for example.</p>

<p class="bad">// Old method, do not use it</p>

<div class="codebox"><pre>

$start = (isset($HTTP_GET_VARS['start'])) ? intval($HTTP_GET_VARS['start']) : intval($HTTP_POST_VARS['start']);

<p class="good">// Use request var and define a default variable (use the correct type)</p>

<div class="codebox"><pre>

$start = $request->variable('start', 0);

<p class="bad">// $start is an int, the following use of $request->variable() therefore is not allowed</p>

<div class="codebox"><pre>

<p class="good">// Getting an array, keys are integers, value defaults to 0</p>

<div class="codebox"><pre>

<p class="good">// Getting an array, keys are strings, value defaults to 0</p>

<div class="codebox"><pre>

<h4>Login checks/redirection: </h4>

<p>To show a forum login box use <code>login_forum_box($forum_data)</code>, else use the <code>login_box()</code> function.</p>

{

trigger_error('FORM_INVALID');

}

<p>The string passed to <code>add_form_key()</code> needs to match the string passed to <code>check_form_key()</code>. Another requirement for this to work correctly is that all forms include the <code>{S_FORM_TOKEN}</code> template variable.</p>

<div class="codebox"><pre>

$user-&gt;session_begin();

$auth-&gt;acl($user-&gt;data);

<p>The <code>$user-&gt;setup()</code> call can be used to pass on additional language definition and a custom style (used in viewforum).</p>

<p>All messages/errors should be outputted by calling <code>trigger_error()</code> using the appropriate message type and language string. Example:</p>

<div class="codebox"><pre>

<div class="codebox"><pre>

<div class="codebox"><pre>

<h4>Url formatting</h4>

<p>The <code>append_sid()</code> function from 2.0.x is available too, though it does not handle url alterations automatically. Please have a look at the code documentation if you want to get more details on how to use append_sid(). A sample call to append_sid() can look like this:</p>

<div class="codebox"><pre>

<h4>General function usage: </h4>

# Parent style

# Set value to empty or to this style's name if this style does not have a parent style

<a name="genstyling"></a><h3>3.2. General Styling Rules</h3>

<p>Templates should be produced in a consistent manner. Where appropriate they should be based off an existing copy, e.g. index, viewforum or viewtopic (the combination of which implement a range of conditional and variable forms). Please also note that the indentation and coding guidelines also apply to templates where possible.</p>

'PAGE_OF' =&gt; 'Page %s of %s',

/* Just grabbing the replacements as they

come and hope they are in the right order */

<p>&hellip; a clearer way to show explicit replacement ordering is to do:</p>

'PAGE_OF' =&gt; 'Page %1$s of %2$s',

/* Explicit ordering of the replacements,

even if they are the same order as English */

<p>Why bother at all? Because some languages, the string transliterated back to English might read something like:</p>

'PAGE_OF' =&gt; 'Total of %2$s pages, currently on page %1$s',

/* Explicit ordering of the replacements,

reversed compared to English as the total comes first */

<a name="usingplurals"></a><h3>6.iv. Using plurals</h3>

<div class="codebox"><pre>

...

$user->lang('NUMBER_OF_ELEPHANTS', $number_of_elephants);

<p>And the English translation would be:</p>

1 => 'You have 1 elephant', // Singular

2 => 'You have %d elephants', // Plural

),

<p>While the Bosnian translation can have more cases:</p>

2 => 'You have %d slona', // Used for 5, 6,

3 => ...

),

<p><strong>NOTE:</strong> It is okay to use plurals for an unknown number compared to a single item, when the number is not known and displayed:</p>

<div class="codebox"><pre>

...

'MODERATOR' => 'Moderator', // Your board has 1 moderator

'MODERATORS' => 'Moderators', // Your board has multiple moderators

<a name="writingstyle"></a><h3>6.v. Writing Style</h3>

...

'CONV_ERROR_NO_AVATAR_PATH'

=&gt; 'Note to developer: you must specify $convertor['avatar_path'] to use %s.',

<p class="good">// Good - Literal straight quotes should be escaped with a backslash, ie: \</p>

...

'CONV_ERROR_NO_AVATAR_PATH'

=&gt; 'Note to developer: you must specify $convertor[\'avatar_path\'] to use %s.',

<p>However, because phpBB3 now uses UTF-8 as its sole encoding, we can actually use this to our advantage and not have to remember to escape a straight quote when we don't have to:</p>

<div class="codebox"><pre>

...

'USE_PERMISSIONS' =&gt; 'Test out user's permissions',

<p class="good">// Okay - However, non-programmers wouldn't type "user\'s" automatically</p>

<div class="codebox"><pre>

...

'USE_PERMISSIONS' =&gt; 'Test out user\'s permissions',

<p class="good">// Best - Use the Unicode Right-Single-Quotation-Mark character</p>

<div class="codebox"><pre>

...

'USE_PERMISSIONS' =&gt; 'Test out user&rsquo;s permissions',

<p>The <code>&quot;</code> (straight double quote), <code>&lt;</code> (less-than sign) and <code>&gt;</code> (greater-than sign) characters can all be used as displayed glyphs or as part of HTML markup, for example:</p>

...

'FOO_BAR' =&gt; 'PHP version &lt; 5.3.3.&lt;br /&gt;

Visit &quot;Downloads&quot; at &lt;a href=&quot;http://www.php.net/&quot;&gt;www.php.net&lt;/a&gt;.',

<p class="good">// Okay - No more invalid HTML, but &quot;&amp;quot;&quot; is rather clumsy</p>

...

'FOO_BAR' =&gt; 'PHP version &amp;lt; 5.3.3.&lt;br /&gt;

Visit &amp;quot;Downloads&amp;quot; at &lt;a href=&quot;http://www.php.net/&quot;&gt;www.php.net&lt;/a&gt;.',

<p class="good">// Best - No more invalid HTML, and usage of correct typographical quotation marks</p>

...

'FOO_BAR' =&gt; 'PHP version &amp;lt; 5.3.3.&lt;br /&gt;

Visit &ldquo;Downloads&rdquo; at &lt;a href=&quot;http://www.php.net/&quot;&gt;www.php.net&lt;/a&gt;.',

<p>Lastly, the <code>&amp;</code> (ampersand) must always be entitised regardless of where it is used:</p>

<div class="codebox"><pre>

...

'FOO_BAR' =&gt; '&lt;a href=&quot;http://somedomain.tld/?foo=1&amp;bar=2&quot;&gt;Foo &amp; Bar&lt;/a&gt;.',

<p class="good">// Good - Valid HTML, amperands are correctly entitised in all cases</p>

<div class="codebox"><pre>

...

'FOO_BAR' =&gt; '&lt;a href=&quot;http://somedomain.tld/?foo=1&amp;amp;bar=2&quot;&gt;Foo &amp;amp; Bar&lt;/a&gt;.',

<p>As for how these charcters are entered depends very much on choice of Operating System, current language locale/keyboard configuration and native abilities of the text editor used to edit phpBB language files. Please see <a href="http://en.wikipedia.org/wiki/Unicode#Input_methods">http://en.wikipedia.org/wiki/Unicode#Input_methods</a> for more information.</p>