diff --git a/phpBB/docs/coding-guidelines.html b/phpBB/docs/coding-guidelines.html index fa3d362578..acf13e9443 100644 --- a/phpBB/docs/coding-guidelines.html +++ b/phpBB/docs/coding-guidelines.html @@ -109,21 +109,21 @@

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

-

Linefeeds:

+

Linefeeds:

Ensure that your editor is saving files in the UNIX format. This means lines are terminated with a newline, not with a CR/LF combo as they are on Win32, or whatever the Mac uses. Any decent editor should be able to do this, but it might not always be the default. Know your editor. If you want advice on Windows text editors, just ask one of the developers. Some of them do their editing on Win32.

- +

1.ii. File Header

Standard header for new files:

This template of the header must be included at the start of all phpBB files: 

-/** 
+/**
 *
 * @package {PACKAGENAME}
 * @version $Id: $
-* @copyright (c) 2007 phpBB Group 
-* @license http://opensource.org/licenses/gpl-license.php GNU Public License 
+* @copyright (c) 2007 phpBB Group
+* @license http://opensource.org/licenses/gpl-license.php GNU Public License
 *
 */
@@ -145,11 +145,11 @@

Files containing only functions:

- +

Do not forget to comment the functions (especially the first function following the header). Each function should have at least a comment of what this function does. For more complex functions it is recommended to document the parameters too.

Files containing only classes:

- +

Do not forget to comment the class. Classes need a separate @package definition, it is the same as the header package name. Apart from this special case the above statement for files containing only functions needs to be applied to classes and it's methods too.

Code following the header but only functions/classes file:

@@ -157,7 +157,7 @@

If this case is true, the best method to avoid documentation confusions is adding an ignore command, for example:

-/** 
+/**
 * {HEADER}
 */
 
@@ -285,7 +285,7 @@ while (condition)
 for ($i = 0; $i < size; $i++)
 	do_stuff($i);
- +

// These are all right. 

 if (condition)
@@ -293,12 +293,12 @@ if (condition)
 	do_stuff();
 }
 
-while (condition) 
+while (condition)
 {
 	do_stuff();
 }
 
-for ($i = 0; $i < size; $i++) 
+for ($i = 0; $i < size; $i++)
 {
 	do_stuff();
 }
@@ -308,29 +308,29 @@ for ($i = 0; $i < size; $i++)
 	
This one is a bit of a holy war, but we're going to use a style that can be summed up in one sentence: Braces always go on their own line. The closing brace should also always be at the same column as the corresponding opening brace, examples:

 
 	
-if (condition) 
+if (condition)
 {
 	while (condition2)
 	{
 		...
 	}
 }
-else 
+else
 {
 	...
 }
 
-for ($i = 0; $i < $size; $i++) 
+for ($i = 0; $i < $size; $i++)
 {
 	...
 }
 
-while (condition) 
+while (condition)
 {
 	...
 }
 
-function do_stuff() 
+function do_stuff()
 {
 	...
 }
@@ -344,19 +344,19 @@ function do_stuff()
 	
 $i=0;
 $i = 0;
-		
+
 if($i<7) ...
 if ($i < 7) ...
-		
+
 if ( ($i < 7)&&($j > 8) ) ...
 if ($i < 7 && $j > 8) ...
-		
+
 do_stuff( $i, 'foo', $b );
 do_stuff($i, 'foo', $b);
-		
+
 for($i=0; $i<$size; $i++) ...
-for ($i = 0; $i < $size; $i++) ... 
-		
+for ($i = 0; $i < $size; $i++) ...
+
 $i=($j < $size)?0:1;
 $i = ($j < $size) ? 0 : 1;
 	

@@ -532,9 +532,9 @@ switch ($mode)
 		// I am doing something here
 
 	break;
-	
+
 	case 'mode2':
-	
+
 		// I am doing something completely different here
 
 	break;
