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:

See also

The phpBB Skeleton Extension is a tool to help developers rapidly generate the initial files and components needed to start developing new extensions for phpBB.

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".

See also

A complete explanation of all JSON schema fields available in a composer.json file can be found here: https://getcomposer.org/doc/04-schema.md

More information on specifying package version constraints can be found here: https://getcomposer.org/doc/articles/versions.md#basic-constraints

So far, our extension has no functionality yet. Continue on to the next sections to learn more about how to write an extension that will do something useful.