<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>