@@ -556,7 +556,7 @@ switch ($mode)
 switch ($mode)
 {
 	case 'mode1':
-	
+
 		// I am doing something here
 
 	// no break here
@@ -585,22 +585,22 @@ switch ($mode)
 	
SQL Statements are often unreadable without some formatting, since they tend to be big at times. Though the formatting of sql statements adds a lot to the readability of code. SQL statements should be formatted in the following way, basically writing keywords: 

 
 	
-$sql = 'SELECT * 
-<-one tab->FROM ' . SOME_TABLE . ' 
-<-one tab->WHERE a = 1 
-<-two tabs->AND (b = 2 
-<-three tabs->OR b = 3) 
+$sql = 'SELECT *
+<-one tab->FROM ' . SOME_TABLE . '
+<-one tab->WHERE a = 1
+<-two tabs->AND (b = 2
+<-three tabs->OR b = 3)
 <-one tab->ORDER BY b';
 	

 
 	
Here the example with the tabs applied:

 
 	
-$sql = 'SELECT * 
-	FROM ' . SOME_TABLE . ' 
-	WHERE a = 1 
-		AND (b = 2 
-			OR b = 3) 
+$sql = 'SELECT *
+	FROM ' . SOME_TABLE . '
+	WHERE a = 1
+		AND (b = 2
+			OR b = 3)
 	ORDER BY b';
 	

 
@@ -609,18 +609,18 @@ $sql = 'SELECT *
 
 	
// These are wrong.

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

 
 	
// These are right. 

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

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.

@@ -629,15 +629,15 @@ $sql = 'SELECT *

// This is wrong.

-$sql = 'SELECT * 
-	FROM ' . SOME_TABLE . ' 
+$sql = 'SELECT *
+	FROM ' . SOME_TABLE . '
 	WHERE a != 2';

// This is right. 

-$sql = 'SELECT * 
-	FROM ' . SOME_TABLE . ' 
+$sql = 'SELECT *
+	FROM ' . SOME_TABLE . '
 	WHERE a <> 2';
@@ -684,7 +684,7 @@ $sql_ary = array( 'moredata' => $another_int ); -$sql = 'UPDATE ' . SOME_TABLE . ' +$sql = 'UPDATE ' . SOME_TABLE . ' SET ' . $db->sql_build_array('UPDATE', $sql_ary) . ' WHERE user_id = ' . (int) $user_id; $db->sql_query($sql); @@ -762,7 +762,7 @@ $sql_array = array( ) ), - 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' + 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' AND f.forum_id = fw.forum_id', 'ORDER_BY' => 'left_id' @@ -782,7 +782,7 @@ $sql_array = array( FORUMS_TABLE => 'f' ), - 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' + 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' AND f.forum_id = fw.forum_id', 'ORDER_BY' => 'left_id' @@ -880,6 +880,23 @@ $action_ary = request_var('action', array('' => 0));

Sensitive Operations:

For sensitive operations always let the user confirm the action. For the confirmation screens, make use of the confirm_box() function.

+

Altering Operations:

+

For operations altering the state of the database, for instance posting, always verify the form token, unless you are already using confirm_box(). To do so, make use of the add_form_key() and check_form_key() functions.

+ 
+	add_form_key('my_form');
+
+	if ($submit)
+	{
+		if (!check_form_token('my_form'))
+		{
+			trigger_error('FORM_INVALID');
+		}
+	}
+
+ +

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

+ +

Sessions:

Sessions should be initiated on each page, as near the top as possible using the following code:

@@ -1396,6 +1413,18 @@ div

Just always remember that processing is taking place from up to down.

+

Forms

+

If a form is used for a non-trivial operation (i.e. more than a jumpbox), then it should include the {S_FORM_TOKEN} template variable.

+ 
+<form method="post" id="mcp" action="{U_POST_ACTION}">
+
+	<fieldset class="submit-buttons">
+		<input type="reset" value="{L_RESET}" name="reset" class="button2" /> 
+		<input type="submit" name="action[add_warning]" value="{L_SUBMIT}" class="button1" />
+	</fieldset>
+	{S_FORM_TOKEN}
+</form>
+

Back to Top
@@ -1405,6 +1434,8 @@ div
+ +

5. Character Sets and Encodings

@@ -1412,6 +1443,8 @@ div
+ +

What are Unicode, UCS and UTF-8?

The Universal Character Set (UCS) described in ISO/IEC 10646 consists of a large amount of characters. Each of them has a unique name and a code point which is an integer number. Unicode - which is an industry standard - complements the Universal Character Set with further information about the characters' properties and alternative character encodings. More information on Unicode can be found on the Unicode Consortium's website. One of the Unicode encodings is the 8-bit Unicode Transformation Format (UTF-8). It encodes characters with up to four bytes aiming for maximum compatability with the American Standard Code for Information Interchange which is a 7-bit encoding of a relatively small subset of the UCS.

@@ -1495,13 +1528,13 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))

