Extension Validation Policy

The following policies should be followed when developing extensions for phpBB. This ensures consistent and quality code that is up to standards of phpBB. If you have any questions about any of the policies, feel free to discuss them in the Extension Writers Forum.


General

  1. Coding Guidelines

    The phpBB Coding Guidelines should be followed as much as possible. This means that all files should follow these guidelines, including PHP, JavaScript, and HTML files. This is to ensure maximum readability by the phpBB Extension Customisations Team. Third-party libraries are the only exceptions and do not have to follow the coding guidelines. It is also required to use the English language for all table names, variable names and comments. The primary language for phpBB and extensions is English.
  2. Modifying phpBB Files

    No files that belong to the core phpBB package shall be modified in any way. Although the basis for all modifications in 3.0 was built on modifying phpBB's core files, extensions in 3.1 are intended to be self-contained and void of actual code changes to phpBB's core files. As such, no extension may require code changes to phpBB's core files.
  3. Composer:

    A composer.json file is required. [docs].
  4. Vendor Prefixing

    All php events, services, routes and new template events in an extension should be prefixed with the extension's vendor name and package name, and contain only lowercase letters, numbers, dots, and underscores.
    1. PHP Events: vendor.extension.custom_event
    2. Services: vendor.extension.custom.service
    3. Routes: vendor_extension_custom_route
    4. Template Events: <!-- EVENT vendor_extension_custom_event -->
    Note: It is forbidden to use phpbb or core to prefix events, services and routes.
  5. Language and Styles

    Language files and/or style files should always provide files for the English language and prosilver style, respectively.
    • English language files should be stored in language/en.
    • Additional language files should be stored in the language directory with the correct language name (ISO), e.g., language/de.
    • prosilver specific style files should be stored in styles/prosilver. However, generic style files that can be universally used with all styles should be stored in styles/all.
    • Additional style files should be contained in their respective directories, e.g., styles/subsilver2.
  6. Privacy

    For privacy reasons it is not allowed to send private information (including but not limited to posts, user information, etc.) to any remote website or remote server. Any extension that does send information to a remote website or remote server will be denied for this reason. Exceptions to this rule, although rare, will be handled on a case-by-case basis.
  7. Other

    • Avoid using deprecated functions from phpBB 3.0. View changed functions in the wiki.
    • Tabs are used instead of spaces for indenting. A tab is defined as having a width of four spaces in this instance. This applies to PHP, JavaScript, JSON and CSS files. The only exception to this rule is Yaml files, which require 4-spaces for indentation.
    • Included third-party libraries should be up-to-date. They should be kept un-modified as much as possible. It is also preferred to use Composer to manage third-party libraries if possible.
    • Files uploaded via the extension (e.g., downloads in a download extension) should not be placed in the ext/vendor/name directory, but in (for example) phpBB's store/vendor_ext/ directory.
    • Extensions are intended for use on live production sites. Extensions built for developers or development environments will not be validated or added to the Extensions Database. Please notify an Extension Team member if you have a development extension you would like to see added to the Extension Writer Tools sticky in the Extension Writers forum.

