<meta name="description" content="phpBB 3.1.x Changelog" />

<title>phpBB &bull; Changelog</title>

</head>

<a id="top" name="top" accesskey="t"></a>

<div id="page-header">

<div class="headerbar">

<div id="doc-description">

<h1>phpBB 3.1.x Changelog</h1>

<p style="display: none;"><a href="#start_here">Skip</a></p>

</div>

</div>

</div>

<!-- BEGIN DOCUMENT -->

<h1>Changelog</h1>

<div class="paragraph menu">

<div class="content">

<ol>

<li><a href="#changelog">Changelog</a>

<li><a href="#v311">Changes since 3.1.1</a></li>

<li><a href="#v310">Changes since 3.1.0</a></li>

<li><a href="#v310RC6">Changes since 3.1.0-RC6</a></li>

<li><a href="#v310a2">Changes since 3.1.0-a2</a></li>

<li><a href="#v310a1">Changes since 3.1.0-a1</a></li>

<li><a href="#v30x">Changes since 3.0.x</a></li>

<li><a href="#v3011">Changes since 3.0.11</a></li>

<li><a href="#v3010">Changes since 3.0.10</a></li>

<li><a href="#v309">Changes since 3.0.9</a></li>

<li><a href="#v30rc3">Changes since RC-3</a></li>

<li><a href="#v30rc2">Changes since RC-2</a></li>

<li><a href="#v30rc1">Changes since RC-1</a></li>

</li>

<li><a href="#disclaimer">Copyright and disclaimer</a></li>

</ol>

</div>

</div>

<hr />

<a name="changelog"></a><h2>1. Changelog</h2>

<div class="paragraph">

<div class="content">

<h4>Security</h4>

<ul>

</ul>

<h4>Security</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-13262">PHPBB3-13262</a>] - Add note to docs about htaccess file when upgrading 3.0 to 3.1</li>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-13215">PHPBB3-13215</a>] - Update Symfony Components to 2.3.21</li>

</ul>

<h4>Bug</h4>

<ul>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-13123">PHPBB3-13123</a>] - Add events to allow post blocking and post pre/past processing</li>

</ul>

<h4>Bug</h4>

<ul>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-12948">PHPBB3-12948</a>] - Remove Travis CI &quot;broken opcache on PHP 5.5.7 and 5.5.8&quot; workaround.</li>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-12829">PHPBB3-12829</a>] - Remove check for pgsql 8.3/8.2</li>

</ul>

<h4>Bug</h4>

<ul>

</ul>

<h4>Bug</h4>

<ul>

</ul>

<h4>Bug</h4>

<ul>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-12302">PHPBB3-12302</a>] - Upgrade composer.phar to 1.0.0-alpha8</li>

</ul>

<h4>Bug</h4>

<ul>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-12147">PHPBB3-12147</a>] - Remove Travis CI notification configuration</li>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-11998">PHPBB3-11998</a>] - Add console / command line client environment </li>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-11913">PHPBB3-11913</a>] - Apply reorganisation of download.phpbb.com to build_announcement.php</li>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-11753">PHPBB3-11753</a>] - Upgrade mysql_upgrader.php schema data.</li>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-10909">PHPBB3-10909</a>] - Update Travis Test Configuration: Travis no longer supports PHP 5.3.2</li>

</ul>

<h4>Bug</h4>

<ul>

<li>[<a href="http://tracker.phpbb.com/browse/PHPBB3-10480">PHPBB3-10480</a>] - Automate changelog building</li>

</ul>

<h4> Bug

</h4>

</li>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-9924'>PHPBB3-9924</a>] - $template-&gt;display hook does not pass $template instance

</li>

</li>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-9928'>PHPBB3-9928</a>] - Do not link &quot;login to your board&quot; to the &quot;send statistics&quot; page after completed update.

</li>

</li>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-9932'>PHPBB3-9932</a>] - The Bing bot is not added when converting.

</li>

</li>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-9934'>PHPBB3-9934</a>] - Mass Mail missing under the system tab on a fresh install

</li>

</li>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-9948'>PHPBB3-9948</a>] - Inline quicktime files won&#39;t display

</li>

</li>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-9950'>PHPBB3-9950</a>] - Problem with localized button images after uprading from 3.0.7-PL1 to 3.0.8

</li>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-10250'>PHPBB3-10250</a>] - phpBB Logo needs the Registered Trademark Symbol

</li>

</ul>