6.i. Standardisation

- +

Reason:

- +

phpBB is one of the most translated open-source projects, with the current stable version being available in over 60 localisations. Whilst the ad hoc approach to the naming of language packs has worked, for phpBB3 and beyond we hope to make this process saner which will allow for better interoperation with current and future web browsers.

- +

Encoding:

- +

With phpBB3, the output encoding for the forum in now UTF-8, a Universal Character Encoding by the Unicode Consortium that is by design a superset to US-ASCII and ISO-8859-1. By using one character set which simultaenously supports all scripts which previously would have required different encodings (eg: ISO-8859-1 to ISO-8859-15 (Latin, Greek, Cyrillic, Thai, Hebrew, Arabic); GB2312 (Simplified Chinese); Big5 (Traditional Chinese), EUC-JP (Japanese), EUC-KR (Korean), VISCII (Vietnamese); et cetera), this removes the need to convert between encodings and improves the accessibility of multilingual forums.

The impact is that the language files for phpBB must now also be encoded as UTF-8, with a caveat that the files must not contain a BOM for compatibility reasons with non-Unicode aware versions of PHP. For those with forums using the Latin character set (ie: most European languages), this change is transparent since UTF-8 is superset to US-ASCII and ISO-8859-1.

@@ -1835,7 +1868,7 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
  • Language's local name
  • Authors information
    • - +

    iso.txt is automatically generated by the language pack submission system on phpBB.com. You don't have to create this file yourself if you plan on releasing your language pack on phpBB.com, but do keep in mind that phpBB itself does require this file to be present.

    Because language tags themselves are meant to be machine read, they can be rather obtuse to humans and why descriptive strings as provided by iso.txt are needed. Whilst en-US could be fairly easily deduced to be "English as used in the United States", de-CH is more difficult less one happens to know that de is from "Deutsch", German for "German" and CH is the abbreviation of the official Latin name for Switzerland, "Confoederatio Helvetica".

    @@ -1889,11 +1922,11 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))

    For the localised language description, just translate the English version though use whatever appropriate punctuation typical for your own locale, assuming the language uses punctuation at all.

    Unicode bi-directional considerations:

    - +

    Because phpBB is now UTF-8, all translators must take into account that certain strings may be shown when the directionality of the document is either opposite to normal or is ambiguous.

    - +

    The various Unicode control characters for bi-directional text and their HTML enquivalents where appropriate are as follows:

    - + @@ -1957,9 +1990,9 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
    Unicode bidirectional control characters & HTML elements/entities
    - +

    For iso.txt, the directionality of the text can be explicitly set using special Unicode characters via any of the three methods provided by left-to-right/right-to-left markers/embeds/overrides, as without them, the ordering of characters will be incorrect, eg:

    - + @@ -2003,15 +2036,15 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
    Unicode bidirectional control characters iso.txt
    - +

    In choosing which of the three methods to use, in the majority of cases, the LRM or RLM to put a "strong" character to fully enclose an ambiguous punctuation character and thus make it inherit the correct directionality is sufficient.

    Within some cases, there may be mixed scripts of a left-to-right and right-to-left direction, so using LRE & RLE with PDF may be more appropriate. Lastly, in very rare instances where directionality must be forced, then use LRO & RLO with PDF.

    For further information on authoring techniques of bi-directional text, please see the W3C tutorial on authoring techniques for XHTML pages with bi-directional text.

    - +

    Working with placeholders:

    - +

    As phpBB is translated into languages with different ordering rules to that of English, it is possible to show specific values in any order deemed appropriate. Take for example the extremely simple "Page X of Y", whilst in English this could just be coded as:

    - + 
     	...
 'PAGE_OF'	=>	'Page %s of %s',
