Blame Identity/Webenv/App/phpBB/3.0.4/docs/coding-guidelines.html

f2e824
f2e824
<html xmlns="http://www.w3.org/1999/xhtml" dir="ltr" lang="en" xml:lang="en">
f2e824
<head>
f2e824
f2e824
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
f2e824
<meta http-equiv="content-style-type" content="text/css" />
f2e824
<meta http-equiv="content-language" content="en" />
f2e824
<meta http-equiv="imagetoolbar" content="no" />
f2e824
<meta name="resource-type" content="document" />
f2e824
<meta name="distribution" content="global" />
f2e824
<meta name="copyright" content="2007 phpBB Group" />
f2e824
<meta name="keywords" content="" />
f2e824
<meta name="description" content="Olympus coding guidelines document" />
f2e824
<title>phpBB3 • Coding Guidelines</title>
f2e824
f2e824
<link href="stylesheet.css" rel="stylesheet" type="text/css" media="screen, projection" />
f2e824
f2e824
</head>
f2e824
f2e824
<body id="phpbb" class="section-docs">
f2e824
f2e824
f2e824
	
f2e824
	
f2e824
		
f2e824
			
f2e824
f2e824
			
f2e824
				
f2e824
				

Coding Guidelines

f2e824
				

Olympus coding guidelines document

f2e824
				

Skip

f2e824
			
f2e824
f2e824
			
f2e824
		
f2e824
	
f2e824
f2e824
	
f2e824
f2e824
	
f2e824
f2e824
f2e824
f2e824

These are the phpBB Coding Guidelines for Olympus, all attempts should be made to follow them as closely as possible.

f2e824
f2e824

Coding Guidelines

f2e824
f2e824
	
f2e824
		
f2e824
f2e824
		
