phpbb/documentation

Documentation for end-users: board visitors, moderators and administrators

phpBB User Documentation

Documentation for board visitors, moderators and administrators can be seen online here.

phpBB Developer Documentation

Documentation for phpBB development and extension authors can be seen online here.

Get Involved

Do you have an improvement, bug fix or translation for our Docs? Read our Contributing guidelines to help improve our Documentation.

License

Documentation © 2021 phpBB Limited.
Licensed under the CC Attribution-NonCommercial-ShareAlike 3.0 license.

documentation's Issues

Migrate from sphinx-versioning to sphinx-multiversion

This should be fully compatible with newer sphinx versions, see quickstart:
https://holzhaus.github.io/sphinx-multiversion/master/quickstart.html

Here is an example of a documentation that is using sphinx-multiversion already:
https://github.com/mixxxdj/manual

"Updating a phpBB 3.0 modification to a phpBB 3.1 extension" links to migration wiki instead of the doc

https://area51.phpbb.com/docs/dev/31x/extensions/modification_to_extension.html#database-changes-umil-replaced-by-migrations

The docs for migrations have been moved already

Example Code License?

Hello!

I didn't see this mentioned anywhere, so I thought I'd open an issue about it.

What license is the example code in the documentation licensed under?

For example, I would like to copy and paste the code from here and modify it to suit my needs, but I'm not sure what license the code is made available under.

Thanks! :)

twig documentation

hi,
is there a twig documentation ? i'm missing it here and it's not on the wiki either.

Duplicate section "minor" after merging 3.2.x into 3.3.x

The 3.3.x documentation should not include the minor section for minor updates in the 3.2.x branch.

links returns : 404 not found

Hi guys,

Many links in this documentation return a 404 error.

https://www.phpbb.com/support/docs/en/3.1/ug/ => Section 1.2, “Installation”.
https://www.phpbb.com/support/docs/en/3.1/ug/quickstart/installation_intro/ => Figure 1.1, “Introduction”
https://www.phpbb.com/support/docs/en/3.1/ug/quickstart/installation_requirements/quick_requirements.php => section on phpBB3's requirements
and much more.

language/usage.rst should have a short section about loading extension files

with add_lang_ext()

Add documentation for extensions and unit tests

• Unit tests
• Functional tests
• Automatic testing on Travis CI

But this involves:

• having php in the enviroment path
• installing phpBB from git
• run composer
• using a git repo for the extension (travis only)

Use Twig in documentation code blocks

Update all HTML code blocks to use Twig instead of old phpBB template syntax.

3.2 documentation refers to deprecated settings & 3.1 forums

Some of the 3.2 documentation (userguide) refers to deprecated settings and 3.1 forums.

Missing Information - Update 3.0 - 3.1

On Page https://www.phpbb.com/support/docs/en/3.1/ug/upgradeguide/upgrade3/ i miss some information:

1. Going after this guide, the folder "cache" should be deleted. After this, the new folder is not writeable. I see 2 solutions: Telling the admin, not to delete but to empty the folder. Or telling the admin to set the writeable-rights. If the cache-folder is not writeable the database-update stops with error-message: cache not writeable.
2. Missing information: 7. Delete and rebuild the search-index after update.
3. Before starting the update you should tell the admin to think about the option to clear the database to a unmodded clean state with the 3.0.x-Tool because for 3.1 - until now - no database-cleanup-tool is available. Its not so easy to remove the bugs that are generated by old database-mod-changes.
4. For updates from 3.0.12 to 3.1.1 its better to take the database-update.php from the update-package, isnt it? Going through all 3.0.x-database-updates is irritating the admin.

Why i'am telling you this here? I hope this is the right place. - see: https://tracker.phpbb.com/browse/WEBSITE-1176?jql=project%20%3D%20WEBSITE

Maybe the reported bug 1176 about .htaccesss should be integrated too.

Add documentation for setting up PhpStorm