<h4> Improvement

</h4>

<ul>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-10186'>PHPBB3-10186</a>] - UCP signature panel displays when not authed for signatures

</li>

</ul>

<h4> New Feature

</h4>

<ul>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-10110'>PHPBB3-10110</a>] - Redis caching module

</li>

</ul>

<h4> Task

</h4>

<ul>

<li>[<a href='http://tracker.phpbb.com/browse/PHPBB3-10107'>PHPBB3-10107</a>] - Improve docs for non-apache webserver configuration

</li>

</ul>

<h4> Sub-task

</h4>

<ul>

</li>

</ul>

<h4> Security

</h4>

<ul>

</li>

</ul>

<ul>

<li>[Sec] Do not expose forum content of forums with ACL entries but no actual permission in ATOM Feeds. (Bug #58595)</li>

</ul>

<ul>

<li>[Fix] Allow ban reason and length to be selected and copied in ACP and subsilver2 MCP. (Bug #51095)</li>

</ul>

<ul>

<li>[Fix] Allow whitespaces in avatar gallery names. (Bug #44955)</li>

<li>[Feature] Send anonymous statistical information to phpBB on installation and update (optional).</li>

</ul>

<ul>

<li>[Fix] Delete user entry from ban list table upon user deletion (Bug #40015 - Patch by TerraFrost)</li>

<li>[Sec] Only use forum id supplied for posting if global announcement detected. (Reported by nickvergessen)</li>

</ul>

<ul>

<li>[Fix] Allow mixed-case template directories to be inherited (Bug #36725)</li>

<li>[Sec] Ask for forum password if post within passworded forum quoted in private message. (Reported by nickvergessen)</li>

</ul>

<ul>

<li>[Fix] Correctly set topic starter if first post in topic removed (Bug #30575 - Patch by blueray2048)</li>

<li>[Sec Precaution] Stricter validation of the HTTP_HOST header (Thanks to Techie-Micheal et al for pointing out possible issues in derived code)</li>

</ul>

<ul>

<li>[Fix] Ability to set permissions on non-mysql dbms (Bug #24955)</li>

<li>[Sec] Only allow urls gone through redirect() being used within login_box(). (thanks nookieman)</li>

</ul>

<ul>

<li>[Change] Validate birthdays (Bug #15004)</li>

<li>[Fix] Find and display colliding usernames correctly when converting from one database to another (Bug #23925)</li>

</ul>

<ul>

<li>[Fix] Cleaned usernames contain only single spaces, so &quot;a_name&quot; and &quot;a__name&quot; are treated as the same name (Bug #15634)</li>

<li>[Fix] Call garbage_collection() within database updater to correctly close connections (affects Oracle for example)</li>

</ul>

<ul>

<li>[Fix] Fixed MSSQL related bug in the update system</li>

<li>[Fix] No duplication of active topics (Bug #15474)</li>

</ul>

<ul>

<li>[Fix] Submitting language changes using acp_language (Bug #14736)</li>

<li>[Fix] Able to request new password (Bug #14743)</li>

</ul>

<ul>

<li>[Feature] Removing constant PHPBB_EMBEDDED in favor of using an exit_handler(); the constant was meant to achive this more or less.</li>

<li>[Sec] New password hashing mechanism for storing passwords (#i42)</li>

</ul>

<ul>

<li>[Fix] MySQL, PostgreSQL and SQLite related database fixes (Bug #13862)</li>

<li>[Fix] odbc_autocommit causing existing result sets to be dropped (Bug #14182)</li>

</ul>

<ul>

<li>[Fix] Fixing some subsilver2 and prosilver style issues</li>

</ul>

<ul>

<li>[Fix] Re-allow searching within the memberlist</li>

</ul>

<ul>

<li>[Fix] (X)HTML issues within the templates (Bug #11255, #11255)</li>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="disclaimer"></a><h2>2. Copyright and disclaimer</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<!-- END DOCUMENT -->

phpBB Developers: bantu (Andreas Fischer)

dhruv.goel92 (Dhruv Goel)

marc1706 (Marc Alexander)

nickvergessen (Joas Schilling)

prototech (Cesar Gallegos)

For a list of phpBB Team members, please see:

<meta name="description" content="phpBB 3.1.x frequently asked questions" />

<title>phpBB &bull; FAQ</title>

</head>

<a id="top" name="top" accesskey="t"></a>

<div id="page-header">

<div class="headerbar">

<div id="doc-description">

<h1>phpBB 3.1.x FAQ</h1>

<p>phpBB 3.1.x frequently asked questions</p>

<p style="display: none;"><a href="#start_here">Skip</a></p>

</div>

</div>

</div>

<!-- BEGIN DOCUMENT -->

<h1>FAQ</h1>

<div class="paragraph menu">

<div class="content">

</div>

</div>

<hr />

<a name="install"></a><h2>I am finding phpBB too difficult to install. Will you do it for me?</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

I want to sue you because i think you host an illegal board!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="viewonline"></a><h2>According to viewonline a user is doing/reading something they should not be able to!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="mail"></a><h2>I keep getting Mail sending errors when I (or my users) post/send PM's/etc.!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="mail_language"></a><h2>My users are complaining that emails are not in their selected language!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="aol_browser"></a><h2>My AOL based users keep getting logged out!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="avatars"></a><h2>I am unable to upload avatars from my computer, regardless of the settings.</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="gallery_avatars"></a><h2>I just cannot get gallery avatars to appear!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="permissions"></a><h2>How do I use/set permissions?</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="login_issues"></a><h2>I (or my users) cannot stay logged in to the forum!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="logout_issues"></a><h2>My users are complaining about being logged out too quickly!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="not_answered"></a><h2>My question isn't answered here!</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="disclaimer"></a><h2>Copyright and disclaimer</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<!-- END DOCUMENT -->

<meta name="description" content="phpBB 3.1.x Installation, updating and conversion informations" />

<title>phpBB &bull; Install</title>

</head>

<a id="top" name="top" accesskey="t"></a>

<div id="page-header">

<div class="headerbar">

<div id="doc-description">

<h1>phpBB 3.1.x Install</h1>

<p>phpBB 3.1.x Installation, updating and conversion informations</p>

<p style="display: none;"><a href="#start_here">Skip</a></p>

</div>

</div>

</div>

<!-- BEGIN DOCUMENT -->

<h1>Install</h1>

<div class="paragraph menu">

<div class="content">

</div>

</div>

<hr />

<a name="quickinstall"></a><h2>1. Quick install</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="require"></a><h2>2. Requirements</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="install"></a><h2>3. New installation</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="update"></a><h2>4. Updating from stable releases of phpBB 3.1.x</h2>

<div class="paragraph">

<div class="content">

<p>This update method is the recommended method for updating. This package detects changed files automatically and merges in changes if needed.</p>

<p>To perform the update, either follow the instructions from the <strong>Administration Control Panel-&gt;System</strong> Tab - this should point out that you are running an outdated version and will guide you through the update - or follow the instructions listed below.</p>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="convert"></a><h2>6. Conversion from phpBB 2.0.x to phpBB 3.1.x</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="postinstall"></a><h2>7. Important (security related) post-Install tasks for all installation methods</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="anti_spam"></a><h2>8. Anti-Spam Measures</h2>

<div class="paragraph">

<div class="content">

<p>Like any online site that allows user input, your board could be subject to unwanted posts; often referred to as <a href="http://en.wikipedia.org/wiki/Forum_spam">forum spam</a>. The vast majority of these attacks will be from automated computer programs known as <a href="http://en.wikipedia.org/wiki/Spambot">spambots</a>. The attacks, generally, are not personal as the spammers are just trying to find accessible targets. phpBB has a number of anti-spam measures built in, including a range of CAPTCHAs. However, administrators are strongly urged to read and follow the advice for <a href="https://www.phpbb.com/support/spam/">Preventing Spam in phpBB</a> as soon as possible after completing the installation of your board.</p>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="disclaimer"></a><h2>9. Copyright and disclaimer</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<!-- END DOCUMENT -->

<meta name="description" content="phpBB 3.1.x Readme" />

<title>phpBB &bull; Readme</title>

</head>

<a id="top" name="top" accesskey="t"></a>

<div id="page-header">

<div class="headerbar">

<div id="doc-description">

<h1>phpBB 3.1.x Readme</h1>

<p style="display: none;"><a href="#start_here">Skip</a></p>

</div>

</div>

</div>

<!-- BEGIN DOCUMENT -->

<h1>Readme</h1>

<div class="paragraph menu">

<div class="content">

</div>

</div>

<hr />

<a name="install"></a><h2>1. Installing phpBB</h2>

<div class="paragraph">

<div class="content">

<p>Installation, update and conversion instructions can be found in the <a href="INSTALL.html">INSTALL</a> document in this directory. If you are intending on converting from a phpBB 2.0.x or 3.0.x installation we highly recommend that you backup any existing data before proceeding!</p>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="run"></a><h2>2. Running phpBB</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="help"></a><h2>3. Getting help with phpBB</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="status"></a><h2>4. Status of this version</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="bugs"></a><h2>5. Reporting Bugs</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="curbugs"></a><h2>6. Overview of current bug list</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="php"></a><h2>7. PHP compatibility issues</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="disclaimer"></a><h2>8. Copyright and disclaimer</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<!-- END DOCUMENT -->

font-family: Verdana, Helvetica, Arial, sans-serif;

color: #828282;

background-color: #FFFFFF;

margin: 0;

padding: 12px 0;

}

img { border-width: 0; }

p {

line-height: 1.3em;

font-size: 1.1em;

border-bottom: 1px solid #CCCCCC;

margin-bottom: 3px;

padding-bottom: 2px;

color: #115098;

margin-top: 20px;

}

font-weight: bold;

margin-bottom: 3px;

padding-bottom: 2px;

color: #115098;

margin-top: 20px;

}

border-width: 1px;

border-style: solid;

background-color: #FAFAFA;

}

#wrap {

.headerbar {

background: #ebebeb none repeat-x 0 0;

color: #FFFFFF;

margin-bottom: 4px;

}

.paragraph {

margin-bottom: 4px;

background-repeat: no-repeat;

background-position: 100% 0;

color: #000000;

}

.content {

color: #333333;

}

.headerbar {

background-color: #12A3EB;

color: #FFFFFF;

}

color: #28313F;

}

.error {

color: #BC2A4D;

}

a:hover { color: #D31141; }

a:active { color: #368AD2; }

.content {

padding: 0;

line-height: 1.48em;

}

* html hr { margin: 0; }

height: 11px;

}

.content ol, .content ul {

clear: both;

margin-right: 1em;

}

<meta name="description" content="This is an explanation of how to use the phpBB auth/acl API" />

<title>phpBB3 &bull; Auth API</title>

</head>

<a id="top" name="top" accesskey="t"></a>

<div id="page-header">

<div class="headerbar">

<div id="doc-description">

<h1>Auth API</h1>

<p>This is an explanation of how to use the phpBB auth/acl API</p>

<p style="display: none;"><a href="#start_here">Skip</a></p>

</div>

</div>

</div>

<!-- BEGIN DOCUMENT -->

<h1>Auth API</h1>

<div class="paragraph menu">

<div class="content">

</div>

</div>

<hr />

<a name="intro"></a><h2>1. Introduction</h2>

<div class="paragraph">

<div class="content">

<p>To use any methods contained with the <code>auth</code> class it first needs to be instantiated. This is best achieved early in the execution of the script in the following manner:</p>

<div class="codebox"><pre>

<p>Once an instance of the class has been created you are free to call the various methods it contains. Please note that should you wish to use the <code>auth_admin</code> methods you will need to instantiate this separately but in the same way.</p>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="methods"></a><h2>2. Methods</h2>

<div class="paragraph">

<div class="content">

<p>The <code>acl</code> method is the initialisation routine for all the acl functions. If you intend calling any acl method you must first call this. The method takes as its one and only required parameter an associative array containing user information as stored in the database. This array must contain at least the following information; user_id, user_permissions and user_type. It is called in the following way:</p>

<div class="codebox"><pre>

<p>Where userdata is the array containing the aforementioned data.</p>

<p>This method is the primary way of determining what a user can and cannot do for a given option globally or in a given forum. The method should be called in the following way:</p>

<div class="codebox"><pre>

<p>Where option is a string representing the required option, e.g. 'f_list', 'm_edit', 'a_adduser', etc. By adding a ! in front of the option, e.g. '!f_list' the result of this method will be negated. The optional forum term is the integer forum_id.</p>

<p>The method should be called thus:</p>

<div class="codebox"><pre>

<p>As with the <code>acl_get</code> method the options are strings representing the required permissions to check. The forum again is an integer representing a given forum_id.</p>

<p>This method is used to find out in which forums a user is allowed to carry out an operation or to find out in which forums he is not allowed to carry out an operation. The method should be called in the following way:</p>

<div class="codebox"><pre>

<p>Just like in the <code>acl_get</code> method the option is a string specifying the permission which has to be checked (negation using ! is allowed). The second parameter is a boolean. If it is set to false this method returns all forums with either zero or a positive integer. If it is set to true only those forums with a positive integer as the result will be returned.</p>

<p>The method returns an associative array of the form:</p>

<div class="codebox"><pre>

<p>Where option is the option passed to the method and integer is either zero or a positive integer and the same <code>acl_get(option, forum_id)</code> would return.</p>

<p>This method is used to find out whether a user has a permission in at least one forum or globally. This method is similar to checking whether <code>acl_getf(option, true)</code> returned one or more forums but it's faster. It should be called in the following way:</p>

<div class="codebox"><pre>

<p>As with the previous methods option is a string specifying the permission which has to be checked.</p>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="admin_related"></a><h2>3. Admin related functions</h2>

<div class="paragraph">

<div class="content">

<p>To use any methods this class contains it first needs to be instantiated separately from <code>auth</code>. This is achieved in the same way as <code>auth</code>:</p>

<div class="codebox"><pre>

<p>This instance gives you access to both the methods of this specific class and that of <code>auth</code>.</p>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="disclaimer"></a><h2>4. Copyright and disclaimer</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<!-- END DOCUMENT -->

<meta name="description" content="Ascraeus coding guidelines document" />

<title>phpBB3 &bull; Coding Guidelines</title>

</head>

<a id="top" name="top" accesskey="t"></a>

<div id="page-header">

<div class="headerbar">

<div id="doc-description">

<h1>Coding Guidelines</h1>

<p>Ascraeus coding guidelines document</p>

<p style="display: none;"><a href="#start_here">Skip</a></p>

</div>

</div>

</div>

<!-- BEGIN DOCUMENT -->

<h1>Coding Guidelines</h1>

<div class="paragraph menu">

<div class="content">

</div>

</div>

<hr />

<a name="defaults"></a><h2>1. Defaults</h2>

<div class="paragraph">

<div class="content">

<div class="codebox"><pre>

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

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

* For full copyright and license information, please see

* the docs/CREDITS.txt file.

*

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

/**

*/

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

/**

* {DOCUMENTATION}

*/

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

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="code"></a><h2>2. Code Layout/Guidelines</h2>

<div class="paragraph">

<div class="content">

{

foo($i, $j);

}

<h4>Function Names:</h4>

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

dir/

class_name.php

subdir/

<div class="codebox"><pre>

\phpbb\class_name - phpbb/class_name.php

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

<h4>Summary:</h4>

do_stuff();

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

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

<div class="codebox"><pre>

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

{

do_stuff();

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

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

function do_stuff()

{

...

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

function do_stuff() {

...

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

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

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

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

<h4>Operator precedence:</h4>

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

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

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

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

<h4>Quoting strings:</h4>

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

<div class="codebox"><pre>

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

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

<div class="codebox"><pre>

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

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

<div class="codebox"><pre>

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

<div class="codebox"><pre>

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

$foo = array(

'bar' => 42,

'boo' => 23

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

<div class="codebox"><pre>

$foo = array(

'bar' => 42,

'boo' => 23,

<h4>Associative array keys:</h4>

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

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

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

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

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

<h4>Comments:</h4>

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

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

<div class="codebox"><pre>

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

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

<div class="codebox"><pre>

$array[$i] = $j;

$array[$i] = $k;

<h4>Inline conditionals:</h4>

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

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

<div class="codebox"><pre>

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

<div class="codebox"><pre>

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

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

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

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

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

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

case 'mode2':

// I am doing something completely different here

break;

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

<div class="codebox"><pre>

default:

// Always assume that a case was not caught

break;

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

<div class="codebox"><pre>

// Always assume that a case was not caught

break;

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

// Always assume that a case was not caught

break;

<h4>Class Members</h4>

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

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

<div class="codebox"><pre>

var $x;

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

<div class="codebox"><pre>

public $x;

<h4>Constants</h4>

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

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

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

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

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

WHERE a = 1

AND (b = 2

OR b = 3)

<h4>SQL Quotes: </h4>

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

<div class="codebox"><pre>

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

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

<div class="codebox"><pre>

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

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

<div class="codebox"><pre>

$sql = 'SELECT *

FROM ' . SOME_TABLE . '

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

<div class="codebox"><pre>

$sql = 'SELECT *

FROM ' . SOME_TABLE . '

<h4>Common DBAL methods: </h4>

<div class="codebox"><pre>

$sql = 'SELECT *

FROM ' . SOME_TABLE . "

<h4>sql_query_limit():</h4>

'moredata' =&gt; $another_int,

);

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

$sql = 'UPDATE ' . SOME_TABLE . '

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

WHERE user_id = ' . (int) $user_id;

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

'moredata' =&gt; $another_int_2,

);

<h4>sql_in_set():</h4>

$sql = 'SELECT *

FROM ' . FORUMS_TABLE . '

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

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

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

<div class="codebox"><pre>

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

<div class="codebox"><pre>

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

$sql = 'SELECT *

FROM ' . FORUMS_TABLE . '

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

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

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

<div class="codebox"><pre>

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

<div class="codebox"><pre>

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

'ORDER_BY' =&gt; 'left_id',

);

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

// Here we read the cookie data

}

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

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

{

do_something();

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

<div class="codebox"><pre>

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

{

do_something();

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

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

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

<div class="codebox"><pre>

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

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

<div class="codebox"><pre>

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

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

<div class="codebox"><pre>

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

<div class="codebox"><pre>

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

<div class="codebox"><pre>

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

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

{

trigger_error('FORM_INVALID');

}

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

<div class="codebox"><pre>

$user-&gt;session_begin();

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

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

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

<div class="codebox"><pre>

<div class="codebox"><pre>

<div class="codebox"><pre>

<h4>Url formatting</h4>

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

<div class="codebox"><pre>

<h4>General function usage: </h4>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="styling"></a><h2>3. Styling</h2>

<div class="paragraph">

<div class="content">

<a name="cfgfiles"></a><h3>3.i. Style Config Files</h3>

# Parent style

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

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

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

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="templating"></a><h2>4. Templating</h2>

<div class="paragraph">

<div class="content">

<a name="templates"></a><h3>4.i. General Templating</h3>

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="charsets"></a><h2>5. Character Sets and Encodings</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="translation"></a><h2>6. Translation (<abbr title="Internationalisation">i18n</abbr>/<abbr title="Localisation">L10n</abbr>) Guidelines</h2>

<div class="paragraph">

<div class="content">

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

/* Just grabbing the replacements as they

come and hope they are in the right order */

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

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

/* Explicit ordering of the replacements,

even if they are the same order as English */

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

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

/* Explicit ordering of the replacements,

reversed compared to English as the total comes first */

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

<div class="codebox"><pre>

...

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

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

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

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

),

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

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

3 => ...

),

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

<div class="codebox"><pre>

...

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

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

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

...

'CONV_ERROR_NO_AVATAR_PATH'

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

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

...

'CONV_ERROR_NO_AVATAR_PATH'

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

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

<div class="codebox"><pre>

...

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

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

<div class="codebox"><pre>

...

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

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

<div class="codebox"><pre>

...

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

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

...

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

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

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

...

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

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

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

...

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

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

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

<div class="codebox"><pre>

...

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

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

<div class="codebox"><pre>

...

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

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

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<hr />

<a name="disclaimer"></a><h2>7. Copyright and disclaimer</h2>

<div class="paragraph">

<div class="content">

<div class="back2top"><a href="#wrap" class="top">Back to Top</a></div>

</div>

<!-- END DOCUMENT -->

* Purpose: Add content after the last header-column (but before the action column)

in the ranks list in the ACP

acp_simple_footer_after

===

* Location: adm/style/simple_footer.html

* Since: 3.1.0-a1

* Purpose: Add asset calls directly before the `</head>` tag

overall_header_navigation_append

===

* Locations:

* Since: 3.1.0-b3

* Purpose: Add content after the page-header, but before the page-body

overall_header_stylesheets_after

===

* Locations:

* Since: 3.1.0-a4

* Purpose: Add content before the quick reply textbox

search_results_post_after

===

* Locations:

* Since: 3.1.0-b3

* Purpose: Add content directly before the post author in search results (posts view mode)

search_results_topic_after

===

* Locations:

* Purpose: Add options to the bottom of the drop-down lists block of the Edit

Display Options screen

ucp_register_credentials_before

===

* Locations:

* Since: 3.1.0-a1

* Purpose: Add asset calls directly before the `</head>` tag of the Print Topic screen

viewtopic_body_avatar_after

===

* Locations:

* Since: 3.1.0-RC4

* Purpose: Add data at the end of the posts.

viewtopic_body_postrow_post_notices_after

===

* Locations: