Tutorial: Getting Started¶

Introduction¶

Welcome to phpBB’s extension development tutorial and documentation.

These tutorial pages are based on phpBB’s Acme Demo extension. This simple extension demonstrates many common features of an extension, including using a front-controller page, modifying phpBB through core events and template events, modifying the database using migrations, and setting up an ACP module for configuration settings.

This tutorial covers the basic creation of extensions:

Extension folder

Composer JSON

Extension Folder¶

All extensions must be located within the ext/ folder which can be found in phpBB’s root folder.

Extensions are packaged using a folder structure as follows: vendor/extname.

Thus, an extension should be located in the phpBB directory as follows: phpBB/ext/vendor/extname.

The vendor name can be the author’s username or any other name you choose to group your extensions by. The extension name is the name of the extension. In this tutorial we will use acme as the vendor name and demo as the extension name.

Important

Both the vendor and extension names must start with a lowercase letter, followed by lowercase letters and numbers only. Uppercase letters, underscores, dashes and other characters are not permitted. The following is an example of an allowed vendor and extension name: iamuser1/iamanextension.

Composer JSON¶

Every extension requires a meta data file named composer.json in order for phpBB to identify your extension. This file contains basic information about an extension as well its dependencies. It is written using the JSON format and must be stored in the root folder of the extension, e.g. phpBB/ext/acme/demo/composer.json.

The information in composer.json will be used by the Extensions Manager in the ACP. The details of the meta data are explained below the sample, but for now let’s have a look at the complete file:

{
    "name": "acme/demo",
    "type": "phpbb-extension",
    "description": "Acme Demo Extension for phpBB 3.2",
    "homepage": "https://github.com/phpbb/phpbb-ext-acme-demo",
    "version": "0.1.0",
    "time": "2013-11-05",
    "keywords": ["phpbb", "extension", "acme", "demo"],
    "license": "GPL-2.0-only",
    "authors": [
        {
            "name": "Nickv",
            "email": "nickvergessen@localhost",
            "homepage": "https://github.com/nickvergessen/",
            "role": "Lead Developer"
        }
    ],
    "require": {
        "php": ">=5.4.0",
        "composer/installers": "~1.0"
    },
    "require-dev": {
        "phpbb/epv": "dev-master"
    },
    "extra": {
        "display-name": "Acme Demo Extension",
        "soft-require": {
            "phpbb/phpbb": "~3.2"
        }
    }
}

Note

It is important to remember that the last item or object in any JSON array must not contain a trailing comma.

Field	Required	Content
`name`	Yes	The vendor name and extension name, separated by `/`, matching the folder structure.
`type`	Yes	The type of package. It should always be `phpbb-extension`.
`description`	Yes	A short description of your extension, may be empty (but not skipped).
`homepage`	No	A valid URL. It is recommended to use the link to the contribution in the customisation database, or to the repository of your extension (if you are using a public one like GitHub).
`version`	Yes	The version of your extension. This should follow the format of X.Y.Z with an optional suffix of -dev, -patch, -alpha, -beta or -RC.
`time`	No	The release date of your extension. Must be in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format.
`keywords`	No	An array of keywords related to the extension.
`license`	Yes	The license of the package. This can be either a string or an array of strings. Typically extensions should be licensed under the same GPL-2.0 license as phpBB.
`authors`	Yes	An array of authors of the extension. See authors for more details.
`require`	Yes	An array of requirements of the extension. See require for more details.
`require-dev`	No	An array of development requirements of the extension. See require-dev for more details.
`extra`	Yes	An array of arbitrary extra data. See extra for more details.

authors¶

You may have unlimited authors. At least one author is highly recommended.

Field	Required	Content
`name`	Yes	The name of an author.
`email`	No	An email address of the author.
`homepage`	No	A URL pointing to the website of the author.
`role`	No	Role can be used to specify what the author did for the extension (e.g. Developer, Translator, Supporter, etc.)

require¶

List the dependencies required by the extension, i.e. the PHP version and third party libraries.

Field	Content
`php`	The minimum-stability version of PHP required by the extension. phpBB 3.2 requires PHP 5.4.0 or higher, so the version comparison is `>= 5.4.0`.
`composer/installers`	Recommended by phpBB. This will install extensions to the correct location in phpBB when installed via Composer.

require-dev¶

In the optional require-dev section you can list the dependencies of the extension which are only required for development. Acme Demo uses the Extension Pre Validator Tool from the phpBB Extensions Team to perform some basic validation when running tests on Travis CI (see Tutorial: Testing). Since we always want to have the newest version, we require dev-master.

extra¶

This section can contain virtually any arbitrary data according to the composer specification. However, phpBB requires two special entries in this array for extensions:

Field	Content
`display-name`	The name of your extension, e.g. Acme Demo Extension.
`soft-require`	The minimum-stability version of phpBB required by the extension. In this case we require any 3.1 version, which is done by prefixing it with a `~`: `"phpbb/phpbb": "~3.2"`.