This should also include setting up proper JS hinting (see #32 (comment)).

Add a .gitignore

Add a .gitignore for thumbs and DS Store

Updates master banch (3.2.x => 3.3.x)

Changes:

• PHP x.x.x (to be determined)
• phpBB 3.2.x

Add filename to code examples

As requested by @nickvergessen I'm adding this as an issue:

It's really useful to see the filename in example code like Symfony's documentation has. I don't think it's necessary for all example code, but especially for large code blocks andcomplete files it is.

Maybe with /ext/ and the full path?

// ext/acme/demo/acp/main_module.php

E.g.

// ext/acme/demo/acp/main_module.php
<?php
/**
 *
 * This file is part of the phpBB Forum Software package.
 *
 * @copyright (c) phpBB Limited <https://www.phpbb.com>
 * @license GNU General Public License, version 2 (GPL-2.0)
 *
 * For full copyright and license information, please see
 * the docs/CREDITS.txt file.
 *
 */

namespace acme\demo\acp;

class main_info
{
    public function module()
    {
        return array(
            'filename'      => '\acme\demo\acp\main_module',
            'title'         => 'ACP_DEMO_TITLE',
            'version'       => '1.0.0',
            'modes'         => array(
                'settings' => array(
                    'title' => 'ACP_DEMO',
                    'auth'  => 'ext_acme/demo && acl_a_board',
                    'cat'   => array('ACP_DEMO_TITLE'),
                ),
            ),
        );
    }
}

Add documentation for new files classes in 3.2

PDF documentation does not build due to parse exception

When running the generation of the PDF documentation, we currently encounter this issue:

SEVERE: org.xml.sax.SAXParseException; systemId: file:documentation/documentation/xsl/pdf/fo/pagesetup.xsl; lineNumber: 689; columnNumber: 57; java.lang.reflect.UndeclaredThrowableException
Jan 29, 2023 1:27:44 PM org.apache.fop.cli.Main startFOP
SEVERE: Exception
org.apache.fop.apps.FOPException: javax.xml.transform.TransformerException: java.lang.reflect.UndeclaredThrowableException
javax.xml.transform.TransformerException: java.lang.reflect.UndeclaredThrowableException
        at org.apache.fop.cli.InputHandler.transformTo(InputHandler.java:303)
        at org.apache.fop.cli.InputHandler.renderTo(InputHandler.java:130)
        at org.apache.fop.cli.Main.startFOP(Main.java:177)
        at org.apache.fop.cli.Main.main(Main.java:208)
Caused by: javax.xml.transform.TransformerException: java.lang.reflect.UndeclaredThrowableException
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2416)
        at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1374)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.templates.ElemIf.execute(ElemIf.java:160)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1374)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.templates.ElemTemplate.execute(ElemTemplate.java:392)
        at org.apache.xalan.templates.ElemCallTemplate.execute(ElemCallTemplate.java:246)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1374)
        at org.apache.xalan.templates.ElemApplyTemplates.transformSelectedNodes(ElemApplyTemplates.java:393)
        at org.apache.xalan.templates.ElemApplyTemplates.execute(ElemApplyTemplates.java:176)
        at org.apache.xalan.templates.ElemApplyTemplates.transformSelectedNodes(ElemApplyTemplates.java:393)
        at org.apache.xalan.templates.ElemApplyTemplates.execute(ElemApplyTemplates.java:176)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.templates.ElemIf.execute(ElemIf.java:160)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.templates.ElemChoose.execute(ElemChoose.java:139)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.templates.ElemChoose.execute(ElemChoose.java:139)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.templates.ElemChoose.execute(ElemChoose.java:139)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        at org.apache.xalan.transformer.TransformerImpl.applyTemplateToNode(TransformerImpl.java:2281)
        at org.apache.xalan.transformer.TransformerImpl.transformNode(TransformerImpl.java:1367)
        at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:709)
        at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:1284)
        at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:1262)
        at org.apache.fop.cli.InputHandler.transformTo(InputHandler.java:300)
        ... 3 more
