phpBB Skeleton Extension¶
The Skeleton Extension is a tool for extension developers. Its purpose is to kick start your extension development projects.
What is a skeleton? It’s a working boiler-plate extension. When you want to begin development on an extension, creating a skeleton will generate most of the initial files you would need, so you don’t have to.
This means you can jump straight into writing code for your extension, and bypass the mundane task of creating the initial files, methods and docblocks yourself.
If you’ve never written an extension before, a skeleton provides an ideal way to get started with your first one. Experienced developers will love it too, no longer having to copy-paste code from their existing extensions in order to start up new ones.
All code generated by the Skeleton Extension is fully documented and represents the phpBB Extension Team’s best practices for extension coding.
Be sure to reference and familiarise yourself with phpBB’s extension validation policies and coding guidelines.
How to install¶
phpBB’s Skeleton Extension is just like any other extension and is installed into a phpBB board just the same as any other.
Note
The Skeleton Extension is intended to be installed in a phpBB board used for offline/local development of extensions. It is not necessarily intended to be installed on live/production web sites.
Requirements¶
A phpBB board, version 3.2.3 or newer.
PHP version 5.6 or newer.
PHP ZipArchive module enabled.
Installation¶
Unzip and install it to your phpBB
ext/folder, e.g.phpBB/ext/phpbb/skeletonIn phpBB, go to “ACP” > “Customise” > “Extensions” and enable “phpBB Skeleton Extension”.
Create an extension¶
Important
The Skeleton Extension generates working classes and methods which are intended to make the skeleton nominally functional and, more importantly, instructional.
This documentation will assume we are creating the Acme Demo
extension, with the vendor/package naming structure: acme/demo.
Most file, function, class, table and variable names will be
populated with the vendor and package names specified.
The skeleton generated is only a starting point! You should always review the skeleton code you generate and update, edit or remove any of the code you do not need as you begin to develop your extension.
phpBB Web interface¶
The easiest way to use the Skeleton Extension is from its web-based user interface (UI).
In order to create an extension via the web UI, open the phpBB board you installed this extension in and visit the “Create skeleton extension” link in the board’s navigation bar.
You will be presented with a form where you can enter information about the extension you want to create. Complete the form and submit it.
A packaged ZIP file will begin to download in your browser.
Additionally, a copy of it can be found in phpBB/store/tmp-ext/.
Unzip your skeleton extension and begin writing your own code.
Command line interface¶
The Skeleton Extension can also accommodate users that prefer working from a Command Line Interface (CLI).
In order to create an extension via the CLI, you need to open a console
on your server and cd to the root directory of the phpBB board where
you installed this extension:
$ cd ./path/to/phpBB
To create an extension, run:
$ ./bin/phpbbcli.php extension:create
You will be prompted to enter information about the extension you want to create.
Your extension will be saved to phpBB/store/tmp-ext/.
Documentation¶
The following documentation describes how to use the Skeleton Extension to configure and generate a skeleton that will suit your needs, so you can jump straight into writing your own code.
Extension packaging¶
Extensions are packaged in a directory structure as follows: vendorname/extensionname.
For example, the Acme Demo extension uses a packaging structure that looks like acme/demo.
Vendor name¶
The vendor name can be your username or any other name you choose to associate
your extensions with. Valid naming conventions must start with a letter and
contain letters and numbers only. In the case of the Acme Demo extension,
this would be acme. This field is required.
Package name¶
The package name is the name of the extension. Valid naming conventions must
start with a letter and contain letters and numbers only. In the case of the
Acme Demo extension, this would be demo. This field is required.
Display name¶
This is the name (or title) of your extension in plain English. This is what the user will
see when your extension appears in the phpBB ACP Extension Manager. In the case of the
Acme Demo extension, this would be Acme Demo. This field is required.
Description¶
A brief description of your extension. This will be visible to users in the Details page of your extension in phpBB’s ACP Extension Manager.
Version¶
The version of your extension. phpBB’s coding guidelines require an x.y.z semantic
versioning format, with optional -dev, -alpha, -beta and -RC pre-release suffixes.
When left blank, the Skeleton Extension will use 1.0.0-dev by default.
Date of the extension¶
Date the extension is released. Dates must be in the YYYY-MM-DD format.
When left blank, the Skeleton Extension will use the current date by default.
Homepage of the extension¶
An optional link to your extension’s homepage. This can be, for example, an extension’s GitHub repository or any other site related to your extension.
Authors¶
Here you can name your extension’s author(s). Use the Add author button
to add additional authors.
Author name¶
The name of an extension’s author. Must not be empty.
Author email¶
The email address of an extension’s author. (Optional)
Author homepage¶
The homepage URL of an extension’s author. (Optional)
Author role¶
The role of an extension’s author. For example, lead developer, contributor, translator, etc. (Optional)
Requirements¶
Requirements are where you define the minimum (and maximum) PHP and phpBB versions your extension needs to be able to perform.
Minimum phpBB requirement of the extension¶
Typically this should be set to the version of phpBB in which you are developing and testing your extension.
The version should be defined using Composer’s version constraints.
For example, to require phpBB 3.1.4 or greater, use >=3.1.4.
Maximum phpBB requirement of the extension¶
To mitigate compatibility breaks, it is common to set the maximum version to the next major release version of phpBB.
For example, if your extension is being developed for phpBB 3.1.x, you can
set the maximum requirement to phpBB 3.2.x by using <3.2.0@dev.
Note
Currently, phpBB does not automatically enforce the minimum and maximum
requirements. However, it will begin enforcing it in a future release.
In the meantime, it is possible to use the is_enableable() method
in the ext.php class to enforce the minimum and maximum requirements.
PHP requirement of the extension¶
Since your extension will operate within phpBB, it’s often safe to assume
that your extension will share the same minimum PHP requirement as phpBB
does. Thus, by default, this field will use >=5.3.3 unless you enter
an alternative version.
Note
You can find phpBB’s PHP requirements by looking at its composer.json file.
Components¶
The default Skeleton Extension outputs a license file and composer.json. The Components section allows you to choose from a variety of typical components an extension could need, such as an ACP module, migrations, events, and tasks such as cron, CLI and notifications. The files generated for these components are simple yet fully working examples based off the Acme Demo extension. They are intended to give you a consistent and phpBB code-ready starting point, so you can focus more on writing your code and less on file structure and organisation.
PHP event listeners¶
PHP event listeners work with core events to inject code into phpBB. Core events are like hooks, and they can be found throughout phpBB’s codebase at key points. They give your extension access to phpBB’s variables and allow you to use and modify them or to inject additional PHP code during phpBB’s execution.
The Skeleton Extension will generate a sample event listener PHP file and necessary services YAML file:
vendor
├── package
│ ├── config # The config dir contains all service config files
│ │ ├── services.yml # A config YAML file
│ │ └── ...
│ ├── event # The event dir contains all PHP event listeners
│ │ ├── main_listener.php # A sample PHP event listener
│ │ └── ...
│ └── ...
└── ...
Style event listeners¶
Style listeners use template events to inject HTML, JS and CSS into
phpBB’s style files. Style listeners must be located in a directory
named event to be recognised as a template event. All files outside
the event dir are seen as standard style files.
all/ Directory contains style files that can be used by any/all
styles.
prosilver/ Directory contains style files specifically for prosilver
(and any styles that inherit from prosilver).
subsilver2/ Directory contains style files specifically for
subsilver2 (and any styles that inherit from subsilver2).
The Skeleton Extension will generate a sample template event listener HTML file for prosilver:
vendor
├── package
│ ├── styles # The styles dir
│ │ ├── prosilver # Dir containing prosilver style files
│ │ │ ├── template # Dir containing HTML template files
│ │ │ │ ├── event # Dir containing template event files
│ │ │ │ │ ├── overall_header_navigation_prepend.html # A template event
│ │ │ │ │ └── ...
│ │ │ │ └── ...
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
Administration control panel (ACP)¶
Add a functional ACP module for an extension to the ACP’s Extensions tab.
The Skeleton Extension will generate all the files needed for a functioning ACP module including its migration, language, style and PHP files:
vendor
├── package
│ ├── acp # Dir containing ACP module PHP files
│ │ ├── main_info.php # Module information
│ │ ├── main_module.php # Module execution logic
│ │ └── ...
│ ├── adm # Dir containing ACP module HTML templates
│ │ ├── style # ACP templates are loaded from the style dir
│ │ │ ├── acp_demo_body.html # Sample ACP HTML template file
│ │ │ └── ...
│ │ └── ...
│ ├── controller # Dir containing controller files
│ │ ├── acp_controller.php # A sample ACP controller class
│ │ └── ...
│ ├── language # Dir containing language files
│ │ ├── en # English language files (required)
│ │ │ ├── common.php # A language file used by the extension
│ │ │ ├── info_acp_demo.php # An auto-loaded lang file for ACP modules
│ │ │ └── ...
│ │ └── ...
│ ├── migrations # Dir containing migration files
│ │ ├── install_acp_module.php # A migration installing the ACP module
│ │ └── ...
│ └── ...
└── ...
Note
The ACP is not yet part of phpBB’s container-based dependency injection system, so it does not utilise a services YAML file.
Moderator control panel (MCP)¶
Add a functional MCP module for an extension to the MCP.
The Skeleton Extension will generate all the files needed for a functioning MCP module including its migration, language, style and PHP files:
vendor
├── package
│ ├── controller # Dir containing controller files
│ │ ├── mcp_controller.php # A sample MCP controller class
│ │ └── ...
│ ├── language # Dir containing language files
│ │ ├── en # English language files (required)
│ │ │ ├── info_mcp_demo.php # An auto-loaded lang file for MCP modules
│ │ │ └── ...
│ │ └── ...
│ ├── mcp # Dir containing MCP module PHP files
│ │ ├── main_info.php # Module information
│ │ ├── main_module.php # Module execution logic
│ │ └── ...
│ ├── migrations # Dir containing migration files
│ │ ├── install_mcp_module.php # A migration installing the MCP module
│ │ └── ...
│ ├── styles # The styles dir
│ │ ├── prosilver # Dir containing prosilver style files
│ │ │ ├── template # Dir containing HTML template files
│ │ │ │ ├── mcp_demo_body.html # Sample MCP HTML template file
│ │ │ │ └── ...
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
Note
The MCP is not yet part of phpBB’s container-based dependency injection system, so it does not utilise a services YAML file.
User control panel (UCP)¶
Add a functional UCP module for an extension to the UCP.
The Skeleton Extension will generate all the files needed for a functioning UCP module including its migration, language, style and PHP files:
vendor
├── package
│ ├── controller # Dir containing controller files
│ │ ├── ucp_controller.php # A sample UCP controller class
│ │ └── ...
│ ├── language # Dir containing language files
│ │ ├── en # English language files (required)
│ │ │ ├── info_ucp_demo.php # An auto-loaded lang file for UCP modules
│ │ │ └── ...
│ │ └── ...
│ ├── migrations # Dir containing migration files
│ │ ├── install_ucp_module.php # A migration installing the UCP module
│ │ ├── install_sample_schema.php # Contains changes used in the new module
│ │ └── ...
│ ├── styles # The styles dir
│ │ ├── prosilver # Dir containing prosilver style files
│ │ │ ├── template # Dir containing HTML template files
│ │ │ │ ├── ucp_demo_body.html # Sample UCP HTML template file
│ │ │ │ └── ...
│ │ │ └── ...
│ │ └── ...
│ ├── ucp # Dir containing UCP module PHP files
│ │ ├── main_info.php # Module information
│ │ ├── main_module.php # Module execution logic
│ │ └── ...
│ └── ...
└── ...
Note
The UCP is not yet part of phpBB’s container-based dependency injection system, so it does not utilise a services YAML file.
Database migration¶
Migration files are used to make database changes. This includes adding data to tables and schema changes (which are changes to the database’s tables and columns).
The Skeleton Extension will generate all of its sample migration files:
vendor
├── package
│ ├── migrations # Dir containing migration files
│ │ ├── install_acp_module.php # A migration installing the ACP module
│ │ ├── install_mcp_module.php # A migration installing the MCP module
│ │ ├── install_ucp_module.php # A migration installing the UCP module
│ │ ├── install_sample_schema.php # Sample schema changes to the database
│ │ ├── install_sample_data.php # Sample data changes to the database
│ │ └── ...
│ └── ...
└── ...
Service¶
The Service component is a PHP class that does something behind the scenes. It is a class that can be accessed by controllers, event listeners, or control panel modules.
The Skeleton Extension will generate a sample class that simply returns the current user object. It shows how to use dependency injection for services and parameters, thus it includes sample config and parameter YAML files:
vendor
├── package
│ ├── config # The config dir contains all service config files
│ │ ├── parameters.yml # A parameter YAML file
│ │ ├── services.yml # A config YAML file
│ │ └── ...
│ ├── service.php # A sample PHP file that contains a class/object
│ └── ...
└── ...
Controller (front page)¶
Controllers are typically used for front-facing files/classes. They run the code that produces a new and complete page that the user will interact with. Examples of front-facing pages an extension may use include a news page, a blog, a FAQ, etc.
The Skeleton Extension generates a front-facing page that displays a “Hello world” message to the user. Included with this component are the HTML template file for the page, PHP and template event listeners (to demonstrate adding a link to the new page in the nav bar), the language file, and the config and routing YAML files:
vendor
├── package
│ ├── config # The config dir contains all service config files
│ │ ├── routing.yml # A routing YAML file
│ │ ├── services.yml # A config YAML file
│ │ └── ...
│ ├── controller # Dir containing controller files
│ │ ├── main_controller.php # A sample controller class
│ │ └── ...
│ ├── event # The event dir contains all PHP event listeners
│ │ ├── main_listener.php # A sample PHP event listener
│ │ └── ...
│ ├── language # Dir containing language files
│ │ ├── en # English language files (required)
│ │ │ ├── common.php # A language file used by the extension
│ │ │ └── ...
│ │ └── ...
│ ├── styles # The styles dir
│ │ ├── prosilver # Dir containing prosilver style files
│ │ │ ├── template # Dir containing HTML template files
│ │ │ │ ├── demo_body.html # An HTML template used by the controller
│ │ │ │ ├── event # Dir containing template event files
│ │ │ │ │ ├── overall_header_navigation_prepend.html # A template event
│ │ │ │ │ └── ...
│ │ │ │ └── ...
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
Extension base (ext.php)¶
The optional ext.php file can be used to run code before or during
extension installation and removal operations. This is most useful if
your extension needs to run code when it is enabled, disabled, or
purged. Extensions have also used it to check if phpBB satisfies the
requirements of the extension before proceeding with installation, to
define class constants, and more.
The Skeleton Extension will generate a sample ext.php class. This class
is empty by default but can be populated with methods when used with
other components (such as Notifications):
vendor
├── package
│ ├── ext.php # A sub class. The class and file name can not be changed.
│ └── ...
└── ...
Console command¶
Extensions can add their own commands to phpBB’s command line interface (CLI). This is useful for extension that can provide additional terminal commands to perform certain actions.
The Skeleton Extension will generate a simple CLI command, including the necessary language and config files:
vendor
├── package
│ ├── config # The config dir contains all service config files
│ │ ├── services.yml # A config YAML file
│ │ └── ...
│ ├── console # Dir containing CLI related classes
│ │ ├── command # Dir containing CLI command classes
│ │ │ ├── sample.php # A sample CLI command class
│ │ │ └── ...
│ │ └── ...
│ ├── language # Dir containing language files
│ │ ├── en # English language files (required)
│ │ │ ├── cli.php # A language file used by the extension
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
Cron task¶
A cron task allows an extension to schedule and run actions at specific time intervals.
The Skeleton Extension will generate a simple cron task, including the necessary migration and config files:
vendor
├── package
│ ├── config # The config dir contains all service config files
│ │ ├── services.yml # A config YAML file
│ │ └── ...
│ ├── cron # Dir containing cron related classes
│ │ ├── task # Dir containing cron task classes
│ │ │ ├── sample.php # A sample cron task class
│ │ │ └── ...
│ │ └── ...
│ ├── migrations # Dir containing migration files
│ │ ├── install_cron.php # A migration installing cron related data
│ │ └── ...
│ └── ...
└── ...
Notifications¶
Notifications allow an extension to notify users of specific activities through phpBB’s notification system.
The Skeleton Extension will generate a sample notification, including
the necessary language and config files. Additionally it will generate
an ext.php file with important actions that must run during an
extension’s enable, disable and purge steps:
vendor
├── package
│ ├── config # The config dir contains all service config files
│ │ ├── services.yml # A config YAML file
│ │ └── ...
│ ├── ext.php # Contains enable, disable and purge steps
│ ├── language # Dir containing language files
│ │ ├── en # English language files (required)
│ │ │ ├── common.php # A language file used by the extension
│ │ │ ├── info_ucp_demo.php # A UCP language file used by the notification
│ │ │ └── ...
│ │ └── ...
│ ├── notification # Dir containing notification related classes
│ │ ├── type # Dir containing notification types
│ │ │ ├── sample.php # A sample notification type class
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
Permissions¶
Permissions can be used to grant users, groups and roles access to specific extension features and functionality.
The Skeleton Extension will generate a migration file showing the installation of admin, moderator and user level permissions and assign then to some roles and user groups. Additionally, the required permissions language file is created as well as a PHP event that shows how permissions are assigned to their respective language keys and permission categories:
vendor
├── package
│ ├── config # The config dir contains all service config files
│ │ ├── services.yml # A config YAML file
│ │ └── ...
│ ├── event # The event dir contains all PHP event listeners
│ │ ├── main_listener.php # A sample PHP event listener
│ │ └── ...
│ ├── language # Dir containing language files
│ │ ├── en # English language files (required)
│ │ │ ├── permissions_demo.php # A language file specifically for permissions
│ │ │ └── ...
│ │ └── ...
│ ├── migrations # Dir containing migration files
│ │ ├── install_sample_data.php # Sample data changes to the database
│ │ └── ...
│ └── ...
└── ...
Tests (PHPUnit)¶
Unit tests can test an extension to verify that specific portions of its source code work properly. This helps ensure basic code integrity and prevents regressions as an extension is being developed and debugged.
The Skeleton Extension will generate some basic sample unit and functional tests:
vendor
├── package
│ ├── phpunit.xml.dist # A PHPUnit configuration file (do not edit)
│ ├── tests # Dir containing test scripts
│ │ ├── controller # Example dir containing controller tests
│ │ │ ├── main_test.php # A simple unit test (tests a controller class)
│ │ │ └── ...
│ │ ├── dbal # Example dir containing dbal tests
│ │ │ ├── fixtures # Dir containing database test fixtures
│ │ │ │ ├── config.xml # A database test fixture of the config table
│ │ │ │ └── ...
│ │ │ ├── simple_test.php # A simple test (tests a database interaction)
│ │ │ └── ...
│ │ ├── functional # Dir containing functional tests
│ │ │ ├── view_test.php # A simple functional test
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
Github Actions CI configuration¶
Github Actions is a platform for running your PHPUnit tests on a GitHub repository.
The Skeleton Extension will generate the basic workflow script file needed to test your phpBB extension with each commit and pull request pushed to your GitHub repository:
vendor
├── package
│ ├── .github # A hidden directory to contain Github related files
│ │ ├── workflows # A directory to contain any test scripts
│ | | ├── tests.yml # The test configuration script in YAML format
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
Warning
The .github directory is a hidden folder. You can view and access it
using a Text Editor or IDE that is capable of displaying hidden folders.
Note
The Skeleton Extension currently does not allow you to generate the Github Actions CI component without also generating the PHPUnit tests component. This is because without unit tests, there is little benefit to using Github Actions.
Travis CI configuration¶
Travis CI is a platform for running your PHPUnit tests on a GitHub repository.
The Skeleton Extension will generate the basic config and script files needed to test your phpBB extension with each commit and pull request pushed to your GitHub repository:
vendor
├── package
│ ├── .travis.yml # A Travis CI configuration file
│ ├── tests # Dir containing PHPUnit tests
│ ├── travis # Dir containing Travis CI scripts
│ │ ├── prepare-phpbb.sh # Script required by Travis CI during testing (do not edit)
│ │ └── ...
│ └── ...
└── ...
Warning
The .travis.yml is a hidden file. You can view and edit it
using a Text Editor or IDE that is capable of displaying hidden
files.
Note
The Skeleton Extension currently does not allow you to generate the Travis CI component without also generating the PHPUnit tests component. This is because without unit tests, there is little benefit to using Travis CI.
Build script (phing)¶
A phing build script is generated for your extension which can be used to generate build packages to help simplify the release or deployment process.
For example, when you are ready to release a version of your extension, running the build script will package your extension in the appropriate vendor/package format and generate a ZIP file ready to submit to phpBB’s Customisation Database. It can also clean out files not intended for distribution such as unit tests and hidden Git files.
To run the build script, use the following console commands:
# Navigate to the root of your extension
$ cd ./path/to/phpBB/vendor/package
# If you don't already have phing installed, get from composer:
$ php ./path/to/composer.phar install
# Run phing:
$ ./vendor/bin/phing
After phing successfully completes its process, a build folder will
be added to your repository:
vendor
├── package
│ ├── build.xml # A phing build configuration file
│ ├── build # Dir used by the build process
│ │ ├── checkout # A zipped archive of your current Git repository
│ │ ├── package # The packaged extension, as built by phing
│ │ ├── upload # The packaged extension, zipped for distribution
│ │ └── ...
│ └── ...
└── ...
Warning
Never commit the build directory to Git or your repository.
You should add build/ to your .gitignore to ensure Git
ignores this directory.