### Example Command Usage Output
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
This is an example of the output when requesting help for the 'config:set' command, illustrating its usage and optional arguments.
```bash
Usage:
config:set [-d|--dynamic] key value
```
--------------------------------
### Install phpBB with CLI Configuration
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
This snippet shows a sample YAML configuration file for the phpBB CLI installer. It includes settings for the administrator, board details, database connection (MySQLi example), email configuration, server variables, and extensions.
```yaml
installer:
admin:
name: admin
password: mypassword
email: admin@example.org
board:
lang: en
name: My Board
description: My amazing new phpBB board
database:
dbms: mysqli
dbhost: ~
dbport: ~
dbuser: bertie
dbpasswd: bertiepasswd
dbname: bertiedb
table_prefix: phpbb_
email:
enabled: false
smtp_delivery : ~
smtp_host: ~
smtp_port: ~
smtp_auth: ~
smtp_user: ~
smtp_pass: ~
server:
cookie_secure: false
server_protocol: http://
force_server_vars: false
server_name: localhost
server_port: 80
script_path: /
extensions: ['phpbb/viglink']
```
--------------------------------
### Execute phpBB Installation via CLI
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
This command demonstrates how to initiate the phpBB installation process using the CLI installer, referencing a specified YAML configuration file.
```bash
$ php install/phpbbcli.php install install-config.yml
```
--------------------------------
### Get General CLI Help
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
The 'help' command provides general assistance and information on how to use the phpBB CLI.
```bash
$ php bin/phpbbcli.php help
```
--------------------------------
### Execute phpBB CLI
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
This command executes the main phpBB CLI application. It should output information about the installed CLI if successful.
```bash
$ php bin/phpbbcli.php
```
--------------------------------
### Get Help for a Specific Command
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
This command shows detailed help for a specific CLI command, such as 'config:set', including its usage, arguments, and options.
```bash
$ php bin/phpbbcli.php config:set --help
```
--------------------------------
### Navigate to phpBB Directory
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
This command navigates you to the root directory of your phpBB installation using the 'cd' command in a shell environment.
```bash
$ cd path/to/phpBB
```
--------------------------------
### List Available CLI Commands
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
The 'list' command displays all available commands for the phpBB CLI, allowing users to see the full range of functionalities.
```bash
$ php bin/phpbbcli.php list
```
--------------------------------
### Execute phpBB Update via CLI
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
This command demonstrates how to initiate the phpBB update process using the CLI updater, referencing a specified YAML configuration file.
```bash
$ php install/phpbbcli.php update update-config.yml
```
--------------------------------
### phpBB Extension Tutorial: Getting Started
Source: https://area51.phpbb.com/docs/dev/3.3.x/index
A tutorial for developing phpBB extensions, covering the initial steps and fundamental concepts required to create new functionalities.
```php
// Example of an extension's main file structure (conceptual)
namespace vendor\ext\extname\event;
use Symfony\Component\EventDispatcher\Event;
class listener_extname_main extends __Event
{
public static $events = array(
'core.user_add_before' => 'user_add_before',
);
public function user_add_before($event)
{
// Extension logic here
}
}
```
--------------------------------
### phpBB Skeleton Extension: Installation and Creation
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/index
This guide explains how to install and create a phpBB extension using the phpBB Skeleton Extension. It provides the necessary steps and documentation references for getting started with extension development.
```bash
# Example of installing the skeleton extension via Composer
composer create-project phpbb/skeleton-extension my-new-extension
cd my-new-extension
composer install
```
```php
// Example of the ext.php file in the skeleton extension
namespace phpbb\extension\skeleton;
class ext extends \phpbb\extension\base
{
public function main($what)
{
// Extension main logic
}
}
```
--------------------------------
### Update phpBB with CLI Configuration (All)
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/getting_started
This YAML configuration is used for updating phpBB via the CLI. It specifies that both the database and files should be updated.
```yaml
updater:
type: all
extensions: ['phpbb/viglink']
```
--------------------------------
### phpBB Extension Development: Getting Started
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/index
This section guides users through the initial steps of creating a phpBB extension. It covers the essential components like the extension folder structure and the Composer JSON file, which is crucial for managing dependencies and extension metadata.
```php
// Example of a basic extension folder structure
// ext/
// vendor/
// your_namespace/
// your_extension/
// composer.json
// ext.php
// config.yml
// language/
// styles/
// migrations/
// controller/
// event/
// Example of composer.json content for a phpBB extension
{
"name": "vendor/your_extension",
"type": "phpbb-extension",
"version": "1.0.0",
"description": "A sample phpBB extension.",
"keywords": ["phpbb", "extension"],
"homepage": "https://your-website.com",
"license": "MIT",
"authors": [
{
"name": "Your Name",
"email": "your.email@example.com"
}
],
"require": {
"php": ">=7.0.0",
"composer/installers": "^1.0"
},
"extra": {
"display-name": "Your Extension",
"version": "1.0.0",
"phpbb-version": "3.3.*",
"branch-alias": {
"dev-master": "1.0.x-dev"
}
}
}
```
--------------------------------
### Create New Migration Class in PHP
Source: https://area51.phpbb.com/docs/dev/3.3.x/migrations/getting_started
Defines the basic structure for a new migration class in phpBB. It requires extending the `phpbbdbmigrationmigration` class and provides a placeholder for database change instructions.
```PHP
* @license GNU General Public License, version 2 (GPL-2.0)
*
* For full copyright and license information, please see
* the docs/CREDITS.txt file.
*
*/
class phpbb_demo_db_demo_test extends phpbb_database_test_case
{
public function getDataSet()
{
return $this->createXMLDataSet(dirname(__FILE__) . '/fixtures/three_users.xml');
}
public function fetchrow_data()
{
return [
['', [['username_clean' => 'barfoo'],
['username_clean' => 'foobar'],
['username_clean' => 'bertie']]],
['user_id = 2', [['username_clean' => 'foobar']]],
["username_clean = 'bertie'", [['username_clean' => 'bertie']]],
["username_clean = 'phpBB'", []],
];
}
/**
* @dataProvider fetchrow_data
*/
public function test_fetchrow($where, $expected)
{
// The function from phpbb_test_case_helpers returns a new db for every test.
$db = $this->new_dbal();
$result = $db->sql_query('SELECT username_clean
FROM phpbb_users
' . (($where) ? ' WHERE ' . $where : '') . '
ORDER BY user_id ASC');
$ary = [];
while ($row = $db->sql_fetchrow($result))
{
$ary[] = $row;
}
$db->sql_freeresult($result);
$this->assertEquals($expected, $ary);
}
}
```
--------------------------------
### Install phpBB Skeleton Extension
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/skeleton_extension
Instructions for installing the phpBB Skeleton Extension like any other phpBB extension. It involves downloading, unzipping into the 'ext/' folder, and enabling it via the phpBB Admin Control Panel (ACP). The extension is recommended for local development environments.
```bash
Download the latest release.
Unzip and install it to your phpBB `ext/` folder, e.g. `phpBB/ext/phpbb/skeleton`
In phpBB, go to “ACP” > “Customise” > “Extensions” and enable “phpBB Skeleton Extension”.
```
--------------------------------
### Install Composer Dependencies
Source: https://area51.phpbb.com/docs/dev/3.3.x/development/git
Installs the project's dependencies using Composer. This command should be run from the phpBB directory after cloning the repository.
```shell
cd phpBB
php ../composer.phar install
```
--------------------------------
### Load Core Language Files
Source: https://area51.phpbb.com/docs/dev/3.3.x/language/usage
Loads additional language files during user setup or after setup has been called. `phpbb\user::setup()` is used for initial loading, while `phpbb\language\language::add_lang()` is used for subsequent loads.
```php
$user->setup('search');
// or
$user->setup(['ucp', 'search']);
```
```php
$language->add_lang('search');
// or
$language->add_lang(['ucp', 'search']);
```
--------------------------------
### PHPBB Language File Example
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_key_concepts
An example of a common language file for a phpBB extension, defining various language strings for different parts of the application.
```php
'Demo',
'DEMO_HELLO' => 'Hello %s!',
'DEMO_GOODBYE' => 'Goodbye %s!',
'ACP_DEMO_TITLE' => 'Demo Module',
'ACP_DEMO' => 'Settings',
'ACP_DEMO_GOODBYE' => 'Should say goodbye?',
'ACP_DEMO_SETTING_SAVED' => 'Settings have been saved successfully!',
]);
```
--------------------------------
### Plural Rules Example
Source: https://area51.phpbb.com/docs/dev/3.3.x/language/index
A short example demonstrating how plural rules are defined and used within the phpBB language system to handle different quantities.
```php
// Example plural rule definition
$plural_rules = array(
'nplurals' => 2,
'plural' => 'n != 1',
);
// Using plural strings in templates
// {NUMBER_OF_ITEMS} = 1: One item
// {NUMBER_OF_ITEMS} = 2: 2 items
```
--------------------------------
### Example Plural Rule Structure with Zero Handling
Source: https://area51.phpbb.com/docs/dev/3.3.x/language/plurals
This example demonstrates how to include a specific case for zero ('0') in the plural rule definition. This allows for distinct handling of the 'no examples' scenario.
```php
'EXAMPLE' => [
0 => 'No example',
1 => '1 example',
2 => '[zero is not handled here anymore! Only number ending with 01-10] examples',
3 => '[number ending with 11-19] example',
4 => 'even more examples',
],
```
--------------------------------
### phpBB 3.1 find_users_for_notification() Example
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/new_in_rhea
Provides an example of the `find_users_for_notification()` method in phpBB 3.1, which is used to query the database for users who should receive a notification. It shows how to fetch user IDs and prepare them for notification processing.
```php
public function find_users_for_notification($data, $options = [])
{
// run code to query a group of users from the database...
while ($row = $this->db->sql_fetchrow($result))
{
$users[$row['user_id']] = [''];
}
// do any additional processing...
return $users;
}
```
--------------------------------
### phpBB Migration Dependencies
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_migrations
Defines a migration's dependencies to ensure correct installation order. The depends_on() method specifies which other migrations must be installed prior to the current one.
```php
public function depends_on()
{
return [
'phpbb\migration\data\v330\rc1\some_previous_migration',
];
}
```
--------------------------------
### phpBB Database Abstraction Layer
Source: https://area51.phpbb.com/docs/dev/3.3.x/index
Guides on using the Database Abstraction Layer (DBAL) in phpBB, covering connecting, preparing and running SQL queries, and methods for handling results after INSERT, UPDATE, and SELECT operations.
```php
// Example of preparing and running a query
$sql = "SELECT * FROM phpbb_users WHERE user_id = ?";
$db->sql_query($db->sql_build_params("SELECT"), $sql, $user_id);
$result = $db->sql_fetchrow();
```
--------------------------------
### XML Fixture for phpBB Database Test
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_testing
This XML file defines the structure and initial data for a phpBB configuration table used in database unit tests. It specifies the columns for the 'phpbb_config' table, serving as a dataset for test setup.
```XML
config_nameconfig_valueis_dynamic
```
--------------------------------
### phpBB Extension Template Directory Structure
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_key_concepts
Provides an example of the recommended directory structure for template and theme files within a phpBB extension. It includes organization for universal files and style-specific files like prosilver and subsilver2.
```HTML
styles
├── all
│ ├── template
│ │ └── event
│ │ └── overall_header_head_append.html
│ └── theme
│ ├── css
│ │ └── acme_demo_main.css
│ └── images
│ └── acme_demo_image.png
├── prosilver
│ └── template
│ ├── acme_demo_body.html
│ └── event
│ └── overall_header_navigation_append.html
└── subsilver2
└── template
├── acme_demo_body.html
└── event
└── overall_header_navigation_append.html
```
--------------------------------
### Add Services to Ordered Collection
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_advanced
This example shows how to add services ('acme.demo.foobar_foo' and 'acme.demo.foobar_bar') to an ordered service collection. The 'order' tag specifies the loading sequence.
```yaml
acme.demo.foobar_foo:
class: acme\demo\foobar_foo
tags:
- { name: acme.demo.foobar_service, order: 1 }
acme.demo.foobar_bar:
class: acme\demo\foobar_bar
tags:
- { name: acme.demo.foobar_service, order: 2 }
```
--------------------------------
### phpBB 3.1 create_insert_array() Example
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/new_in_rhea
Shows the `create_insert_array()` method in phpBB 3.1, which prepares data for database insertion by returning an array from the parent class. This method was used to format data before it was sent to the database.
```php
public function create_insert_array($data, $pre_create_data = [])
{
// prepare some data...
return parent::create_insert_array($data, $pre_create_data);
}
```
--------------------------------
### phpBB Extension Development: Modules
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/index
This tutorial focuses on creating Control Panel (ACP) modules for your phpBB extensions. It explains how to create modules, install them, and integrate them into the phpBB administration interface.
```php
// Example of an ACP module definition (e.g., ext/vendor/your_extension/acp/main_module.php)
namespace your_namespace\your_extension\acp;
class main_module
{
var $u_action;
function main($id, $page_no, &$common, &$tpl)
{
global $phpbb_root_path, $phpbb_admin_path, $phpEx;
// Assign template variables
$tpl->assign_vars(array(
'L_TITLE' => 'My Extension Module',
'L_EXPLAIN' => 'Manage settings for my extension.'
));
// Define the action URL
$this->u_action = append_sid("$phpbb_admin_path/page_ செய்யுங்கள்.php", "i=$id&mode=manage");
$tpl->assign_vars(array(
'U_ACTION' => $this->u_action
));
// Include the module's language file
$user->add_lang_module('acp/main');
// Display the module page
return array(
'title' => 'ACP_MY_EXTENSION_MODULE',
'tpl_file' => 'acp/my_extension_module_body.html'
);
}
}
```
```php
// Example of an ACP module language file (e.g., ext/vendor/your_extension/language/en/acp/main.php)
'My Extension Module',
'ACP_MY_EXTENSION_MODULE_EXPLAIN' => 'Manage settings for my extension.',
);
```
--------------------------------
### phpBB Database Migration Files
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/skeleton_extension
Illustrates the directory structure for database migration files in a phpBB extension. This includes files for installing ACP, MCP, and UCP modules, as well as schema and data changes.
```php
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
│ │ └── ...
│ └── ...
└── ...
```
--------------------------------
### Configuring Extension Setup for phpBB Database Tests
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_testing
This PHP code snippet demonstrates how to configure phpBB unit tests to recognize and set up a specific extension. By overriding the `setup_extensions()` method, the test suite ensures that the 'acme/demo' extension is properly initialized before running database-related tests.
```PHP
class add_database_changes_test extends \phpbb_database_test_case
{
static protected function setup_extensions()
{
return ['acme/demo'];
}
...
```
--------------------------------
### Check Extension Enableability with ext.php
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_advanced
This PHP code overrides the `is_enableable()` method in the `ext.php` file to enforce extension requirements, such as a minimum phpBB version. If the condition is not met, the extension will not be installed, and the user will be notified.
```php
container->get('config');
return phpbb_version_compare($config['version'], '3.1.5', '>=');
}
}
```
--------------------------------
### Run PHPUnit Tests
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_testing
This command executes the PHPUnit test suite for the extension using the specified configuration file. It can also be used to run tests from a specific file by appending its path.
```bash
$ ./phpBB/vendor/bin/phpunit -c phpBB/ext/acme/demo/phpunit.xml.dist
```
```bash
$ ./phpBB/vendor/bin/phpunit -c phpBB/ext/acme/demo/phpunit.xml.dist phpBB/ext/acme/demo/tests/controller/main_test.php
```
--------------------------------
### phpBB Extension Development: Controllers and Routes
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/index
This tutorial explains how to create custom controllers and define routes for your phpBB extensions. This allows you to build custom pages and functionality accessible via specific URLs within your phpBB installation.
```php
// Example of a controller file (e.g., ext/vendor/your_extension/controller/main.php)
namespace your_namespace\your_extension\controller;
use phpbb\controller\base_controller;
use phpbb\request\request_interface;
use phpbb\template\template;
class main extends base_controller
{
protected $request;
protected $template;
public function __construct(request_interface $request, template $template)
{
$this->request = $request;
$this->template = $template;
}
public function display_page($param)
{
$this->template->assign_vars(array(
'PAGE_TITLE' => 'My Custom Page',
'MESSAGE' => 'This is a page generated by my extension.'
));
return $this->response('my_custom_page.html');
}
}
```
```php
// Example of defining routes in config.yml (e.g., ext/vendor/your_extension/config.yml)
services:
your_extension.controller.main:
class: your_namespace\your_extension\controller\main
arguments:
- '@request'
- '@template'
routing:
- name: your_extension_page
url: /ext/your_extension/my_page/{param}
defaults:
_controller: your_extension.controller.main::display_page
methods: [GET]
```
--------------------------------
### Update phpBB using CLI
Source: https://area51.phpbb.com/docs/dev/3.3.x/cli/index
This section details the process of updating an existing phpBB installation using the Command Line Interface (CLI). It covers the commands required to apply updates smoothly.
```bash
php bin/phpbbcli.php update
```
--------------------------------
### Write phpBB Unit Tests Without Database
Source: https://area51.phpbb.com/docs/dev/3.3.x/testing/unit_testing
Example of a PHP unit test for phpBB that does not require database interaction. It uses a data provider to supply test cases for the `phpbb_email_hash` function.
```PHP
assertEquals($expected, phpbb_email_hash($email));
}
}
```
--------------------------------
### Define Newspage Migration Dependencies
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/modification_to_extension
The `depends_on()` static function specifies dependencies for a migration, ensuring that required prior migrations are installed first. This example shows a dependency on phpBB's `3.1.0-a1` migration.
```php
static public function depends_on()
{
return ['\phpbb\db\migration\data\v310\alpha1'];
}
```
--------------------------------
### phpBB Controller for Front Page
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/skeleton_extension
Controllers are used for front-facing files and classes that generate complete pages for user interaction. This example shows the typical directory structure for a controller, including its PHP file, HTML template, and event listeners.
```php
vendor
├── package
│ ├── controller
│ │ ├── main_controller.php
│ │ └── ...
│ ├── event
│ │ ├── main_listener.php
│ │ └── ...
│ ├── language
│ │ ├── en
│ │ │ ├── common.php
│ │ │ └── ...
│ │ └── ...
│ ├── styles
│ │ ├── prosilver
│ │ │ ├── template
│ │ │ │ ├── demo_body.html
│ │ │ │ ├── event
│ │ │ │ │ ├── overall_header_navigation_prepend.html
│ │ │ │ │ └── ...
│ │ │ │ └── ...
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
```
```yml
vendor
├── package
│ ├── config
│ │ ├── routing.yml
│ │ ├── services.yml
│ │ └── ...
│ └── ...
└── ...
```
```html
vendor
├── package
│ ├── styles
│ │ ├── prosilver
│ │ │ ├── template
│ │ │ │ ├── demo_body.html
│ │ │ │ ├── event
│ │ │ │ │ ├── overall_header_navigation_prepend.html
│ │ │ │ │ └── ...
│ │ │ │ └── ...
│ │ │ └── ...
│ │ └── ...
│ └── ...
└── ...
```
--------------------------------
### Executing phpBB Unit Tests with PHPUnit
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_testing
This command executes phpBB unit tests using PHPUnit. It specifies the configuration file for the tests, allowing developers to run tests for specific extensions and verify their functionality.
```Bash
$ ./phpBB/vendor/bin/phpunit -c phpBB/ext/acme/demo/phpunit.xml.dist
```
--------------------------------
### Retrieve File Upload Information with phpBB Request
Source: https://area51.phpbb.com/docs/dev/3.3.x/request/request
Provides an example of using the `file()` method, a shortcut for retrieving information about uploaded files via the `$_FILES` superglobal. It shows how to get file details and subsequently handle the upload process.
```php
$upload_file = $request->file('avatar_upload_file');
if (!empty($upload_file['name']))
{
$file = $upload->handle_upload('files.types.form', 'avatar_upload_file');
}
```
--------------------------------
### Render Template using Controller Helper in PHP
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_controllers
This PHP code demonstrates how to use the phpBB controller helper to render a template file. It shows both the general approach and the recommended method using an extension-specific prefix.
```php
$this->helper->render('demo_body.html', $name);
```
```php
$this->helper->render('@acme_demo/demo_body.html', $name);
```
--------------------------------
### phpBB Extension Development: Testing
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/index
This guide covers various testing methodologies for phpBB extensions, including unit tests, unit tests with database interaction, and functional testing. It also touches upon continuous integration with GitHub Actions.
```php
// Example of a basic unit test (conceptual, using PHPUnit)
namespace your_namespace\your_extension\tests;
use PHPUnit\Framework\TestCase;
class my_test extends TestCase
{
public function testSomething()
{
$this->assertTrue(true);
}
}
```
```php
// Example of a unit test with database interaction (conceptual)
// Requires setting up a test database connection and mocking/setting up data.
```
--------------------------------
### PhpStorm Configuration for phpBB Development
Source: https://area51.phpbb.com/docs/dev/3.3.x/index
Instructions on setting up PhpStorm for phpBB development, including project creation, code style configuration, inspections, and PHPUnit integration.
```ini
; Example PhpStorm code style settings (conceptual)
[CodeStyle]
php.indent.size = 4
php.tab.size = 4
```
--------------------------------
### Execute Code at End of User Setup
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/events_list
This event allows for the execution of custom code at the very end of the user setup process. It is located in `phpbb/user.php`.
```php
core.user_setup_after
```
--------------------------------
### Run phing Build Script
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/skeleton_extension
This snippet shows the console commands required to navigate to the extension's root directory, install phing using composer if necessary, and execute the phing build script. It facilitates the packaging and release process for phpBB extensions.
```bash
# 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
```
--------------------------------
### Testing phpBB Extensions with GitHub Actions
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_testing
This section details how to set up continuous integration for testing phpBB extensions using GitHub Actions. It covers creating workflow files and customizing the test execution.
```yaml
# Example GitHub Actions workflow file for testing phpBB extensions
# This is a conceptual example and would need to be adapted
# to the specific needs of the extension and its dependencies.
name: PHPBB Extension Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.0'
- name: Install Dependencies
run: composer install --prefer-dist --no-progress
- name: Run phpBB Tests
run: |
# Assuming you have a script or command to run tests, e.g., vendor/bin/phpunit
# This would typically involve setting up a test database and running the tests.
# Example command (replace with actual command):
# php bin/run-tests.php --extension=my_extension
echo "Running phpBB tests..."
# Placeholder for actual test execution command
exit 0 # Replace with actual test command that returns non-zero on failure
```
--------------------------------
### phpBB Extension Base File (ext.php)
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/skeleton_extension
The optional `ext.php` file is used for executing code during extension installation, enabling, disabling, or purging. It can also be used for requirement checks and defining class constants. The file name and class name cannot be altered.
```php
vendor
├── package
│ ├── ext.php
│ └── ...
└── ...
```
--------------------------------
### Install Migration Schema Changes (PHP)
Source: https://area51.phpbb.com/docs/dev/3.3.x/migrations/schema_changes
The `update_schema()` function is called during the installation of a migration to apply database schema changes. It should return an array of schema modification instructions.
```PHP
public function update_schema()
{
return [];
}
```
--------------------------------
### PHP: Manage Filesystem Changes with Migrations
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_advanced
This PHP code demonstrates how to manage filesystem changes, such as creating and removing directories, using phpBB's migration system. It includes methods for checking if files exist, defining installation order, and executing custom filesystem operations during update and revert processes.
```PHP
filesystem))
{
$this->filesystem = $this->container->get('filesystem');
$this->acme_demo_dir = $this->container->getParameter('core.root_path') . 'store/acme_demo_dir';
}
}
public function effectively_installed()
{
$this->init();
return $this->filesystem->exists($this->acme_demo_dir);
}
public static function depends_on()
{
return ['\acme\demo\migrations\first_migration'];
}
public function update_data(): array
{
return [
['custom', [[$this, 'add_dir']]],
];
}
public function revert_data(): array
{
return [
['custom', [[$this, 'remove_dir']]],
];
}
public function add_dir()
{
$this->init();
try
{
$this->filesystem->mkdir($this->acme_demo_dir, 0755);
$this->filesystem->touch($this->acme_demo_dir . '/index.htm');
}
catch (\phpbb\filesystem\exception\filesystem_exception $e)
{
// log or handle any errors here using $e->get_filename() or $e->getMessage()
}
}
public function remove_dir()
{
$this->init();
try
{
$this->filesystem->remove($this->acme_demo_dir);
}
catch (\phpbb\filesystem\exception\filesystem_exception $e)
{
// log or handle any errors here using $e->get_filename() or $e->getMessage()
}
}
}
```
--------------------------------
### Example Plural Rule Structure (4 Rows)
Source: https://area51.phpbb.com/docs/dev/3.3.x/language/plurals
An example of a plural rule structure with 4 rows, defining how different number endings are categorized for pluralization. This structure is used when a language has more complex plural forms than English.
```php
'EXAMPLE' => [
1 => '1 example',
2 => '[0 or number ending with 01-10] examples',
3 => '[number ending with 11-19] example',
4 => 'even more examples',
],
```
--------------------------------
### Get Variable Names from Super Global
Source: https://area51.phpbb.com/docs/dev/3.3.x/request/request
This function returns all variable names (keys) for a specific super global (GET, POST, REQUEST, COOKIE, SERVER, FILES). If no super global is specified, it defaults to REQUEST.
```PHP
// Converts query string (GET) parameters in request into hidden fields.
$hidden = '';
$names = $request->variable_names(\phpbb\request\request_interface::GET);
foreach ($names as $name)
{
// Sessions are dealt with elsewhere, omit sid always
if ($name == 'sid')
{
continue;
}
$value = $request->variable($name, '', true);
$get_value = $request->variable($name, '', true, \phpbb\request\request_interface::GET);
if ($value === $get_value)
{
$escaped_name = phpbb_quoteattr($name);
$escaped_value = phpbb_quoteattr($value);
$hidden .= "";
}
}
return $hidden;
```
--------------------------------
### Install ACP Module and Config - PHP
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_modules
This PHP migration class installs a new configuration variable and adds an ACP module to the phpBB control panel. It defines dependencies and provides an update_data method to add the configuration and module entries to the database.
```PHP
config['acme_demo_goodbye']);
}
/**
* This migration depends on phpBB's v314 migration
* already being installed.
*/
static public function depends_on()
{
return ['\phpbb\db\migration\data\v31x\v314'];
}
public function update_data()
{
return [
// Add the config variable we want to be able to set
['config.add', ['acme_demo_goodbye', 0]],
// Add a parent module (ACP_DEMO_TITLE) to the Extensions tab (ACP_CAT_DOT_MODS)
['module.add', [
'acp',
'ACP_CAT_DOT_MODS',
'ACP_DEMO_TITLE'
]],
// Add our main_module to the parent module (ACP_DEMO_TITLE)
['module.add', [
'acp',
'ACP_DEMO_TITLE',
[
'module_basename' => '\\acme\demo\acp\main_module',
'modes' => ['settings'],
],
]],
];
}
}
```
--------------------------------
### Complete phpBB Event Listener in PHP
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_controllers
This complete PHP class demonstrates a phpBB event listener, including its constructor for dependency injection (Controller Helper and Template objects), methods for subscribing to events (`getSubscribedEvents`), loading language files (`load_language_on_setup`), and adding a navigation link (`add_page_header_link`).
```php
namespace acme\demo\event;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
class main_listener implements EventSubscriberInterface
{
/* @var \phpbb\controller\helper */
protected $helper;
/* @var \phpbb\template\template */
protected $template;
/**
* Constructor
*
* @param \phpbb\controller\helper $helper
* @param \phpbb\template\template $template
*/
public function __construct(\phpbb\controller\helper $helper, \phpbb\template\template $template)
{
$this->helper = $helper;
$this->template = $template;
}
/**
* Assign functions defined in this class to event listeners in the core
*
* @return array
*/
static public function getSubscribedEvents()
{
return [
'core.user_setup' => 'load_language_on_setup',
'core.page_header' => 'add_page_header_link',
];
}
/**
* Load the Acme Demo language file
* acme/demo/language/en/demo.php
*
* @param \phpbb\event\data $event The event object
*/
public function load_language_on_setup($event)
{
$lang_set_ext = $event['lang_set_ext'];
$lang_set_ext[] = [
'ext_name' => 'acme/demo',
'lang_set' => 'demo',
];
$event['lang_set_ext'] = $lang_set_ext;
}
/**
* Add a page header nav bar link
*
* @param \phpbb\event\data $event The event object
*/
public function add_page_header_link($event)
{
$this->template->assign_vars([
'U_DEMO_PAGE' => $this->helper->route('acme_demo_route', ['name' => 'world']),
]);
}
}
```
--------------------------------
### Registering Event Listeners in PHP
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_controllers
This PHP code snippet shows how to define the events a listener subscribes to within a phpBB extension. It registers the `load_language_on_setup` method for the `core.user_setup` event and the `add_page_header_link` method for the `core.page_header` event.
```php
static public function getSubscribedEvents()
{
return [
'core.user_setup' => 'load_language_on_setup',
'core.page_header' => 'add_page_header_link',
];
}
```
--------------------------------
### Check if Newspage Migration is Effectively Installed
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/modification_to_extension
The `effectively_installed()` function checks if a migration has already been applied, even if it hasn't run yet. This is useful for updates from older versions or when table columns are added. It typically checks a configuration setting for the installed version.
```php
public function effectively_installed()
{
return isset($this->config['newspage_mod_version']) && version_compare($this->config['newspage_mod_version'], '1.0.0', '>=');
}
```
--------------------------------
### PHP Event Listener for Language File Loading
Source: https://area51.phpbb.com/docs/dev/3.3.x/extensions/tutorial_events
This PHP code defines an event listener class for phpBB extensions. It subscribes to the 'core.user_setup' event to load a custom language file ('demo.php') for the 'acme/demo' extension. The listener modifies the event object to include the language file, ensuring language keys are available.
```PHP
'load_language_on_setup',
];
}
/**
* Load the Acme Demo language file
* acme/demo/language/en/demo.php
*
* @param \phpbb\event\data $event The event object
*/
public function load_language_on_setup($event)
{
$lang_set_ext = $event['lang_set_ext'];
$lang_set_ext[] = [
'ext_name' => 'acme/demo',
'lang_set' => 'demo',
];
$event['lang_set_ext'] = $lang_set_ext;
}
}
```