f2e824
f2e824
    f2e824
    	
  1. Defaults
  2. f2e824
    	
      f2e824
      		
    1. Editor Settings
    2. f2e824
      		
    3. File Header
    4. f2e824
      		
    5. File Locations
    6. f2e824
      	
      f2e824
      	
      f2e824
      	
    7. Code Layout/Guidelines
    8. f2e824
      	
        f2e824
        		
      1. Variable/Function Naming
      2. f2e824
        		
      3. Code Layout
      4. f2e824
        		
      5. SQL/SQL Layout
      6. f2e824
        		
      7. Optimizations
      8. f2e824
        		
      9. General Guidelines
      10. f2e824
        	
        f2e824
        	
        f2e824
        	
      11. Styling
      12. f2e824
        	
          f2e824
          		
        1. Style Config Files
        2. f2e824
          		
        3. General Styling Rules
        4. f2e824
          	
          f2e824
          	
        5. Templating
        6. f2e824
          	
            f2e824
            		
          1. General Templating
          2. f2e824
            		
          3. Template Inheritance
          4. f2e824
            	
            f2e824
            	
          5. Character Sets and Encodings
          6. f2e824
            	
          7. Translation (i18n/L10n) Guidelines
          8. f2e824
            	
              f2e824
              		
            1. Standardisation
            2. f2e824
              		
            3. Other considerations
            4. f2e824
              		
            5. Writing Style
            6. f2e824
              	
              f2e824
              	
              f2e824
              	
            7. Guidelines Changelog
            8. f2e824
              	
            9. Copyright and disclaimer
            10. f2e824
              f2e824
              f2e824
              		
              f2e824
              f2e824
              		
              f2e824
              	
              f2e824
              f2e824
              	
              f2e824
              f2e824

              1. Defaults

              f2e824
              f2e824
              	
              f2e824
              		
              f2e824
              f2e824
              		
              f2e824
              f2e824

              1.i. Editor Settings

              f2e824
              f2e824
              	

              Tabs vs Spaces:

              f2e824
              	

              In order to make this as simple as possible, we will be using tabs, not spaces. We enforce 4 (four) spaces for one tab - therefore you need to set your tab width within your editor to 4 spaces. Make sure that when you save the file, it's saving tabs and not spaces. This way, we can each have the code be displayed the way we like it, without breaking the layout of the actual files.

              f2e824
              	

              Tabs in front of lines are no problem, but having them within the text can be a problem if you do not set it to the amount of spaces every one of us uses. Here is a short example of how it should look like:

              f2e824
              f2e824
              	
              f2e824
              {TAB}$mode{TAB}{TAB}= request_var('mode', '');
              f2e824
              {TAB}$search_id{TAB}= request_var('search_id', '');
              f2e824
              	
              f2e824
              f2e824
              	

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

              f2e824
              f2e824
              	

              Linefeeds:

              f2e824
              	

              Ensure that your editor is saving files in the UNIX (LF) line ending format. This means that lines are terminated with a newline, not with Windows Line endings (CR/LF combo) as they are on Win32 or Classic Mac (CR) Line endings. Any decent editor should be able to do this, but it might not always be the default setting. Know your editor. If you want advice for an editor for your Operating System, just ask one of the developers. Some of them do their editing on Win32.

              f2e824
              f2e824
              	

              1.ii. File Header

              f2e824
              f2e824
              	

              Standard header for new files:

              f2e824
              	

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

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

              Please see the File Locations section for the correct package name.

              f2e824
              f2e824
              	

              Files containing inline code:

              f2e824
              f2e824
              	

              For those files you have to put an empty comment directly after the header to prevent the documentor assigning the header to the first code element found.

              f2e824
              f2e824
              	
              f2e824
              /**
              f2e824
              * {HEADER}
              f2e824
              */
              f2e824
              f2e824
              /**
              f2e824
              */
              f2e824
              {CODE}
              f2e824
              	
              f2e824
              f2e824
              	

              Files containing only functions:

              f2e824
              f2e824
              	

              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.

              f2e824
              f2e824
              	

              Files containing only classes:

              f2e824
              f2e824
              	

              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.

              f2e824
              f2e824
              	

              Code following the header but only functions/classes file:

              f2e824
              f2e824
              	

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

              f2e824
              f2e824
              	
              f2e824
              /**
              f2e824
              * {HEADER}
              f2e824
              */
              f2e824
              f2e824
              /**
              f2e824
              * @ignore
              f2e824
              */
              f2e824
              Small code snipped, mostly one or two defines or an if statement
              f2e824
              f2e824
              /**
              f2e824
              * {DOCUMENTATION}
              f2e824
              */
              f2e824
              class ...
              f2e824
              	
              f2e824
              f2e824
              	

              1.iii. File Locations

              f2e824
              f2e824
              	

              Functions used by more than one page should be placed in functions.php, functions specific to one page should be placed on that page (at the bottom) or within the relevant sections functions file. Some files in /includes are holding functions responsible for special sections, for example uploading files, displaying "things", user related functions and so forth.

              f2e824
              f2e824
              	

              The following packages are defined, and related new features/functions should be placed within the mentioned files/locations, as well as specifying the correct package name. The package names are bold within this list:

              f2e824
              f2e824
              	
                f2e824
                		
              • phpBB3
                Core files and all files not assigned to a separate package
              • f2e824
                		
              • acm
                /includes/acm, /includes/cache.php
                Cache System
              • f2e824
                		
              • acp
                /adm, /includes/acp, /includes/functions_admin.php
                Administration Control Panel
              • f2e824
                		
              • dbal
                /includes/db
                Database Abstraction Layer.
                Base class is dbal
              • f2e824
                			
                  f2e824
                  				
                • /includes/db/dbal.php
                  Base DBAL class, defining the overall framework
                • f2e824
                  				
                • /includes/db/firebird.php
                  Firebird/Interbase Database Abstraction Layer
                • f2e824
                  				
                • /includes/db/msssql.php
                  MSSQL Database Abstraction Layer
                • f2e824
                  				
                • /includes/db/mssql_odbc.php
                  MSSQL ODBC Database Abstraction Layer for MSSQL
                • f2e824
                  				
                • /includes/db/mysql.php
                  MySQL Database Abstraction Layer for MySQL 3.x/4.0.x/4.1.x/5.x
                • f2e824
                  				
                • /includes/db/mysqli.php
                  MySQLi Database Abstraction Layer
                • f2e824
                  				
                • /includes/db/oracle.php
                  Oracle Database Abstraction Layer
                • f2e824
                  				
                • /includes/db/postgres.php
                  PostgreSQL Database Abstraction Layer
                • f2e824
                  				
                • /includes/db/sqlite.php
                  Sqlite Database Abstraction Layer
                • f2e824
                  			
                  f2e824
                  		
                  f2e824
                  		
                • diff
                  /includes/diff
                  Diff Engine
                • f2e824
                  		
                • docs
                  /docs
                  phpBB Documentation
                • f2e824
                  		
                • images
                  /images
                  All global images not connected to styles
                • f2e824
                  		
                • install
                  /install
                  Installation System
                • f2e824
                  		
                • language
                  /language
                  All language files
                • f2e824
                  		
                • login
                  /includes/auth
                  Login Authentication Plugins
                • f2e824
                  		
                • VC
                  /includes/captcha
                  CAPTCHA
                • f2e824
                  		
                • mcp
                  mcp.php, /includes/mcp, report.php
                  Moderator Control Panel
                • f2e824
                  		
                • ucp
                  ucp.php, /includes/ucp
                  User Control Panel
                • f2e824
                  		
                • utf
                  /includes/utf
                  UTF8-related functions/classes
                • f2e824
                  		
                • search
                  /includes/search, search.php
                  Search System
                • f2e824
                  		
                • styles
                  /styles, style.php
                  phpBB Styles/Templates/Themes/Imagesets
                • f2e824
                  	
                  f2e824
                  f2e824
                  		
                  f2e824
                  f2e824
                  		
                  f2e824
                  f2e824
                  		
                  f2e824
                  	
                  f2e824
                  f2e824
                  	
                  f2e824
                  f2e824

                  2. Code Layout/Guidelines

                  f2e824
                  f2e824
                  	
                  f2e824
                  		
                  f2e824
                  f2e824
                  		
                  f2e824
                  f2e824
                  	

                  Please note that these Guidelines applies to all php, html, javascript and css files.

                  f2e824
                  f2e824
                  	

                  2.i. Variable/Function Naming

                  f2e824
                  f2e824
                  	

                  We will not be using any form of hungarian notation in our naming conventions. Many of us believe that hungarian naming is one of the primary code obfuscation techniques currently in use.

                  f2e824
                  f2e824
                  	

                  Variable Names:

                  f2e824
                  	

                  Variable names should be in all lowercase, with words separated by an underscore, example:

                  f2e824
                  f2e824
                  	
                  f2e824
                  		

                  $current_user is right, but $currentuser and $currentUser are not.

                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Names should be descriptive, but concise. We don't want huge sentences as our variable names, but typing an extra couple of characters is always better than wondering what exactly a certain variable is for.

                  f2e824
                  f2e824
                  	

                  Loop Indices:

                  f2e824
                  	

                  The only situation where a one-character variable name is allowed is when it's the index for some looping construct. In this case, the index of the outer loop should always be $i. If there's a loop inside that loop, its index should be $j, followed by $k, and so on. If the loop is being indexed by some already-existing variable with a meaningful name, this guideline does not apply, example:

                  f2e824
                  f2e824
                  	
                  f2e824
                  for ($i = 0; $i < $outer_size; $i++)
                  f2e824
                  {
                  f2e824
                     for ($j = 0; $j < $inner_size; $j++)
                  f2e824
                     {
                  f2e824
                        foo($i, $j);
                  f2e824
                     }
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Function Names:

                  f2e824
                  	

                  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. Function names should preferably have a verb in them somewhere. Good function names are print_login_status(), get_user_data(), etc.

                  f2e824
                  f2e824
                  	

                  Function Arguments:

                  f2e824
                  	

                  Arguments are subject to the same guidelines as variable names. We don't want a bunch of functions like: do_stuff($a, $b, $c). In most cases, we'd like to be able to tell how to use a function by just looking at its declaration.

                  f2e824
                  f2e824
                  	

                  Summary:

                  f2e824
                  	

                  The basic philosophy here is to not hurt code clarity for the sake of laziness. This has to be balanced by a little bit of common sense, though; print_login_status_for_a_given_user() goes too far, for example -- that function would be better named print_user_login_status(), or just print_login_status().

                  f2e824
                  f2e824
                  	

                  Special Namings:

                  f2e824
                  	

                  For all emoticons use the term smiley in singular and smilies in plural.

                  f2e824
                  f2e824
                  	

                  2.ii. Code Layout

                  f2e824
                  f2e824
                  	

                  Always include the braces:

                  f2e824
                  	

                  This is another case of being too lazy to type 2 extra characters causing problems with code clarity. Even if the body of some construct is only one line long, do not drop the braces. Just don't, examples:

                  f2e824
                  f2e824
                  	

                  // These are all wrong.

                  f2e824
                  f2e824
                  	
                  f2e824
                  if (condition) do_stuff();
                  f2e824
                  f2e824
                  if (condition)
                  f2e824
                  	do_stuff();
                  f2e824
                  f2e824
                  while (condition)
                  f2e824
                  	do_stuff();
                  f2e824
                  f2e824
                  for ($i = 0; $i < size; $i++)
                  f2e824
                  	do_stuff($i);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // These are all right.

                  f2e824
                  	
                  f2e824
                  if (condition)
                  f2e824
                  {
                  f2e824
                  	do_stuff();
                  f2e824
                  }
                  f2e824
                  f2e824
                  while (condition)
                  f2e824
                  {
                  f2e824
                  	do_stuff();
                  f2e824
                  }
                  f2e824
                  f2e824
                  for ($i = 0; $i < size; $i++)
                  f2e824
                  {
                  f2e824
                  	do_stuff();
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Where to put the braces:

                  f2e824
                  	

                  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:

                  f2e824
                  f2e824
                  	
                  f2e824
                  if (condition)
                  f2e824
                  {
                  f2e824
                  	while (condition2)
                  f2e824
                  	{
                  f2e824
                  		...
                  f2e824
                  	}
                  f2e824
                  }
                  f2e824
                  else
                  f2e824
                  {
                  f2e824
                  	...
                  f2e824
                  }
                  f2e824
                  f2e824
                  for ($i = 0; $i < $size; $i++)
                  f2e824
                  {
                  f2e824
                  	...
                  f2e824
                  }
                  f2e824
                  f2e824
                  while (condition)
                  f2e824
                  {
                  f2e824
                  	...
                  f2e824
                  }
                  f2e824
                  f2e824
                  function do_stuff()
                  f2e824
                  {
                  f2e824
                  	...
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Use spaces between tokens:

                  f2e824
                  	

                  This is another simple, easy step that helps keep code readable without much effort. Whenever you write an assignment, expression, etc.. Always leave one 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:

                  f2e824
                  f2e824
                  	

                  // Each pair shows the wrong way followed by the right way.

                  f2e824
                  f2e824
                  	
                  f2e824
                  $i=0;
                  f2e824
                  $i = 0;
                  f2e824
                  f2e824
                  if($i<7) ...
                  f2e824
                  if ($i < 7) ...
                  f2e824
                  f2e824
                  if ( ($i < 7)&&($j > 8) ) ...
                  f2e824
                  if ($i < 7 && $j > 8) ...
                  f2e824
                  f2e824
                  do_stuff( $i, 'foo', $b );
                  f2e824
                  do_stuff($i, 'foo', $b);
                  f2e824
                  f2e824
                  for($i=0; $i<$size; $i++) ...
                  f2e824
                  for ($i = 0; $i < $size; $i++) ...
                  f2e824
                  f2e824
                  $i=($j < $size)?0:1;
                  f2e824
                  $i = ($j < $size) ? 0 : 1;
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Operator precedence:

                  f2e824
                  	

                  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:

                  f2e824
                  f2e824
                  	

                  // what's the result? who knows.

                  f2e824
                  	
                  f2e824
                  $bool = ($i < 7 && $j > 8 || $k == 4);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // now you can be certain what I'm doing here.

                  f2e824
                  	
                  f2e824
                  $bool = (($i < 7) && (($j < 8) || ($k == 4)));
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // But this one is even better, because it is easier on the eye but the intention is preserved

                  f2e824
                  	
                  f2e824
                  $bool = ($i < 7 && ($j < 8 || $k == 4));
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Quoting strings:

                  f2e824
                  	

                  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 always use single quotes unless 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.

                  f2e824
                  	

                  Also, if you are using a string variable as part of a function call, you do not need to enclose that variable in quotes. Again, this will just make unnecessary work for the parser. Note, however, that nearly all of the escape sequences that exist for double-quoted strings will not work with single-quoted strings. Be careful, and feel free to break this guideline if it's making your code easier to read, examples:

                  f2e824
                  f2e824
                  	

                  // wrong

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

                  // right

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

                  // Sometimes single quotes are just not right

                  f2e824
                  	
                  f2e824
                  $post_url = $phpbb_root_path . 'posting.' . $phpEx . '?mode=' . $mode . '&amp;start=' . $start;
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // Double quotes are sometimes needed to not overcroud the line with concentinations

                  f2e824
                  	
                  f2e824
                  $post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&amp;start=$start";
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  In SQL Statements mixing single and double quotes is partly allowed (following the guidelines listed here about SQL Formatting), else it should be tryed to only use one method - mostly single quotes.

                  f2e824
                  f2e824
                  	

                  Associative array keys:

                  f2e824
                  	

                  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:

                  f2e824
                  f2e824
                  	

                  // wrong

                  f2e824
                  	
                  f2e824
                  $foo = $assoc_array[blah];
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // right

                  f2e824
                  	
                  f2e824
                  $foo = $assoc_array['blah'];
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // wrong

                  f2e824
                  	
                  f2e824
                  $foo = $assoc_array["$var"];
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // right

                  f2e824
                  	
                  f2e824
                  $foo = $assoc_array[$var];
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Comments:

                  f2e824
                  	

                  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.

                  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.

                  Avoid using /* */ comment blocks for one-line comments, // should be used for one/two-liners.

                  f2e824
                  f2e824
                  	

                  Magic numbers:

                  f2e824
                  	

                  Don't use them. Use named constants for any literal value other than obvious special cases. Basically, it's ok to check if an array has 0 elements by using the literal 0. It's not ok to assign some special meaning to a number and then use it everywhere as a literal. This hurts readability AND maintainability. The constants true and false should be used in place of the literals 1 and 0 -- even though they have the same values (but not type!), it's more obvious what the actual logic is when you use the named constants. Typecast variables where it is needed, do not rely on the correct variable type (PHP is currently very loose on typecasting which can lead to security problems if a developer does not have a very close eye to it).

                  f2e824
                  f2e824
                  	

                  Shortcut operators:

                  f2e824
                  	

                  The only shortcut operators that cause readability problems are the shortcut increment $i++ and decrement $j-- operators. These operators should not be used as part of an expression. They can, however, be used on their own line. Using them in expressions is just not worth the headaches when debugging, examples:

                  f2e824
                  f2e824
                  	

                  // wrong

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

                  // right

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

                  Inline conditionals:

                  f2e824
                  	

                  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:

                  f2e824
                  f2e824
                  	

                  // Bad place to use them

                  f2e824
                  	
                  f2e824
                  ($i < $size && $j > $size) ? do_stuff($foo) : do_stuff($bar);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // OK place to use them

                  f2e824
                  	
                  f2e824
                  $min = ($i < $j) ? $i : $j;
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Don't use uninitialized variables.

                  f2e824
                  	

                  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:

                  f2e824
                  f2e824
                  	

                  // Wrong

                  f2e824
                  	
                  f2e824
                  if ($forum) ...
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // Right

                  f2e824
                  	
                  f2e824
                  if (isset($forum)) ...
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // Also possible

                  f2e824
                  	
                  f2e824
                  if (isset($forum) && $forum == 5)
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  The empty() 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 isset($array) && sizeof($array) > 0 - this can be written in a shorter way as !empty($array).

                  f2e824
                  f2e824
                  	

                  Switch statements:

                  f2e824
                  	

                  Switch/case code blocks can get a bit long sometimes. To have some level of notice and being in-line with the opening/closing brace requirement (where they are on the same line for better readability), this also applies to switch/case code blocks and the breaks. An example:

                  f2e824
                  f2e824
                  	

                  // Wrong

                  f2e824
                  	
                  f2e824
                  switch ($mode)
                  f2e824
                  {
                  f2e824
                  	case 'mode1':
                  f2e824
                  		// I am doing something here
                  f2e824
                  		break;
                  f2e824
                  	case 'mode2':
                  f2e824
                  		// I am doing something completely different here
                  f2e824
                  		break;
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // Good

                  f2e824
                  	
                  f2e824
                  switch ($mode)
                  f2e824
                  {
                  f2e824
                  	case 'mode1':
                  f2e824
                  		// I am doing something here
                  f2e824
                  	break;
                  f2e824
                  f2e824
                  	case 'mode2':
                  f2e824
                  		// I am doing something completely different here
                  f2e824
                  	break;
                  f2e824
                  f2e824
                  	default:
                  f2e824
                  		// Always assume that a case was not caught
                  f2e824
                  	break;
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // Also good, if you have more code between the case and the break

                  f2e824
                  	
                  f2e824
                  switch ($mode)
                  f2e824
                  {
                  f2e824
                  	case 'mode1':
                  f2e824
                  f2e824
                  		// I am doing something here
                  f2e824
                  f2e824
                  	break;
                  f2e824
                  f2e824
                  	case 'mode2':
                  f2e824
                  f2e824
                  		// I am doing something completely different here
                  f2e824
                  f2e824
                  	break;
                  f2e824
                  f2e824
                  	default:
                  f2e824
                  f2e824
                  		// Always assume that a case was not caught
                  f2e824
                  f2e824
                  	break;
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

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

                  f2e824
                  f2e824
                  	

                  If no break is intended, please add a comment instead. An example:

                  f2e824
                  f2e824
                  	

                  // Example with no break

                  f2e824
                  	
                  f2e824
                  switch ($mode)
                  f2e824
                  {
                  f2e824
                  	case 'mode1':
                  f2e824
                  f2e824
                  		// I am doing something here
                  f2e824
                  f2e824
                  	// no break here
                  f2e824
                  f2e824
                  	case 'mode2':
                  f2e824
                  f2e824
                  		// I am doing something completely different here
                  f2e824
                  f2e824
                  	break;
                  f2e824
                  f2e824
                  	default:
                  f2e824
                  f2e824
                  		// Always assume that a case was not caught
                  f2e824
                  f2e824
                  	break;
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  2.iii. SQL/SQL Layout

                  f2e824
                  f2e824
                  	

                  Common SQL Guidelines:

                  f2e824
                  	

                  All SQL should be cross-DB compatible, if DB specific SQL is used alternatives must be provided which work on all supported DB's (MySQL3/4/5, MSSQL (7.0 and 2000), PostgreSQL (7.0+), Firebird, SQLite, Oracle8, ODBC (generalised if possible)).

                  f2e824
                  	

                  All SQL commands should utilise the DataBase Abstraction Layer (DBAL)

                  f2e824
                  f2e824
                  	

                  SQL code layout:

                  f2e824
                  	

                  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:

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

                  Here the example with the tabs applied:

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

                  SQL Quotes:

                  f2e824
                  	

                  Double quotes where applicable (The variables in these examples are typecasted to integers before) ... examples:

                  f2e824
                  f2e824
                  	

                  // These are wrong.

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

                  // These are right.

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

                  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.

                  f2e824
                  f2e824
                  	

                  Avoid DB specific SQL:

                  f2e824
                  	

                  The "not equals operator", as defined by the SQL:2003 standard, is "<>"

                  f2e824
                  f2e824
                  	

                  // This is wrong.

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

                  // This is right.

                  f2e824
                  	
                  f2e824
                  $sql = 'SELECT *
                  f2e824
                  	FROM ' . SOME_TABLE . '
                  f2e824
                  	WHERE a <> 2';
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Common DBAL methods:

                  f2e824
                  f2e824
                  	

                  sql_escape():

                  f2e824
                  f2e824
                  	

                  Always use $db->sql_escape() if you need to check for a string within an SQL statement (even if you are sure the variable cannot contain single quotes - never trust your input), for example:

                  f2e824
                  f2e824
                  	
                  f2e824
                  $sql = 'SELECT *
                  f2e824
                  	FROM ' . SOME_TABLE . "
                  f2e824
                  	WHERE username = '" . $db->sql_escape($username) . "'";
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  sql_query_limit():

                  f2e824
                  f2e824
                  	

                  We do not add limit statements to the sql query, but instead use $db->sql_query_limit(). You basically pass the query, the total number of lines to retrieve and the offset.

                  f2e824
                  f2e824
                  	

                  Note: Since Oracle handles limits differently and because of how we implemented this handling you need to take special care if you use sql_query_limit with an sql query retrieving data from more than one table.

                  f2e824
                  f2e824
                  	

                  Make sure when using something like "SELECT x.*, y.jars" that there is not a column named jars in x; make sure that there is no overlap between an implicit column and the explicit columns.

                  f2e824
                  f2e824
                  	

                  sql_build_array():

                  f2e824
                  f2e824
                  	

                  If you need to UPDATE or INSERT data, make use of the $db->sql_build_array() function. This function already escapes strings and checks other types, so there is no need to do this here. The data to be inserted should go into an array - $sql_ary - or directly within the statement if one or two variables needs to be inserted/updated. An example of an insert statement would be:

                  f2e824
                  f2e824
                  	
                  f2e824
                  $sql_ary = array(
                  f2e824
                  	'somedata'		=> $my_string,
                  f2e824
                  	'otherdata'		=> $an_int,
                  f2e824
                  	'moredata'		=> $another_int
                  f2e824
                  );
                  f2e824
                  f2e824
                  $db->sql_query('INSERT INTO ' . SOME_TABLE . ' ' . $db->sql_build_array('INSERT', $sql_ary));
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  To complete the example, this is how an update statement would look like:

                  f2e824
                  f2e824
                  	
                  f2e824
                  $sql_ary = array(
                  f2e824
                  	'somedata'		=> $my_string,
                  f2e824
                  	'otherdata'		=> $an_int,
                  f2e824
                  	'moredata'		=> $another_int
                  f2e824
                  );
                  f2e824
                  f2e824
                  $sql = 'UPDATE ' . SOME_TABLE . '
                  f2e824
                  	SET ' . $db->sql_build_array('UPDATE', $sql_ary) . '
                  f2e824
                  	WHERE user_id = ' . (int) $user_id;
                  f2e824
                  $db->sql_query($sql);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

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

                  f2e824
                  f2e824
                  	

                  sql_multi_insert():

                  f2e824
                  f2e824
                  	

                  If you want to insert multiple statements at once, please use the separate sql_multi_insert() method. An example:

                  f2e824
                  f2e824
                  	
                  f2e824
                  $sql_ary = array();
                  f2e824
                  f2e824
                  $sql_ary[] = array(
                  f2e824
                  	'somedata'		=> $my_string_1,
                  f2e824
                  	'otherdata'		=> $an_int_1,
                  f2e824
                  	'moredata'		=> $another_int_1,
                  f2e824
                  );
                  f2e824
                  f2e824
                  $sql_ary[] = array(
                  f2e824
                  	'somedata'		=> $my_string_2,
                  f2e824
                  	'otherdata'		=> $an_int_2,
                  f2e824
                  	'moredata'		=> $another_int_2,
                  f2e824
                  );
                  f2e824
                  f2e824
                  $db->sql_multi_insert(SOME_TABLE, $sql_ary);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  sql_in_set():

                  f2e824
                  f2e824
                  	

                  The $db->sql_in_set() function should be used for building IN () and NOT IN () constructs. Since (specifically) MySQL tend to be faster if for one value to be compared the = and <> operator is used, we let the DBAL decide what to do. A typical example of doing a positive match against a number of values would be:

                  f2e824
                  f2e824
                  	
                  f2e824
                  $sql = 'SELECT *
                  f2e824
                  	FROM ' . FORUMS_TABLE . '
                  f2e824
                  	WHERE ' . $db->sql_in_set('forum_id', $forum_ids);
                  f2e824
                  $db->sql_query($sql);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Based on the number of values in $forum_ids, the query can look differently.

                  f2e824
                  f2e824
                  	

                  // SQL Statement if $forum_ids = array(1, 2, 3);

                  f2e824
                  f2e824
                  	
                  f2e824
                  SELECT FROM phpbb_forums WHERE forum_id IN (1, 2, 3)
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // SQL Statement if $forum_ids = array(1) or $forum_ids = 1

                  f2e824
                  f2e824
                  	
                  f2e824
                  SELECT FROM phpbb_forums WHERE forum_id = 1
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

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

                  f2e824
                  f2e824
                  	
                  f2e824
                  $sql = 'SELECT *
                  f2e824
                  	FROM ' . FORUMS_TABLE . '
                  f2e824
                  	WHERE ' . $db->sql_in_set('forum_id', $forum_ids, true);
                  f2e824
                  $db->sql_query($sql);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

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

                  f2e824
                  f2e824
                  	

                  // SQL Statement if $forum_ids = array(1, 2, 3);

                  f2e824
                  f2e824
                  	
                  f2e824
                  SELECT FROM phpbb_forums WHERE forum_id NOT IN (1, 2, 3)
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // SQL Statement if $forum_ids = array(1) or $forum_ids = 1

                  f2e824
                  f2e824
                  	
                  f2e824
                  SELECT FROM phpbb_forums WHERE forum_id <> 1
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  If the given array is empty, an error will be produced.

                  f2e824
                  f2e824
                  	

                  sql_build_query():

                  f2e824
                  f2e824
                  	

                  The $db->sql_build_query() function is responsible for building sql statements for select and select distinct queries if you need to JOIN on more than one table or retrieving data from more than one table while doing a JOIN. This needs to be used to make sure the resulting statement is working on all supported db's. Instead of explaining every possible combination, i will give a short example:

                  f2e824
                  f2e824
                  	
                  f2e824
                  $sql_array = array(
                  f2e824
                  	'SELECT'	=> 'f.*, ft.mark_time',
                  f2e824
                  f2e824
                  	'FROM'		=> array(
                  f2e824
                  		FORUMS_WATCH_TABLE	=> 'fw',
                  f2e824
                  		FORUMS_TABLE		=> 'f'
                  f2e824
                  	),
                  f2e824
                  f2e824
                  	'LEFT_JOIN'	=> array(
                  f2e824
                  		array(
                  f2e824
                  			'FROM'	=> array(FORUMS_TRACK_TABLE => 'ft'),
                  f2e824
                  			'ON'	=> 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id'
                  f2e824
                  		)
                  f2e824
                  	),
                  f2e824
                  f2e824
                  	'WHERE'		=> 'fw.user_id = ' . $user->data['user_id'] . '
                  f2e824
                  		AND f.forum_id = fw.forum_id',
                  f2e824
                  f2e824
                  	'ORDER_BY'	=> 'left_id'
                  f2e824
                  );
                  f2e824
                  f2e824
                  $sql = $db->sql_build_query('SELECT', $sql_array);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  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:

                  f2e824
                  f2e824
                  	
                  f2e824
                  $sql_array = array(
                  f2e824
                  	'SELECT'	=> 'f.*',
                  f2e824
                  f2e824
                  	'FROM'		=> array(
                  f2e824
                  		FORUMS_WATCH_TABLE	=> 'fw',
                  f2e824
                  		FORUMS_TABLE		=> 'f'
                  f2e824
                  	),
                  f2e824
                  f2e824
                  	'WHERE'		=> 'fw.user_id = ' . $user->data['user_id'] . '
                  f2e824
                  		AND f.forum_id = fw.forum_id',
                  f2e824
                  f2e824
                  	'ORDER_BY'	=> 'left_id'
                  f2e824
                  );
                  f2e824
                  f2e824
                  if ($config['load_db_lastread'])
                  f2e824
                  {
                  f2e824
                  	$sql_array['LEFT_JOIN'] = array(
                  f2e824
                  		array(
                  f2e824
                  			'FROM'	=> array(FORUMS_TRACK_TABLE => 'ft'),
                  f2e824
                  			'ON'	=> 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id'
                  f2e824
                  		)
                  f2e824
                  	);
                  f2e824
                  f2e824
                  	$sql_array['SELECT'] .= ', ft.mark_time ';
                  f2e824
                  }
                  f2e824
                  else
                  f2e824
                  {
                  f2e824
                  	// Here we read the cookie data
                  f2e824
                  }
                  f2e824
                  f2e824
                  $sql = $db->sql_build_query('SELECT', $sql_array);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  2.iv. Optimizations

                  f2e824
                  f2e824
                  	

                  Operations in loop definition:

                  f2e824
                  	

                  Always try to optimize your loops if operations are going on at the comparing part, since this part is executed every time the loop is parsed through. For assignments a descriptive name should be chosen. Example:

                  f2e824
                  f2e824
                  	

                  // On every iteration the sizeof function is called

                  f2e824
                  	
                  f2e824
                  for ($i = 0; $i < sizeof($post_data); $i++)
                  f2e824
                  {
                  f2e824
                  	do_something();
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // You are able to assign the (not changing) result within the loop itself

                  f2e824
                  	
                  f2e824
                  for ($i = 0, $size = sizeof($post_data); $i < $size; $i++)
                  f2e824
                  {
                  f2e824
                  	do_something();
                  f2e824
                  }
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Use of in_array():

                  f2e824
                  	

                  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 noticable, but if checked against a huge array within a loop those checks alone can be a bunch of 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 isset($array[$var]) is a lot faster than in_array($var, array_keys($array)) for example.

                  f2e824
                  f2e824
                  f2e824
                  	

                  2.v. General Guidelines

                  f2e824
                  f2e824
                  	

                  General things:

                  f2e824
                  	

                  Never trust user input (this also applies to server variables as well as cookies).

                  f2e824
                  	

                  Try to sanitize values returned from a function.

                  f2e824
                  	

                  Try to sanitize given function variables within your function.

                  f2e824
                  	

                  The auth class should be used for all authorisation checking.

                  f2e824
                  	

                  No attempt should be made to remove any copyright information (either contained within the source or displayed interactively when the source is run/compiled), neither should the copyright information be altered in any way (it may be added to).

                  f2e824
                  f2e824
                  	

                  Variables:

                  f2e824
                  	

                  Make use of the request_var() function for anything except for submit or single checking params.

                  f2e824
                  	

                  The request_var function determines the type to set from the second parameter (which determines the default value too). If you need to get a scalar variable type, you need to tell this the request_var function explicitly. Examples:

                  f2e824
                  f2e824
                  	

                  // Old method, do not use it

                  f2e824
                  	
                  f2e824
                  $start = (isset($HTTP_GET_VARS['start'])) ? intval($HTTP_GET_VARS['start']) : intval($HTTP_POST_VARS['start']);
                  f2e824
                  $submit = (isset($HTTP_POST_VARS['submit'])) ? true : false;
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // Use request var and define a default variable (use the correct type)

                  f2e824
                  	
                  f2e824
                  $start = request_var('start', 0);
                  f2e824
                  $submit = (isset($_POST['submit'])) ? true : false;
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // $start is an int, the following use of request_var therefore is not allowed

                  f2e824
                  	
                  f2e824
                  $start = request_var('start', '0');
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // Getting an array, keys are integers, value defaults to 0

                  f2e824
                  	
                  f2e824
                  $mark_array = request_var('mark', array(0));
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  // Getting an array, keys are strings, value defaults to 0

                  f2e824
                  	
                  f2e824
                  $action_ary = request_var('action', array('' => 0));
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Login checks/redirection:

                  f2e824
                  	

                  To show a forum login box use login_forum_box($forum_data), else use the login_box() function.

                  f2e824
                  f2e824
                  	

                  The login_box() function can have a redirect as the first parameter. As a thumb of rule, specify an empty string if you want to redirect to the users current location, else do not add the $SID to the redirect string (for example within the ucp/login we redirect to the board index because else the user would be redirected to the login screen).

                  f2e824
                  f2e824
                  	

                  Sensitive Operations:

                  f2e824
                  	

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

                  f2e824
                  f2e824
                  	

                  Altering Operations:

                  f2e824
                  	

                  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.

                  f2e824
                  	
                  f2e824
                  	add_form_key('my_form');
                  f2e824
                  f2e824
                  	if ($submit)
                  f2e824
                  	{
                  f2e824
                  		if (!check_form_key('my_form'))
                  f2e824
                  		{
                  f2e824
                  			trigger_error('FORM_INVALID');
                  f2e824
                  		}
                  f2e824
                  	}
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  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.

                  f2e824
                  f2e824
                  f2e824
                  	

                  Sessions:

                  f2e824
                  	

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

                  f2e824
                  f2e824
                  	
                  f2e824
                  $user->session_begin();
                  f2e824
                  $auth->acl($user->data);
                  f2e824
                  $user->setup();
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  The $user->setup() call can be used to pass on additional language definition and a custom style (used in viewforum).

                  f2e824
                  f2e824
                  	

                  Errors and messages:

                  f2e824
                  	

                  All messages/errors should be outputed by calling trigger_error() using the appropriate message type and language string. Example:

                  f2e824
                  f2e824
                  	
                  f2e824
                  trigger_error('NO_FORUM');
                  f2e824
                  	
                  f2e824
                  f2e824
                  	
                  f2e824
                  trigger_error($user->lang['NO_FORUM']);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	
                  f2e824
                  trigger_error('NO_MODE', E_USER_ERROR);
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  Url formatting

                  f2e824
                  f2e824
                  	

                  All urls pointing to internal files need to be prepended by the $phpbb_root_path variable. Within the administration control panel all urls pointing to internal files need to be prepended by the $phpbb_admin_path variable. This makes sure the path is always correct and users being able to just rename the admin folder and the acp still working as intended (though some links will fail and the code need to be slightly adjusted).

                  f2e824
                  f2e824
                  	

                  The append_sid() function from 2.0.x is available too, though 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:

                  f2e824
                  f2e824
                  	
                  f2e824
                  append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&amp;g=' . $row['group_id'])
                  f2e824
                  	
                  f2e824
                  f2e824
                  	

                  General function usage:

                  f2e824
                  f2e824
                  	

                  Some of these functions are only chosen over others because of personal preference and having no other benefit than to be consistant over the code.

                  f2e824
                  f2e824
                  	
                    f2e824
                    		
                  • f2e824
                    			

                    Use sizeof instead of count

                    f2e824
                    		
                    f2e824
                    		
                  • f2e824
                    			

                    Use strpos instead of strstr

                    f2e824
                    		
                    f2e824
                    		
                  • f2e824
                    			

                    Use else if instead of elseif

                    f2e824
                    		
                    f2e824
                    		
                  • f2e824
                    			

                    Use false (lowercase) instead of FALSE

                    f2e824
                    		
                    f2e824
                    		
                  • f2e824
                    			

                    Use true (lowercase) instead of TRUE

                    f2e824
                    		
                    f2e824
                    	
                    f2e824
                    f2e824
                    	

                    Exiting

                    f2e824
                    f2e824
                    	

                    Your page should either call page_footer() in the end to trigger output through the template engine and terminate the script, or alternatively at least call the exit_handler(). That call is necessary because it provides a method for external applications embedding phpBB to be called at the end of the script.

                    f2e824
                    f2e824
                    		
                    f2e824
                    f2e824
                    		
                    f2e824
                    f2e824
                    		
                    f2e824
                    	
                    f2e824
                    f2e824
                    	
                    f2e824
                    f2e824

                    3. Styling

                    f2e824
                    	
                    f2e824
                    		
                    f2e824
                    f2e824
                    		
                    f2e824
                    	

                    3.i. Style Config Files

                    f2e824
                    	

                    Style cfg files are simple name-value lists with the information necessary for installing a style. Similar cfg files exist for templates, themes and imagesets. These follow the same principle and will not be introduced individually. Styles can use installed components by using the required_theme/required_template/required_imageset entries. The important part of the style configuration file is assigning an unique name.

                    f2e824
                    	
                    f2e824
                            # General Information about this style
                    f2e824
                            name = prosilver_duplicate
                    f2e824
                            copyright = © phpBB Group, 2007
                    f2e824
                            version = 3.0.3
                    f2e824
                            required_template = prosilver
                    f2e824
                            required_theme = prosilver
                    f2e824
                            required_imageset = prosilver
                    f2e824
                    	
                    f2e824
                    	

                    3.2. General Styling Rules

                    f2e824

                    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 intendation and coding guidelines also apply to templates where possible.

                    f2e824
                    f2e824

                    The outer table class forumline has gone and is replaced with tablebg.

                    f2e824

                    When writing <table> the order <table class="" cellspacing="" cellpadding="" border="" align=""> creates consistency and allows everyone to easily see which table produces which "look". The same applies to most other tags for which additional parameters can be set, consistency is the major aim here.

                    f2e824

                    Each block level element should be indented by one tab, same for tabular elements, e.g. <tr> <td> etc., whereby the intendiation of <table> and the following/ending <tr> should be on the same line. This applies not to div elements of course.

                    f2e824

                    Don't use <span> more than is essential ... the CSS is such that text sizes are dependent on the parent class. So writing <span class="gensmall"><span class="gensmall">TEST</span></span> will result in very very small text. Similarly don't use span at all if another element can contain the class definition, e.g.

                    f2e824
                    f2e824
                    f2e824
                    <td><span class="gensmall">TEST</span></td>