Caused by: java.lang.reflect.UndeclaredThrowableException
        at com.sun.proxy.$Proxy2.readUnsignedInt(Unknown Source)
        at org.apache.xmlgraphics.image.loader.impl.PreloaderEPS.preloadImage(PreloaderEPS.java:65)
        at org.apache.xmlgraphics.image.loader.ImageManager.preloadImage(ImageManager.java:175)
        at org.apache.xmlgraphics.image.loader.cache.ImageCache.needImageInfo(ImageCache.java:128)
        at org.apache.xmlgraphics.image.loader.ImageManager.getImageInfo(ImageManager.java:122)
        at org.apache.fop.fo.properties.CommonBorderPaddingBackground.getInstance(CommonBorderPaddingBackground.java:381)
        at org.apache.fop.fo.PropertyList.getBorderPaddingBackgroundProps(PropertyList.java:577)
        at org.apache.fop.fo.pagination.Region.bind(Region.java:66)
        at org.apache.fop.fo.pagination.RegionBody.bind(RegionBody.java:58)
        at org.apache.fop.fo.FObj.processNode(FObj.java:124)
        at org.apache.fop.fo.FOTreeBuilder$MainFOHandler.startElement(FOTreeBuilder.java:280)
        at org.apache.fop.fo.FOTreeBuilder.startElement(FOTreeBuilder.java:175)
        at org.apache.xml.serializer.ToXMLSAXHandler.closeStartTag(ToXMLSAXHandler.java:204)
        at org.apache.xml.serializer.ToSAXHandler.flushPending(ToSAXHandler.java:277)
        at org.apache.xml.serializer.ToXMLSAXHandler.endElement(ToXMLSAXHandler.java:243)
        at org.apache.xalan.templates.ElemLiteralResult.execute(ElemLiteralResult.java:1399)
        at org.apache.xalan.transformer.TransformerImpl.executeChildTemplates(TransformerImpl.java:2411)
        ... 32 more
Caused by: java.lang.reflect.InvocationTargetException
        at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
        at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.base/java.lang.reflect.Method.invoke(Method.java:566)
        at org.apache.xmlgraphics.image.loader.impl.AbstractImageSessionContext$ObservingImageInputStreamInvocationHandler.invoke(AbstractImageSessionContext.java:219)
        ... 49 more
Caused by: java.io.EOFException
        at java.desktop/javax.imageio.stream.ImageInputStreamImpl.readInt(ImageInputStreamImpl.java:251)
        at java.desktop/javax.imageio.stream.ImageInputStreamImpl.readUnsignedInt(ImageInputStreamImpl.java:266)
        ... 54 more

So in essence PDFs can't be generated.

Documentation builds for creating PDF fail

It's currently not possible to build the PDF of the user documentation:

error	30-Mar-2018 15:12:36	SEVERE: Exception
error	30-Mar-2018 15:12:36	org.apache.fop.apps.FOPException: The markup declarations contained or pointed to by the document type declaration must be well-formed.
error	30-Mar-2018 15:12:36	javax.xml.transform.TransformerException: The markup declarations contained or pointed to by the document type declaration must be well-formed.
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.InputHandler.transformTo(InputHandler.java:303)
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.InputHandler.renderTo(InputHandler.java:130)
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.Main.startFOP(Main.java:177)
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.Main.main(Main.java:208)
error	30-Mar-2018 15:12:36	Caused by: javax.xml.transform.TransformerException: The markup declarations contained or pointed to by the document type declaration must be well-formed.
error	30-Mar-2018 15:12:36		at org.apache.xalan.transformer.TransformerImpl.fatalError(TransformerImpl.java:780)
error	30-Mar-2018 15:12:36		at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:756)
error	30-Mar-2018 15:12:36		at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:1284)
error	30-Mar-2018 15:12:36		at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:1262)
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.InputHandler.transformTo(InputHandler.java:300)
error	30-Mar-2018 15:12:36		... 3 more
error	30-Mar-2018 15:12:36	
error	30-Mar-2018 15:12:36	---------
error	30-Mar-2018 15:12:36	
error	30-Mar-2018 15:12:36	; SystemID: http://www.docbook.org/xml/4.4/docbookx.dtd; Line#: 1; Column#: 1
error	30-Mar-2018 15:12:36	javax.xml.transform.TransformerException: The markup declarations contained or pointed to by the document type declaration must be well-formed.
error	30-Mar-2018 15:12:36		at org.apache.xalan.transformer.TransformerImpl.fatalError(TransformerImpl.java:780)
error	30-Mar-2018 15:12:36		at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:756)
error	30-Mar-2018 15:12:36		at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:1284)
error	30-Mar-2018 15:12:36		at org.apache.xalan.transformer.TransformerImpl.transform(TransformerImpl.java:1262)
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.InputHandler.transformTo(InputHandler.java:300)
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.InputHandler.renderTo(InputHandler.java:130)
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.Main.startFOP(Main.java:177)
error	30-Mar-2018 15:12:36		at org.apache.fop.cli.Main.main(Main.java:208)