PHP Files

  1. Only functions that exist before and in PHP 5.3.3 may be used by default. If you want to use functions that were added in a later version of PHP you need to mention this requirement within the description.
  2. PHP files are saved as UTF-8 Encoded with UNIX line endings (LF).
  3. PHP files do not contain a (Byte Order Mark) BOM.
  4. No un-initialised variables or indices.
  5. Proper file headers and php DocBlocks should be used.‬‬
  6. Braces { and } should be on newlines.
  7. Contain no ‪magic numbers‬‬. [docs]
  8. IN_PHPBB checks must be used in all included files, unless they contain only classes or interfaces. For example, function files and language files. [docs]
  9. The $request->variable() function is used instead of $_POST, $_GET, or $_REQUEST to get user input. [docs]
  10. Integer variables from $request->variable() are cast as integers using the form: $request->variable('var', 0) and not $request->variable ('var', '0').
  11. $_SERVER variables are properly sanitised (many $_SERVER indexes can be user manipulated). It is preferred to use $request->server() instead of $_SERVER, e.g.: $request->server('REMOTE_ADDR'), as these will be properly sanitised by the $request method.
  12. The $user object also contains several sanitised variables about the user, for example: $user->ip (user's REMOTE_ADDR) and $user->page (name of page currently viewed by user).
  13. phpBB3 DBAL is used instead of database specific SQL functions.
    • User-input string variables are properly sanitised using $db->sql_escape() when using variables in SQL queries. [wiki]
    • int and float variables are enforced by type-casting as (int) and (float) when inserting into SQL queries.
    • $db->sql_build_query() is used on large SQL queries (e.g.: if the query contains joins). [wiki]
    • $db->sql_build_array() is used on SQL INSERT and SQL UPDATE queries. [wiki]
    • $db->sql_multi_insert() is used when performing multiple SQL INSERT statements. [wiki]
    • $db->sql_in_set() is used for SQL IN() WHERE statements.‪ [wiki]
    • $db->sql_query_limit() is used instead of LIMIT in SQL queries. [wiki]
    • Static SQL queries should be cached.‪
    • SQL queries within loops should be avoided.
  14. helper->error() and/or trigger_error() are used for error handling and user messages instead of die() or similar. [wiki]
  15. login_forum_box() or login_box() is used for login. [wiki]
  16. confirm_box() is used for the user to confirm sensitive actions (such as deleting items). [wiki]
  17. URLs pointing to phpBB files call append_sid() to correctly append the session id. [wiki]
  18. ext_vendor/name is a required auth parameter for extensions that must be defined in ACP, MCP, UCP _info files. [docs]

Template Files

  1. No hard-coded PHP in template files.
  2. All prosilver HTML is valid HTML5 syntax.
  3. English language images are supplied as necessary.

Migrations

  1. Database and permission changes should be handled with migrations. All subsequent database changes should be made in new migration files.
  2. Old migration files should never be altered or deleted.
  3. Extensions should never delete phpBB core tables or columns.

JavaScript and CSS

  1. Include JavaScript files with the template function: <!-- INCLUDEJS -->. [docs]
  2. Include CSS files with the template function: <!-- INCLUDECSS -->. [docs]
  3. Included third-party JavaScript/CSS libraries and frameworks should utilise a special template <!-- DEFINE --> tag to prevent duplicate inclusion. For example:

    <!-- IF not $INCLUDED_HIGHSLIDEJS -->
        <!-- INCLUDEJS highslide-full.js -->
        <!-- DEFINE $INCLUDED_HIGHSLIDEJS = true -->
    <!-- ENDIF -->
    Some example template variable definitions to use with common libraries:
    1. HighSlide JS: $INCLUDED_HIGHSLIDEJS
    2. Font Awesome CSS: $INCLUDED_FONTAWESOMECSS
    3. ColorBox JS: $INCLUDED_COLORBOXJS
    4. ColPick JS: $INCLUDED_COLPICKJS
    5. MoTools JS: $INCLUDED_MOTOOLSJS
    6. Dojo JS: $INCLUDED_DOJOJS
    Note: The common practice should be to name the variable definition after the library filename, e.g.: highslide.js becomes HIGHSLIDEJS.

Licenses

  1. Extensions should be released under GPL v2. Included frameworks should use GPL v2 or a compatible license. See http://www.gnu.org/licenses/gpl-faq.html#AllCompatibility.
  2. A license.txt file should be included in the root directory of the extension.

Packaging and Version

  1. Extensions are packaged as follows:
    /vendorname/extensionname/
    The names should be alphanumeric. (No dashes or underscores. Capitals are allowed.) For example, the following common extension files, composer.json, ext.php and license.txt would be located at:
    /vendorname/extensionname/composer.json
    /vendorname/extensionname/ext.php
    /vendorname/extensionname/license.txt
    Download Extension QuickStart (zip) Extension QuickStart is an available package with starter composer.json and ext.php files and the required license.txt.
  2. Semantic version numbers should be used. Only stable versions are allowed in the Extension Database. For every update the version number should be increased.
  3. Extensions will be assumed to have the same PHP support as the current stable release of phpBB. For example, phpBB 3.1.10 supports PHP 5.3.3 and above, but not PHP 7. If an extension has different PHP support requirements then these reqirements must be stated in the Contribution Description in the Extension Database, and mentioned to the validators when submitting the extension. These requirements must also be properly defined in the composer.json file. [docs]

Insta-Deny Policy

Insta-Deny is meant to rapidly respond to basic problems in an extension submitted for validation. Extensions are checked by the Extension Pre Validator (EPV) for coding guideline violations.

In case a violation is detected, the validator (or junior validator) will look at the code violation reported by EPV within 72 hours after submission. The validator will decide if the reported violation is an allowable usage of code. All problems are looked at on a case-by-case basis as there can be valid uses of certain things EPV detects.

If a validator decides that the violation is in fact a problem, the extension will be Insta-Denied. The validator has the final decision. In cases where the validator is not sure, the final decision is made by the validation team leader. If an extension is not Insta-Denied within the first 72 hours after submission, it either means the extension passed the Insta-Deny requirements or the validators were too late in denying it.

Common causes for an Insta-Deny

There are certain conditions that are always reason for an Insta-Deny due to the problems they can cause later in the validation process.

  • PHP syntax errors. On submission, EPV will make sure there are no PHP syntax errors in the extension.
  • Incorrectly named vendor and package names (must be alphanumeric only and must begin with a letter).
  • Extension vendor name cannot be phpbb or core.
  • Invalid composer.json file syntax.
  • Missing a British English (en) language translation.
  • Missing a prosilver template for any extension style files (except when using the “all” template folder).
  • Not using the DBAL. It’s always required to use the DBAL class in your extension.
  • Not using migration files to perform database changes.
  • Extensions designed for use in development only environments. Extensions in the Customisation Database are intended for live production environments.
  • For all other problems EPV finds, it’s a case by case decision if it’s allowed or not.

Preventing an Insta-Deny

An Insta-Deny can be prevented by using EPV before you submit your extension. If there are any problems you will receive them in a report from EPV. In case you have any questions regarding this report please feel free to ask in the Extension Writers Forum. On extension submission, the EPV results will be shown and you should act, if appropriate, upon them.


Repack Policy

All extensions submitted to the Extensions Database can be repacked if the extension author gives approval for the Extension Customisations Team to repack their extension upon submission. A repack will be done when an Extension Customisations Team validator detects a basic problem within the extension that would prevent its approval. This will only be done when the issue is small. Whether an extension is repacked is determined case-by-case when this issue arises. The Extensions Customisation Team validation leader has the final word over this decision.

When we do repack

The Extension Customisation Team will only repack an extension if its author has given the Extension Customisation Team permission to do so. If the author has not given permission, the extension will be denied. The general rule of thumb used to decide whether to repack is: if it will take the Extension Customisation Team less time to repack the extension as opposed to re-validating it for only this issue, then it will be repacked.

The following are some example problems where a repack was allowed in the past:

  • An HTML error.
  • Packaging errors.
  • Using backticks in SQL queries.

When we do not repack

An extension will not be repacked in the following cases, even if it requires simple changes. The reason for this is mostly because the extension hasn't been thoroughly tested prior to submission.

  • The extension cannot be installed. If the installation failed the extension will be denied.
  • The extension contains a parse error or PHP notice.
  • The extension does not work as expected.