phpBB

Development Wiki

Difference between revisions of "Extension meta data"

From phpBB Development Wiki

m (Sample versions.json)
(moved to new docs)
 
Line 1: Line 1:
 
==Description==
 
==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.
+
This documentation has been moved to the new phpBB Development Documentation.
  
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
+
[https://area51.phpbb.com/docs/dev/31x/extensions/tutorial_basics.html#composer-json Extensions: Composer JSON].
  
==Parameters==
+
==Extension Version Check==
The following JSON schema are required in any extension's composer.json file, except where identified as optional:
+
This documentation has been moved to the new phpBB Development Documentation.
{|border="1" cellspacing="0" cellpadding="3"
+
! 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.
+
{|border="1" cellspacing="0" cellpadding="3"
+
! 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.
+
|}<br>
+
|-
+
| '''authors'''
+
| (Optional, but highly recommended) The author(s) of the extension, as an array of JSON objects.
+
{|border="1" cellspacing="0" cellpadding="3"
+
! 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.
+
|}<br>
+
|-
+
| '''extra'''
+
| Arbitrary extra data
+
{|border="1" cellspacing="0" cellpadding="3"
+
! Parameter
+
! Description
+
|-
+
| '''display-name'''
+
| The name of your extension.
+
|-
+
| '''soft-require'''
+
| The phpBB software required version
+
{|border="1" cellspacing="0" cellpadding="3"
+
! Parameter
+
! Description
+
|-
+
| '''phpbb/phpbb'''
+
| The minimum-stability version of phpBB required by the extension. For example: 3.1.* (for any stable released version of phpBB 3.1), 3.1.*@dev (for any dev, beta, RC or stable version of phpBB). More information can be found here: https://getcomposer.org/doc/01-basic-usage.md#package-versions
+
|}<br />
+
|-
+
| '''version-check''' (optional)
+
| The extension manager can check for the latest version of your extension using this feature.
+
{|border="1" cellspacing="0" cellpadding="3"
+
! Parameter
+
! Description
+
|-
+
|'''host'''
+
|Full URL to the host server,
+
|-
+
|'''directory'''
+
|/the directory containing the file,
+
|-
+
|'''filename'''
+
|A JSON file containing the latest version information
+
|}<br>
+
|-
+
|
+
|
+
|}<br>
+
|-
+
|
+
|
+
|}<br>
+
  
==Sample composer.json==
+
[https://area51.phpbb.com/docs/dev/31x/extensions/tutorial_advanced.html#extension-version-checking Extensions: Extension version checking].
It is important to remember that the last item or object in any JSON array must not contain a trailing comma.
+
<pre>
+
{
+
"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",
+
                "composer/installers": "~1.0"
+
},
+
"extra": {
+
"display-name": "Foo Bar by ACME",
+
"soft-require": {
+
"phpbb/phpbb": "3.1.*"
+
},
+
"version-check": {
+
"host": "acme.foobar.com",
+
"directory": "/version",
+
"filename": "foobar.json"
+
}
+
}
+
}
+
</pre>
+
 
+
==Extension Version Check==
+
This optional version data JSON file is hosted from your own server and is used by the Extension Manager's version check feature. The branches "stable" and "unstable" are optional, but at least one of them has to be defined. The Extension Manager has a setting that allows admins to check for 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 version of the extension is announced (typically a page such as the extension's page in phpBB's Extensions in Development forum, or your own web page where the user can find some explanations about this specific version). The "download" 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, GitHub repository, or your own web page). The "eol" and "security" fields are not used at the moment, and should be left as null and false, respectively.
+
<pre>
+
{
+
    "stable": {
+
        "1.0": {
+
            "current": "1.0.0",
+
            "announcement": "https://www.phpbb.com/community/viewtopic.php#",
+
            "download": "https://www.phpbb.com/download_id#",
+
            "eol": null,
+
            "security": false
+
        }
+
    },
+
    "unstable": {
+
        "1.0": {
+
            "current": "1.0.1",
+
            "announcement": "http://acme.foobar.com/version_1.0.1",
+
            "eol": null,
+
            "security": false
+
        },
+
        "1.1": {
+
            "current": "1.1.0-b4",
+
            "announcement": "http://acme.foobar.com/version_1.1.0",
+
            "eol": null,
+
            "security": false
+
        }
+
    }
+
}
+
</pre>
+

Latest revision as of 18:58, 5 December 2016

Description

This documentation has been moved to the new phpBB Development Documentation.

Extensions: Composer JSON.

Extension Version Check

This documentation has been moved to the new phpBB Development Documentation.

Extensions: Extension version checking.