This seems to be caused by docbook now requiring a https link: https://www.docbook.org/xml/4.4/docbookx.dtd

Git Readme

Adding a readme for the git repository to explain what its for. Similar to those for other phpBB sub-projects.

Update scripts for creating 3.3.x documentation

Todo:

• Update bamboo config
• Update scripts for developer documentation
• Update scripts for user documentation
• Test correct creation of scripts
• Update website related scripts (should reference the correct branch for 3.3.x etc.)
• Update Area51 to contain 3.3.x coding guidelines instead of master ones for 3.3.x (!!)
• Make sure link to styles demo for 3.3.x works (@michaelcullum ?)
• Check links to 3.3.x pages on area51
• Add +x to build_code_changes_33.sh
• Use different stylesheet for 3.3.x (?)

Document the usage of the new permission tool "role_exists"

Working example

namespace phpbbstudio\mnote\migrations;

class install_permissions extends \phpbb\db\migration\migration
{
	public function effectively_installed()
	{
		$sql = 'SELECT * FROM ' . $this->table_prefix . "acl_options
			WHERE auth_option = '" . $this->db->sql_escape('a_phpbbstudio_mnote') . "'";
		$result = $this->db->sql_query_limit($sql, 1);
		$row = $this->db->sql_fetchrow($result);
		$this->db->sql_freeresult($result);

		return $row !== false;
	}

	public static function depends_on()
	{
		return ['\phpbb\db\migration\data\v33x\v334'];
	}

	public function update_data()
	{
		return [
			// Add permissions not set
			['permission.add', ['a_phpbbstudio_mnote']],
			['permission.add', ['m_phpbbstudio_mnote']],

			// Set permission on role if it exists
			['if', [
				['permission.role_exists', ['ROLE_ADMIN_FULL']],
				['permission.permission_set', ['ROLE_ADMIN_FULL', 'a_phpbbstudio_mnote']],
			]],

			['if', [
				['permission.role_exists', ['ROLE_MOD_FULL']],
				['permission.permission_set', ['ROLE_MOD_FULL', 'm_phpbbstudio_mnote']],
			]],
		];
	}
}

Extensions tutorial references non-existent "continuous integration with travis ci"

Where is the third area in "Forum moderation"?

Hi guys!

In this line it mentioned 3 areas in the Forum moderation screen.

For the two first (1 listbox and 1 dropdown menu) no problem...
But for the last, which refer to Finally, the third area's selection will only affect exactly this forum.
Where is this area?

Regards.

Merge Translation Policies into Docu

for phpBB 3.1 and 3.2

Means:

• https://github.com/phpbb/phpbb-translation-policies/blob/3.2.x/guidelines.md
• https://github.com/phpbb/phpbb-translation-policies/blob/3.2.x/validation.md
  and for 3.1.x:
• https://github.com/phpbb/phpbb-translation-policies/blob/3.1.x/guidelines.md
• https://github.com/phpbb/phpbb-translation-policies/blob/3.1.x/validation.md

Into these pages: https://area51.phpbb.com/docs/dev/32x/language/index.html / https://area51.phpbb.com/docs/dev/31x/language/index.html

Because it is already in part available: https://area51.phpbb.com/docs/dev/32x/language/validation.html and we like to save some maintenance time.

Request, config etc. classes documentation

I think we need to document somewhere about the request class in particular (and how it prevents security issues) but it would be good to also talk about other commonly used services like the config class.

INSTALL_CONGRATS_EXPLAIN and OVERVIEW_BODY is not in language pack

I don't see INSTALL_CONGRATS_EXPLAIN and OVERVIEW_BODY mentioned on https://github.com/phpbb/documentation/blob/master/development/language/validation.rst#html in language pack 3.2.2.

Maybe they are so new they are not in 3.2.2 or maybe they have been removed.

Update policy for language validation for Rhea/3.2.0

E.g.:

• new files
• viglink translation

Sphinx extension error: cannot import name 'upper'

Hi guys!

Following comments in the #56, the following error remains.

Extension error:
Could not import extension sensio.sphinx.bestpractice (exception: cannot import name 'upper')