@@ -2019,9 +2052,9 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
 		come and hope they are in the right order */
 	...
    - +

    … a clearer way to show explicit replacement ordering is to do:

    - + 
     	...
 'PAGE_OF'	=>	'Page %1$s of %2$s',
@@ -2029,9 +2062,9 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
 		even if they are the same order as English */
 	...
    - +

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

    - + 
     	...
 'PAGE_OF'	=>	'Total of %2$s pages, currently on page %1$s',
@@ -2039,104 +2072,104 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
 		reversed compared to English as the total comes first */
 	...
    - +

    6.iii. Writing Style

    - +

    Miscellaneous tips & hints:

    - +

    As the language files are PHP files, where the various strings for phpBB are stored within an array which in turn are used for display within an HTML page, rules of syntax for both must be considered. Potentially problematic characters are: ' (straight quote/apostrophe), " (straight double quote), < (less-than sign), > (greater-than sign) and & (ampersand).

    - +

    // Bad - The un-escapsed straight-quote/apostrophe will throw a PHP parse error

    - + 
     	...
 'CONV_ERROR_NO_AVATAR_PATH'
 	=>	'Note to developer: you must specify $convertor['avatar_path'] to use %s.',
 	...
    - +

    // Good - Literal straight quotes should be escaped with a backslash, ie: \

    - + 
     	...
 'CONV_ERROR_NO_AVATAR_PATH'
 	=>	'Note to developer: you must specify $convertor[\'avatar_path\'] to use %s.',
 	...
    - +

    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:

    - +

    // Bad - The un-escapsed straight-quote/apostrophe will throw a PHP parse error

    - + 
     	...
 'USE_PERMISSIONS'	=>	'Test out user's permissions',
 	...
    - +

    // Okay - However, non-programmers wouldn't type "user\'s" automatically

    - + 
     	...
 'USE_PERMISSIONS'	=>	'Test out user\'s permissions',
 	...
    - +

    // Best - Use the Unicode Right-Single-Quotation-Mark character

    - + 
     	...
 'USE_PERMISSIONS'	=>	'Test out user’s permissions',
 	...
    - +

    The " (straight double quote), < (less-than sign) and > (greater-than sign) characters can all be used as displayed glyphs or as part of HTML markup, for example:

    - +

    // Bad - Invalid HTML, as segments not part of elements are not entitised

    - + 
     	...
 'FOO_BAR'	=>	'PHP version < 4.3.3.<br />
 	Visit "Downloads" at <a href="http://www.php.net/">www.php.net</a>.',
 	...
    - +

    // Okay - No more invalid HTML, but "&quot;" is rather clumsy

    - + 
     	...
 'FOO_BAR'	=>	'PHP version &lt; 4.3.3.<br />
 	Visit &quot;Downloads&quot; at <a href="http://www.php.net/">www.php.net</a>.',
 	...
    - +

    // Best - No more invalid HTML, and usage of correct typographical quotation marks

    - + 
     	...
 'FOO_BAR'	=>	'PHP version &lt; 4.3.3.<br />
 	Visit “Downloads” at <a href="http://www.php.net/">www.php.net</a>.',
 	...
    - +

    Lastly, the & (ampersand) must always be entitised regardless of where it is used:

    - +

    // Bad - Invalid HTML, none of the ampersands are entitised

    - + 
     	...
 'FOO_BAR'	=>	'<a href="http://somedomain.tld/?foo=1&bar=2">Foo & Bar</a>.',
 	...
    - +

    // Good - Valid HTML, amperands are correctly entitised in all cases

    - + 
     	...
 'FOO_BAR'	=>	'<a href="http://somedomain.tld/?foo=1&amp;bar=2">Foo &amp; Bar</a>.',
 	...
    - +

    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 http://en.wikipedia.org/wiki/Unicode#Input_methods for more information.

    Spelling, punctuation, grammar, et cetera: