phpBB

Development Wiki

Extension meta data

From phpBB Development Wiki

Revision as of 01:32, 29 May 2014 by Vse (Talk | contribs)

Description

Every extension requires a metadata file named composer.json. 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 directory of the extension.

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

Parameters

The following JSON schema are required in any extension's composer.json file, except where identified as optional:

Parameter Usage
name The vendor name and extension name, separated by /
type The type of package. It should always be phpbb-extension
description A short description of your extension.
homepage (optional) A URL pointing to the website of the extension or extension author.
version 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 (optional) The release date of your extension. Must be in YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format.
keywords (optional) An array of keywords related to the extension.
license 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.
require Lists dependencies required by the extension.
Parameter Description
php The minimum-stability version of PHP required by the extension. phpBB requires PHP 5.3.3 or later and this should be the minimum PHP version requirement for any extension.
phpbb/phpbb The minimum-stability version of phpBB required by the extension. For example: 3.1.* (for any version of phpBB 3.1), 3.1.*@dev (for any dev, beta or RC version of phpBB). More information can be found here: https://getcomposer.org/doc/01-basic-usage.md#package-versions

authors (Optional, but highly recommended) The author(s) of the extension, as an array of JSON objects.
Parameter Description
name (optional) The name of an author.
homepage (optional) A URL pointing to the website of the author.
email (optional) An email address of the author.
role (optional) The role of the author, ie: Developer, Co-Developer, Consultant.

extra Arbitrary extra data
Parameter Description
display-name The name of your extension.
version-check (optional) The extension manager can check for the latest version of your extension using this feature.
Parameter Description
host Full URL to the host server,
directory /the directory containing the file,
filename A JSON file containing the latest version information



Sample composer.json

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

{
	"name": "acme/foobar",
	"type": "phpbb-extension",
	"description": "An extension which makes your forum even better.",
	"homepage": "http://acme.foobar.com",
	"version": "1.0.0",
	"time": "2013-09-30",
	"keywords": ["phpbb", "extension", "acme", "foobar"],
	"license": "GPL-2.0",
	"authors": [
		{
			"name": "John Smith",
			"homepage": "http://johnsmith.com",
			"email": "john@smith.tld",
			"role": "Developer"
		},
		{
			"name": "Jane Doe",
			"email": "jane@doe.tld",
			"role": "Co-Developer"
		}
	],
	"require": {
		"php": ">=5.3.3",
		"phpbb/phpbb": "3.1.*"
	},
	"extra": {
		"display-name": "Foo Bar by ACME",
		"version-check": {
			"host": "acme.foobar.com",
			"directory": "/version",
			"filename": "foobar.json"
		}
	}
}

Sample versions.json

This optional version data file is hosted from your own server and is used by the Extension Manager's version check feature. The "stable" branch is required, the "unstable" is optional. The Extension Manager has a setting that allows admins to look for or ignore unstable branches. For this reason, stable branches should only be used for stable release versions suitable for a live forum. The unstable branch can be used to provide links to versions in development. The "announcement" is a link to the page where the extension can be downloaded (typically an announcement page such as the extension's page in the Customisation Database, phpBB's Extensions in Development forum, GitHub repository, or your own web page).

{
    "stable": {
        "1.0": {
            "current": "1.0.0",
            "announcement": "https://www.phpbb.com/download_id#"
        }
    },
    "unstable": {
        "1.0": {
            "current": "1.0.1",
            "announcement": "http://acme.foobar.com/version_1.0.1"
        },
        "1.1": {
            "current": "1.1.0",
            "announcement": "http://acme.foobar.com/version_1.1.0"
        }
    }
}