Any ideas to solve it?

typo in language usage

When using language extries in the JavaScript context with the new twig syntax, the following methods are possible:

should be entries instead of extries

<languagename>_<version> folder inside zip file

https://github.com/phpbb/documentation/blob/master/development/language/validation.rst says:

The submitted <languagename>_<version>.zip must contain a <languagename>_<version> folder. The files from above should be placed in this folder.

But that dont sound smart that the zip file should contain a folder by the same name as the zip file. When you extract it you would get:

british_english_3_2_2/british_english_3_2_2/language/
british_english_3_2_2/british_english_3_2_2/ext/
british_english_3_2_2/british_english_3_2_2/styles/

This would be smarter:

british_english_3_2_2/language/
british_english_3_2_2/ext/
british_english_3_2_2/styles/

Also it says "The files from above" but there are none above.

Document use of mentions feature

The newly added mentions feature needs to be properly documented, e.g. how to best use it for users and/or groups.

Add instructions for "how to generate development documentation"

Hi guys!

I tried to use your script to generate the development documentation.

After installing Python and Sphinx, the script make.bat returns the following error.

Extension error:
Could not import extension sensio.sphinx.refinclude (exception: No module named 'sensio')

After some research, I found how to install Sensio extensions. but it was not easy when we don't know where and what to look for.

Maybe It will be usefull to add something about this in the readme.md

language/usage.rst needs update for 3.2

The logic was moved to phpbb\language\language instead of phpbb\user

@MateBartus did anything else change? https://github.com/phpbb/documentation/pull/20/files#diff-095e33362bf3f1179099f1e83357dfde

Add events list to documentation

Document use of rebase for updating branchs / fixing merge conflicts

Tables broken by new responsive CSS

documentation/development/_static/css/phpbb.css

Line 14 in 91c02a3

float: left;

This float left is breaking content that comes after a table in the docs.

Can we please use something other than float?

Resolve rst formatting errors in master branch

Some files have invalid code-blocks or other formatting issues and inconsistencies that result in warnings while creating the documentation for the master branch.

Unknown target name: "2.0" when building documentation on area51

sphinx-versioning build -w 3.2.x -w 3.3.x -w master development
documentation/development/language/guidelines.rst:17: WARNING: Unknown target name: "2.0".

Update scripts for creating 3.2.x documentation

Todo:

• Update bamboo config
• Update scripts for developer documentation
• Update scripts for user documentation
• Test correct creation of scripts
• Update website related scripts (should reference the correct branch for 3.2.x etc.)
• Update Area51 to contain 3.2.x coding guidelines instead of master ones for 3.2.x (!!)
• Make sure link to styles demo for 3.2.x works (@michaelcullum ?)
• Check links to 3.2.x pages on area51
• Use different stylesheet for 3.2.x (?)

config.php in 3.1 update instructions

It should inform the user to delete the blank config.php in the 3.1 package before uploading as otherwise it might over-write their existing config.php

https://www.phpbb.com/community/viewtopic.php?p=13878596#p13878596

Move tutorials from wiki to documentation

Some tutorials should be moved from the wiki:

• https://wiki.phpbb.com/Tutorial.Parsing_text
• https://wiki.phpbb.com/Tutorial.Template_syntax

frontpage link

on the frontpage of this repository you mention

"Documentation for board visitors, moderators and administrators. Can be seen online here
https://github.com/phpbb/documentation"

Please can you add a link to the online developer documentation aswell.

Backport github actions to 3.2.x branch

Add CLI install/update example to docu

https://github.com/phpbb/documentation/blob/3.2.x/development/cli/getting_started.rst

How do use the config.yml and stuff

Database type-map is missing

Useful for extension writers.

https://gist.github.com/marc1706/6886cedb8aa415497a5e31b4b35ebb38

Add new lang system replacement for LA_KEY

@VSEphpbb from #38 (comment)

Add a bit about the new lang system replacement for LA_KEY by doing {{ lang('KEY')|e('js') }}
Other possible options:
{{ lang('KEY')|escape('js') }}
{{ lang('KEY')|e('addslashes') }}
{{ lang('KEY')|escape('addslashes') }}

addslashes is our own custom func that simply addslashes the string.
js is a native twig function that escapes a string for the JavaScript context.