diff --git a/development/Makefile b/development/Makefile index 93fbe0f8..c492aab5 100644 --- a/development/Makefile +++ b/development/Makefile @@ -9,7 +9,7 @@ BUILDDIR = _build # User-friendly check for sphinx-build ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from https://sphinx-doc.org/) endif # Internal variables. diff --git a/development/cli/getting_started.rst b/development/cli/getting_started.rst index 871b3995..a55a8cdb 100644 --- a/development/cli/getting_started.rst +++ b/development/cli/getting_started.rst @@ -4,7 +4,7 @@ Getting started The command line interface (CLI) is a useful utility for phpBB administrators who have access to a shell (or SSH) on the server they run phpBB on, as well as for extension developers. It provides CLI commands for managing config values, extensions, running database migration, purging the cache, and more. -Most operating systems ship with a built in command line application. For Mac OS and Ubuntu it is called "Terminal" and for Windows it is called "Command Prompt". Third party software such as `PuTTY `_ and `iTerm `_ can also be used. +Most operating systems ship with a built in command line application. For Mac OS and Ubuntu it is called "Terminal" and for Windows it is called "Command Prompt". Third party software such as `PuTTY `_ and `iTerm `_ can also be used. To use phpBB's CLI on a web server, you will need SSH access to your web server. You can find out from your web hosting company if they offer SSH access and how to log into your web server from the CLI. @@ -61,7 +61,7 @@ General options Common options that can be used with any of phpBB's CLI commands. .. csv-table:: - :header: "Option", "Usage" + :header: Option, Usage :delim: | ``--help, -h`` | Display a help message @@ -111,7 +111,7 @@ The phpBB CLI installer uses a YAML file populated with the data needed to confi server: cookie_secure: false - server_protocol: http:// + server_protocol: https:// force_server_vars: false server_name: localhost server_port: 80 diff --git a/development/conf.py b/development/conf.py index a976e334..2fd25351 100644 --- a/development/conf.py +++ b/development/conf.py @@ -35,7 +35,8 @@ 'sensio.sphinx.bestpractice', 'sphinxcontrib.phpdomain', 'sphinx_multiversion', - 'sphinx_rtd_theme' + 'sphinx_rtd_theme', + 'sphinx.ext.autosectionlabel' ] # Add any paths that contain templates here, relative to this directory. @@ -101,6 +102,8 @@ # If true, keep warnings as "system message" paragraphs in the built documents. #keep_warnings = False +autosectionlabel_prefix_document = True + # Options for sphinx_multiversion smv_tag_whitelist = 'None' smv_branch_whitelist = r'^(3.2.x|3.3.x|master)$' diff --git a/development/db/dbal.rst b/development/db/dbal.rst index 63caf08e..613fde5c 100644 --- a/development/db/dbal.rst +++ b/development/db/dbal.rst @@ -2,7 +2,7 @@ Database Abstraction Layer ========================== -phpBB uses a **D**\ ata\ **B**\ ase **A**\ bstraction **L**\ ayer to access the database instead of directly calling e.g. `mysql_query `_ functions. +phpBB uses a **D**\ ata\ **B**\ ase **A**\ bstraction **L**\ ayer to access the database instead of directly calling e.g. `mysql_query `_ functions. You usually access the :abbr:`DBAL (Database Abstraction Layer)` using the global variable ``$db``. This variable is included from :class:`common.php` through :class:`includes/compatibility_globals.php`: @@ -49,11 +49,10 @@ Example using :class:`config.php`: // We do not need this any longer, unset for safety purposes unset($dbpasswd); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: # Host # The host of the database. |br| When using config.php you should use $dbhost instead. @@ -115,10 +114,10 @@ Example: // Now run the query... $result = $db->sql_query($sql); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: # Query Type # Type of query which needs to be created (SELECT, SELECT_DISTINCT) @@ -155,10 +154,10 @@ Example: $sql = 'INSERT INTO ' . USERS_TABLE . ' ' . $db->sql_build_array('INSERT', $data); $db->sql_query($sql); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: # Query Type # Type of query which needs to be created (UPDATE, INSERT, INSERT_SELECT or SELECT) @@ -179,10 +178,10 @@ Example: WHERE ' . $db->sql_in_set('user_id', $sql_in); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: | Column | Name of the sql column that shall be compared @@ -204,10 +203,10 @@ Example: WHERE post_id = ' . (int) $integer . " AND post_text = '" . $db->sql_escape($string) . "'"; -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: | String | The string that needs to be escaped. @@ -220,10 +219,10 @@ Defined in the base driver (``_sql_like_expression`` is defined in the specific The ``sql_not_like_expression`` is identical to ``sql_like_expression`` apart from that it builds a NOT LIKE statement. -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: | Expression | The expression to use. Every wildcard is escaped, except $db->get_any_char() and $db->get_one_char() @@ -266,10 +265,10 @@ Example: WHERE ' . $db->sql_lower_text('log_data') . ' ' . $like; $result = $db->sql_query_limit($sql, 10); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: | Column name | The column name to LOWER the value for. @@ -295,10 +294,10 @@ Example: $result = $db->sql_query($sql); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: | Query | Contains the SQL query which shall be executed @@ -320,10 +319,10 @@ Example: $result = $db->sql_query_limit($sql, $config['topics_per_page'], $start); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: | Query | Contains the SQL query which shall be executed. @@ -356,10 +355,10 @@ Example: $db->sql_multi_insert(USER_GROUP_TABLE, $sql_ary); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: | Table name | Table name to run the statements on. @@ -424,10 +423,10 @@ Example: $total_posts = (int) $db->sql_fetchfield('num_posts'); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters + .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: # Field # Name of the field that needs to be fetched. @@ -438,11 +437,10 @@ sql_fetchrowset --------------- Returns an array with the result of using the ``sql_fetchrow`` method on every row. Defined in the base driver. +.. rubric:: Parameters -Parameters -^^^^^^^^^^ .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: # Result (Optional) # The result that is being evaluated. |br| This result comes from a call to the sql_query method. |br| If left empty the last result will be called. @@ -476,11 +474,10 @@ Example with a while-loop: $config[$row['config_name']] = $row['config_value']; } +.. rubric:: Parameters -Parameters -^^^^^^^^^^ .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: # Result (Optional) # The result that is being evaluated. |br| The result comes from a call to the sql_query method. |br| If left empty the last result will be called. @@ -489,11 +486,10 @@ sql_rowseek ----------- Seeks to given row number. The row number is zero-based. Defined in the specific drivers. +.. rubric:: Parameters -Parameters -^^^^^^^^^^ .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: # Row number # The number of the row which needs to be found (zero-based). @@ -519,11 +515,10 @@ Example: // We don't need to do anything with our query anymore, so lets set it free $db->sql_freeresult($result); +.. rubric:: Parameters -Parameters -^^^^^^^^^^ .. csv-table:: - :header: "Parameter", "Usage" + :header: Parameter, Usage :delim: # Result (Optional) # The result that is being evaluated. |br| This result comes from a call to the sql_query method. |br| If left empty the last result will be called. diff --git a/development/development/css/css_guidelines.rst b/development/development/css/css_guidelines.rst index b912b60a..def8eae9 100644 --- a/development/development/css/css_guidelines.rst +++ b/development/development/css/css_guidelines.rst @@ -323,12 +323,12 @@ Our project makes use of several tools to lint and keep code up to standards. .. note:: This is used to help automatically re-format your code on-the-fly to meet standards during the build process via ``gulp`` as well as on save in your editor. -.. note:: Our editors of choice are `PhpStorm`_ & `ATOM`_ which provide useful plugins to make use of these tools. Check out the `Editor Setup`_ section of the docs for more information +.. note:: Our editors of choice are `PhpStorm`_ & `Visual Studio Code`_ which provide useful plugins to make use of these tools. Check out the `Editor Setup`_ section of the docs for more information -.. _stylelint.io: http://www.stylelint.io +.. _stylelint.io: https://stylelint.io/ .. _postcss-sorting: https://github.com/hudochenkov/postcss-sorting .. _postcss-pxtorem: https://github.com/cuth/postcss-pxtorem .. _stylefmt: https://github.com/morishitter/stylefmt .. _PhpStorm: https://www.jetbrains.com/phpstorm/ -.. _ATOM: http://www.atom.io +.. _Visual Studio Code: https://code.visualstudio.com/ .. _Editor Setup: /editor-setup diff --git a/development/development/css/css_selectors.rst b/development/development/css/css_selectors.rst index 7a63efe4..ba411d14 100644 --- a/development/development/css/css_selectors.rst +++ b/development/development/css/css_selectors.rst @@ -248,9 +248,9 @@ Further Reading - `Writing efficient CSS selectors`_ -.. _Shoot to kill; CSS selector intent: http://csswizardry.com/2012/07/shoot-to-kill-css-selector-intent/ -.. _‘Scope’ in CSS: http://csswizardry.com/2013/05/scope-in-css/ -.. _Keep your CSS selectors short: http://csswizardry.com/2012/05/keep-your-css-selectors-short/ -.. _About HTML semantics and front-end architecture: http://nicolasgallagher.com/about-html-semantics-front-end-architecture/ -.. _Naming UI components in OOCSS: http://csswizardry.com/2014/03/naming-ui-components-in-oocss/ -.. _Writing efficient CSS selectors: http://csswizardry.com/2011/09/writing-efficient-css-selectors/ +.. _Shoot to kill; CSS selector intent: https://csswizardry.com/2012/07/shoot-to-kill-css-selector-intent/ +.. _‘Scope’ in CSS: https://csswizardry.com/2013/05/scope-in-css/ +.. _Keep your CSS selectors short: https://csswizardry.com/2012/05/keep-your-css-selectors-short/ +.. _About HTML semantics and front-end architecture: https://nicolasgallagher.com/about-html-semantics-front-end-architecture/ +.. _Naming UI components in OOCSS: https://csswizardry.com/2014/03/naming-ui-components-in-oocss/ +.. _Writing efficient CSS selectors: https://csswizardry.com/2011/09/writing-efficient-css-selectors/ diff --git a/development/development/css/css_specificity.rst b/development/development/css/css_specificity.rst index 805ac3e4..6abe3100 100644 --- a/development/development/css/css_specificity.rst +++ b/development/development/css/css_specificity.rst @@ -169,10 +169,9 @@ This goes some way to providing our CSS with scope and encapsulation, but does s Now we have better scoped CSS with minimal specificity—the best of both worlds. -Further Reading -^^^^^^^^^^^^^^^ +.. seealso:: -- `‘Scope’ in CSS`_ + - `‘Scope’ in CSS`_ ``!important`` ~~~~~~~~~~~~~~ @@ -272,12 +271,11 @@ Here we are selecting based on an attribute rather than an ID, and attribute sel Do keep in mind that these are hacks, and should not be used unless you have no better alternative. -Further Reading -^^^^^^^^^^^^^^^ +.. seealso:: -- `Hacks for dealing with specificity`_ + - `Hacks for dealing with specificity`_ -.. _jsfiddle.net/0yb7rque: http://jsfiddle.net/csswizardry/0yb7rque/ -.. _known bug: https://twitter.com/codepo8/status/505004085398224896 -.. _‘Scope’ in CSS: http://csswizardry.com/2013/05/scope-in-css/ -.. _Hacks for dealing with specificity: http://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/ + .. _jsfiddle.net/0yb7rque: https://jsfiddle.net/csswizardry/0yb7rque/ + .. _known bug: https://web.archive.org/web/20200512073642/https://twitter.com/codepo8/status/505004085398224896 + .. _‘Scope’ in CSS: https://csswizardry.com/2013/05/scope-in-css/ + .. _Hacks for dealing with specificity: https://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/ diff --git a/development/development/css/css_standards.rst b/development/development/css/css_standards.rst index cc417023..9b45f66e 100644 --- a/development/development/css/css_standards.rst +++ b/development/development/css/css_standards.rst @@ -255,4 +255,4 @@ Preprocessor Comments With most—if not all—preprocessors, we have the option to write comments that will not get compiled out into our resulting CSS file. As a rule, use these comments to speed up and prevent errors in the minification step. -.. _EditorConfig: http://editorconfig.org/ +.. _EditorConfig: https://editorconfig.org/ diff --git a/development/development/git.rst b/development/development/git.rst index 70ea3a5d..afcb129d 100644 --- a/development/development/git.rst +++ b/development/development/git.rst @@ -36,12 +36,12 @@ See `Set Up Git `_ for help on sett Branches ^^^^^^^^ -- `master `_ - The latest unstable development version with new features etc. -- `3.3.x `_ - Development branch of the 3.3 line. Bug fixes and minor feature changes are applied here. -- `3.2.x `_ - Development branch of the 3.2 line. Bug fixes and minor feature changes are applied here. -- `3.1.x `_ - Development branch of the stable 3.1 line. phpBB 3.1 has reached its End of Life and is therefore no longer maintained. -- `3.0.x `_ - Development branch of the stable 3.0 line. phpBB 3.0 has reached its End of Life and is therefore no longer maintained. -- `2.0.x `_ - Development branch of the deprecated 2.0 line. +- `master `_ - The latest unstable development version with new features etc. +- `3.3.x `_ - Development branch of the 3.3 line. Bug fixes and minor feature changes are applied here. +- `3.2.x `_ - Development branch of the 3.2 line. Bug fixes and minor feature changes are applied here. +- `3.1.x `_ - Development branch of the stable 3.1 line. phpBB 3.1 has reached its End of Life and is therefore no longer maintained. +- `3.0.x `_ - Development branch of the stable 3.0 line. phpBB 3.0 has reached its End of Life and is therefore no longer maintained. +- `2.0.x `_ - Development branch of the deprecated 2.0 line. Tags ^^^^ @@ -138,8 +138,10 @@ Review `Forking and Cloning`_. Configuration ------------- -Git -^^^ + +.. rubric:: Git + :heading-level: 4 + Add your Username to Git on your system: :: @@ -162,8 +164,9 @@ Add the upstream remote (you can change 'upstream' to whatever you like): The *upstream* remote url **is** the phpBB GitHub repo. Your cloned fork of the phpBB GitHub repo will, by default, use the *origin* remote url. -Composer -^^^^^^^^ +.. rubric:: Composer + :heading-level: 4 + To be able to run an installation from the repo (and not from a pre-built package) you need to run the following shell commands to install phpBB's dependencies. @@ -179,8 +182,9 @@ Ignore any *abandoned package* warnings. `Introduction - Composer `_ for further information. -Hooks -^^^^^ +.. rubric:: Hooks + :heading-level: 4 + The phpBB repository contains some client-side hooks that can aid development. They are located in the ``git-tools/hooks`` directory. These hooks do things like preparing and validating commit messages, checking for PHP syntax errors. There is a script to set @@ -196,8 +200,8 @@ and re-run the install command. Once these hooks are installed, you simply need to run ``git commit`` to commit new changes. Depending on your environment, you will be prompted to add a commit message -using `Vim `__ or -`Emacs `__. The +using `Vim `__ or +`Emacs `__. The hooks will take care of formatting your entire commit message in the required format (see `Commit Messages`_). @@ -474,7 +478,7 @@ The difference is that, if you don't use the global option, any new repository y create will not have this option properly set for phpBB development which may cause errors to occur while committing or when executing any php file. -**For those who use** `TortoiseGit `_ +**For those who use** `TortoiseGit `_ **(and used to work with TortoiseSVN):** When you use TortoiseGit the first time, you need to disable ``AutoCrlf`` in @@ -489,9 +493,6 @@ can correctly merge branches (*you need to do that on every git repository you h Create your own SSH key ----------------------- -.. seealso:: - - http://help.github.com/win-set-up-git/ TortoiseGit will automatically use the SSH key @@ -525,16 +526,11 @@ Commands Further reading =============== -* `Git Community Book (online) `__ -* `Pro Git Book (online) `__ -* `GitCasts `__ -* `Getting Git `__ -* `RailsConf 2008 `__ Git Talk by Scott Chacon -* `Official Git Documentation `__ -* `Git Crash Course for SVN users `__ -* `GitHub Guides `__ -* `Learn.GitHub `__ -* `Git for the lazy `__ +* `Git Community Book (online) `__ +* `Official Git Documentation `__ +* `GitHub Git Guide `__ +* `Git and GitHub learning resources `__ +* `Git for the lazy `__ External links ============== @@ -545,4 +541,4 @@ External links * `phpBB Extensions GitHub account `__ * `TortoiseGit `__ - A windows Git client based on TortoiseSVN * `TortoiseGit on github `__ - GitHub repository -* `Open Source Contribution Etiquette `__ +* `Open Source Contribution Etiquette `__ diff --git a/development/development/php/templating.rst b/development/development/php/templating.rst index 49b78025..fc617ed9 100644 --- a/development/development/php/templating.rst +++ b/development/development/php/templating.rst @@ -7,422 +7,396 @@ File naming +++++++++++ -Firstly templates now take the suffix ".html" rather than ".tpl". This was done simply to make the lives of some people easier wrt syntax highlighting, etc. +Templates **SHALL** use the suffix ``.html`` and **MAY** use the ``.twig`` suffix for non-HTML files interpreted by twig or twig macros. Other suffixes like ``.tpl`` or ``.html5`` **SHALL NOT** be used. Variables +++++++++ -All template variables should be named appropriately (using underscores for spaces), language entries should be prefixed with ``L_``, system data with ``S_``, urls with ``U_``, javascript urls with ``UA_``, language to be put in javascript statements with ``LA_``, all other variables should be presented 'as is'. +All template variables **SHALL** be named appropriately using underscores for spaces (`snake_case`). -``L_*`` template variables are automatically mapped to the corresponding language entry if the code does not set (and therefore overwrite) this variable specifically and if the language entry exists. For example ``{L_USERNAME}`` maps to ``$user->lang['USERNAME']``. The ``LA_*`` template variables are handled within the same way, but properly escaped so they can be put in javascript code. This should reduce the need to assign loads of new language variables in MODifications. +Previous versions of phpBB used prefixes for special handling of variables, e.g. ``L_`` for language variables, ``S_`` for system variables, etc. This has been deprecated in phpBB 4.0 and will be dropped in a later version of phpBB. +``UA_`` and ``LA`` prefixes resulted in special inside JavaScript. + +Appropriate escaping needs to be done in template files using the provided escape functions. Variables can be escaped inside JavaScript using the standard ``e('js')`` twig function: + +.. code-block:: js + + {{ username|e('js') }} + +This will escape the variable for JavaScript usage. A helper function for language variables inside JavaScript without the need for ``e('js')`` has been introduced: + +.. code-block:: js + + {{ lang_js('USERNAME') }} + +The ``L_`` prefix or ``LA`` prefix is not needed anymore. The function will automatically escape the variable for JavaScript usage. + +.. warning:: + + Support for the ``L_`` prefix and ``LA`` prefix have been deprecated in phpBB 4.0 will be removed in a later version of phpBB. Please use the new functions instead. + +.. seealso:: + + - `escape - Filters - Documentation `_ + - `Twig for Template Designers - Variables `_ Blocks/Loops ++++++++++++ -The basic block level loop remains and takes the form: +The basic block level loop **SHALL** use the twig syntax as follows: -.. code:: html +.. code-block:: html - - markup, {loopname.X_YYYYY}, etc. - + {% for item in loopname %} + markup, {{ item.X_YYYYY }}, etc. + {% endfor %} -A bit later loops will be explained further. To not irritate you we will explain conditionals as well as other statements first. +Further instructions on how to use loops will follow in section `Extended syntax for Blocks/Loops`_. -Including files -+++++++++++++++ +.. warning:: -Something that existed in 2.0.x which no longer exists in 3.x is the ability to assign a template to a variable. This was used (for example) to output the jumpbox. Instead (perhaps better, perhaps not but certainly more flexible) we now have INCLUDE. This takes the simple form: + The old style of loops using ```` and ```` is deprecated in phpBB 4.0 and will be removed in a later version of phpBB. Please use the new twig syntax instead. -.. code:: html + .. code:: html - + + markup, {loopname.X_YYYYY}, etc. + -You will note in the 3.x templates the major sources start with or , etc. In 2.0.x control of "which" header to use was defined entirely within the code. In 3.x the template designer can output what they like. Note that you can introduce new templates (i.e. other than those in the default set) using this system and include them as you wish ... perhaps useful for a common "menu" bar or some such. No need to modify loads of files as with 2.0.x. +.. seealso:: -Added in **3.0.6** is the ability to include a file using a template variable to specify the file, this functionality only works for root variables (i.e. not block variables). + - `for - Tags - Twig Documentation `_ -.. code:: html +Including files ++++++++++++++++ - +In phpBB 3.1 and later, template inclusion **SHALL** be handled using Twig syntax. To include another template file, use the following Twig statement: -Template defined variables can also be utilised. +.. code-block:: twig -.. code:: html + {% include 'filename' %} - - +For example, to include the overall header or a custom menu bar: -PHP -+++ +.. code-block:: twig -A contentious decision has seen the ability to include PHP within the template introduced. This is achieved by enclosing the PHP within relevant tags: + {% include 'overall_header.html' %} + {% include 'simple_header.html' %} -.. code:: html +You can also include a template file using a variable: - - echo "hello!"; - +.. code-block:: twig -You may also include PHP from an external file using: + {% include FILE_VAR %} -.. code:: html +Template-defined variables can be used as well: + +.. code-block:: twig - + {% set SOME_VAR = 'my_file.html' %} + {% include SOME_VAR %} -it will be included and executed inline. +.. seealso:: -.. note:: it is very much encouraged that template designers do not include PHP. The ability to include raw PHP was introduced primarily to allow end users to include banner code, etc. without modifying multiple files (as with 2.0.x). It was not intended for general use ... hence htps://www.phpbb.com will **not** make available template sets which include PHP. And by default templates will have PHP disabled (the admin will need to specifically activate PHP for a template). + - `Twig for Template Designers - Including other templates `_ Conditionals/Control structures +++++++++++++++++++++++++++++++ -The most significant addition to 3.x are conditions or control structures, "if something then do this else do that". The system deployed is very similar to Smarty. This may confuse some people at first but it offers great potential and great flexibility with a little imagination. In their most simple form these constructs take the form: +Starting with phpBB 3.1, the template engine uses Twig for control structures and conditionals. This allows for a more powerful and flexible way to handle logic in templates compared to the previous phpBB template syntax. +All conditionals **SHALL** use the Twig syntax starting with phpBB 4.0. -.. code:: html +.. warning:: - - markup - + The old style of conditionals using ```` and ```` is deprecated in phpBB 4.0 and will be removed in a later version of phpBB. Please use the new Twig syntax instead. -expr can take many forms, for example: + .. code:: html -.. code:: html + + markup + - - markup - +Twig offers a clear and flexible way to handle logic in templates. The basic form of a conditional in Twig is: -This will output the markup if the S_ROW_COUNT variable in the current iteration of loop is an even value (i.e. the expr is TRUE). You can use various comparison methods (standard as well as equivalent textual versions noted in square brackets) including (``not, or, and, eq, neq, is`` should be used if possible for better readability): +.. code-block:: twig -.. code:: php + {% if expr %} + markup + {% endif %} - == [eq] - != [neq, ne] - <> (same as !=) - !== (not equivalent in value and type) - === (equivalent in value and type) - > [gt] - < [lt] - >= [gte] - <= [lte] - && [and] - || [or] - % [mod] - ! [not] - + - - - * - / - , - << (bitwise shift left) - >> (bitwise shift right) - | (bitwise or) - ^ (bitwise xor) - & (bitwise and) - ~ (bitwise not) - is (can be used to join comparison operations) - -Basic parenthesis can also be used to enforce good old BODMAS rules. Additionally some basic comparison types are defined: - -.. code:: text - - even - odd - div - -Beyond the simple use of IF you can also do a sequence of comparisons using the following: +The `expr` can take many forms. For example, to check if the current loop iteration is even: -.. code:: html +.. code-block:: twig - - markup - - markup - . - . - . - - markup - - markup - + {% if loop.index is even %} + markup + {% endif %} -Each statement will be tested in turn and the relevant output generated when a match (if a match) is found. It is not necessary to always use ELSEIF, ELSE can be used alone to match "everything else". +This will output the markup if the current loop index is even. Twig supports a wide range of comparison and logical operators, including: -So what can you do with all this? Well take for example the colouration of rows in viewforum. In 2.0.x row colours were predefined within the source as either row color1, row color2 or row class1, row class2. In 3.x this is moved to the template, it may look a little daunting at first but remember control flows from top to bottom and it's not too difficult: +.. code-block:: text -.. code:: html + ==, !=, ==, >, <, >=, <=, and, or, not, in, is, matches, starts with, ends with, contains, has some, has every - - - - - - - - -
HELLO!
+You can also use parentheses to group expressions and enforce operator precedence. -This will cause the row cell to be output using class row1 when the row count is even, and class row2 otherwise. The S_ROW_COUNT parameter gets assigned to loops by default. Another example would be the following: +Twig provides special tests for common checks: -.. code:: html +.. code-block:: text - - - - - - - - - - - - -
hello!
+ even, odd, divisible by, defined, iterable, empty, null, same as -This will output the row cell in purple for the first two rows, blue for rows 2 to 5, green for rows 5 to 10 and red for remainder. So, you could produce a "nice" gradient effect, for example. +For example: -What else can you do? Well, you could use IF to do common checks on for example the login state of a user: +.. code-block:: twig -.. code:: html + {% if loop.index is divisible by(3) %} + markup + {% endif %} - - markup - +Twig also supports `if`/`elseif`/`else` chains: -This replaces the existing (fudged) method in 2.0.x using a zero length array and BEGIN/END. +.. code-block:: twig -Extended syntax for Blocks/Loops -++++++++++++++++++++++++++++++++ + {% if expr1 %} + markup + {% elseif expr2 %} + markup + {% else %} + markup + {% endif %} -Back to our loops - they had been extended with the following additions. Firstly you can set the start and end points of the loop. For example: +Each condition is checked in order, and the first matching block is rendered. -.. code:: html +Here are some practical examples: - - markup - +**Row coloration in a table:** -Will start the loop on the third entry (note that indexes start at zero). Extensions of this are: +.. code-block:: twig -``loopname(2)``: Will start the loop on the 3rd entry -``loopname(-2)``: Will start the loop two entries from the end -``loopname(3,4)``: Will start the loop on the fourth entry and end it on the fifth -``loopname(3,-4)``: Will start the loop on the fourth entry and end it four from last + + {% for row in rows %} + {% if loop.index is even %} + + {% else %} + + {% endif %} + + + {% endfor %} +
HELLO!
-A further extension to begin is ``BEGINELSE``: +This will use `row1` for even rows and `row2` for odd rows. -.. code:: html +**Gradient effect based on row count:** - - markup - - markup - +.. code-block:: twig -This will cause the markup between ``BEGINELSE`` and ``END`` to be output if the loop contains no values. This is useful for forums with no topics (for example) ... in some ways it replaces "bits of" the existing `switch_` type control (the rest being replaced by conditionals). + + {% for row in rows %} + {% if loop.index > 10 %} + + {% elseif loop.index > 5 %} + + {% elseif loop.index > 2 %} + + {% else %} + + {% endif %} + + + {% endfor %} +
hello!
-Another way of checking if a loop contains values is by prefixing the loops name with a dot: +This will output different background colors depending on the row index. -.. code:: html +**Checking user login state:** - - - markup - - - markup - +.. code-block:: twig -You are even able to check the number of items within a loop by comparing it with values within the IF condition: + {% if S_USER_LOGGED_IN %} + markup + {% endif %} -.. code:: html +.. seealso:: - - - markup - - - markup - + - `Twig for Template Designers - Control Structures `_ + - `Twig for Template Designers - Operators `_ -Nesting loops cause the conditionals needing prefixed with all loops from the outer one to the inner most. An illustration of this: +Extended syntax for Blocks/Loops +++++++++++++++++++++++++++++++++ -.. code:: html +Twig provides powerful features for working with loops, including setting start and end points, handling empty loops, and working with nested loops. - - {firstloop.MY_VARIABLE_FROM_FIRSTLOOP} +**Setting start and end points of a loop:** - - {firstloop.secondloop.MY_VARIABLE_FROM_SECONDLOOP} - - +You can use the `slice` filter to control which items are iterated over: -Sometimes it is necessary to break out of nested loops to be able to call another loop within the current iteration. This sounds a little bit confusing and it is not used very often. The following (rather complex) example shows this quite good - it also shows how you test for the first and last row in a loop (i will explain the example in detail further down): +.. code-block:: twig -.. code:: html + {# Start loop on the third entry (index 2) #} + {% for item in loopname|slice(2) %} + {{ item }} + {% endfor %} - - - {l_block1.L_TITLE} - - - - - - - - - - - - - - {l_block1.L_TITLE} - - - -Let us first concentrate on this part of the example: + {# Start two entries from the end #} + {% for item in loopname|slice(-2) %} + {{ item }} + {% endfor %} -.. code:: html + {# Start at index 3 and end at index 4 (2 items) #} + {% for item in loopname|slice(3, 2) %} + {{ item }} + {% endfor %} - - - markup - - {l_block1.L_TITLE} - - + {# Start at index 3 and end four from last #} + {% for item in loopname|slice(3, loopname|length - 3 - 4) %} + {{ item }} + {% endfor %} -Here we open the loop ``l_block1`` and do some things if the value ``S_SELECTED`` within the current loop iteration is true, else we write the blocks link and title. Here, you see ``{l_block1.L_TITLE}`` referenced - you remember that ``L_*`` variables get automatically assigned the corresponding language entry? This is true, but not within loops. The ``L_TITLE`` variable within the loop l_block1 is assigned within the code itself. +**Handling empty loops:** -Let's have a closer look at the markup: +Twig provides the `else` block for loops: -.. code:: html +.. code-block:: twig - - . - . - + {% for item in loop %} + {{ item }} + {% else %} + No items found. + {% endfor %} - - -
    - +**Checking if a loop contains values:** -
  • {folder.FOLDER_NAME}
    • +You can use an `if` statement with the `length` filter: - -
- - +.. code-block:: twig - - . - . - + {% if loop|length > 0 %} + {% for item in loop %} + {{ item }} + {% endfor %} + {% else %} + No items found. + {% endif %} -The ```` statement clearly checks a global variable and not one within the loop, since the loop is not given here. So, if ``S_PRIVMSGS`` is true we execute the shown markup. Now, you see the ```` statement. The exclamation mark is responsible for instructing the template engine to iterate through the main loop folder. So, we are now within the loop folder - with ```` we would have been within the loop ``l_block1.folder`` automatically as is the case with ``l_block2``: +Or simply use the `else` block as above. -.. code:: html +**Checking the number of items in a loop:** - - . - . - - . - . - - -You see the difference? The loop l_block2 is a member of the loop l_block1 but the loop folder is a main loop. - -Now back to our folder loop: +.. code-block:: twig -.. code:: html + {% if loop|length > 2 %} + {% for item in loop %} + {{ item }} + {% endfor %} + {% else %} + Not enough items. + {% endif %} - - - +.. code-block:: html -You may have wondered what the comparison to S_FIRST_ROW and S_LAST_ROW is about. If you haven't guessed already - it is checking for the first iteration of the loop with S_FIRST_ROW and the last iteration with S_LAST_ROW. This can come in handy quite often if you want to open or close design elements, like the above list. Let us imagine a folder loop build with three iterations, it would go this way: + {% for first in firstloop %} + {{ first.MY_VARIABLE_FROM_FIRSTLOOP }} -.. code:: html + {% for second in first.secondloop %} + {{ second.MY_VARIABLE_FROM_SECONDLOOP }} + {% endfor %} + {% endfor %} -
    -
  • first element
    • -
  • second element
    • -
  • third element
    • -
+**Breaking out of nested loops and working with special variables:** -As you can see, all three elements are written down as well as the markup for the first iteration and the last one. Sometimes you want to omit writing the general markup - for example: +Twig does not support breaking out of multiple nested loops directly, and child loops will not be directly interpreted as child loop inside `for` statements. +It is possible to use the `loop` variable to access the current loop's properties, such as `loop.index`, `loop.length`, and `loop.first`. This will however only work for the current loop, not for parent loops. -.. code:: html +.. code-block:: html - -
    - -
- -
  • {folder.FOLDER_NAME}
    • - + {% for l_block1 in l_block1_list %} + {% if l_block1.S_SELECTED %} + {{ l_block1.L_TITLE }} + {% if S_PRIVMSGS %} +
      + {% for folder in folders %} + {% if loop.first %} +
        + {% endif %} -would result in the following markup: +
      • {{ folder.FOLDER_NAME }}
        • -.. code:: html + {% if loop.last %} +
      + {% endif %} + {% endfor %} +
    + {% endif %} -
      -
    • second element
      • -
    +
      + {% for l_block2 in l_block1.l_block2 %} +
    • + {% if l_block2.S_SELECTED %} + {{ l_block2.L_TITLE }} + {% else %} + {{ l_block2.L_TITLE }} + {% endif %} +
      • + {% endfor %} +
    + {% else %} + {{ l_block1.L_TITLE }} + {% endif %} + {% endfor %} + +**Checking for first and last iteration:** + +Use `loop.first` and `loop.last`: + +.. code-block:: html + + {% for folder in folders %} + {% if loop.first %} + + {% endif %} + {% endfor %} + +**Alternative: Only output markup for certain iterations:** + +.. code-block:: html + + {% for folder in folders %} + {% if loop.first %} +
      + {% elseif loop.last %} +
    + {% else %} +
  • {{ folder.FOLDER_NAME }}
    • + {% endif %} + {% endfor %} Just always remember that processing is taking place from top to bottom. Forms +++++ -If a form is used for a non-trivial operation (i.e. more than a jumpbox), then it should include the {S_FORM_TOKEN} template variable. +If a form is used for a non-trivial operation (i.e. more than a jumpbox), then it **SHALL** include the ``{{ S_FORM_TOKEN }}`` template variable. .. code:: html -
    +
    - - - {S_FORM_TOKEN} + + + {{ S_FORM_TOKEN }}
    @@ -430,36 +404,85 @@ If a form is used for a non-trivial operation (i.e. more than a jumpbox), then i 4.ii. Styles Tree ----------------- -When basing a new style on an existing one, it is not necessary to provide all the template files. By declaring the base style name in the **parent** field in the **Style configuration file(cfg)**, the style can be set to reuse template files from the parent style. - -Style cfg files are simple name-value lists with the information necessary for installing a style. The important part of the style configuration file is assigning an unique name. +Style configuration ``composer.json`` files are derived from the standard `composer` file format, but with a few additional fields specific to phpBB styles. +An important part of the style is assigning a unique name both in the ``name`` field and in the ``display-name`` field in the ``extra`` section of the ``composer.json``: + +.. code:: json + + { + "name": "phpbb/phpbb-style-prosilver", + "description": "phpBB Forum Software default style", + "type": "phpbb-style", + "version": "4.0.0-a1-dev", + "homepage": "https://www.phpbb.com", + "license": "GPL-2.0", + "authors": [ + { + "name": "phpBB Limited", + "email": "operations@phpbb.com", + "homepage": "https://www.phpbb.com/go/authors" + } + ], + "support": { + "issues": "https://tracker.phpbb.com", + "forum": "https://www.phpbb.com/community/", + "docs": "https://www.phpbb.com/support/docs/", + "irc": "irc://irc.libera.chat/phpbb", + "chat": "https://www.phpbb.com/support/chat/" + }, + "extra": { + "display-name": "prosilver", + "phpbb-version": "4.0.0-a1-dev", + "parent-style": "" + } + } + +When basing a new style on an existing one, it is not necessary to provide all the template files. +By declaring the base style name in the **parent** field in the **Style configuration file (composer.json)**, the style can be set to reuse template files from the parent style: + +.. code:: json + + { + "name": "acme-author/my-custom-style", + "description": "My custom style based on prosilver", + "type": "phpbb-style", + "version": "1.0.0", + "homepage": "https://www.some-site.com", + "license": "GPL-2.0", + "authors": [ + { + "name": "ACME Author", + "email": "acme@some-site.com", + "homepage": "https://www.some-site.com" + } + ], + "extra": { + "display-name": "My Custom Style Acme Style", + "phpbb-version": "4.0.0", + "parent-style": "prosilver" + } + } The effect of doing so is that the template engine will use the template files in the new style where they exist, but fall back to files in the parent style otherwise. +In the above example, if the new style does not have a file named ``overall_header.html``, the template engine will use the one from the ``prosilver`` style. We strongly encourage the use of parent styles for styles based on the bundled styles, as it will ease the update procedure. -.. code:: php - - # General Information about this style - name = Custom Style - copyright = © phpBB Limited, 2007 - style_version = 3.2.0-b1 - phpbb_version = 3.2.0-b1 +.. note:: - # Defining a different template bitfield - # template_bitfield = lNg= - - # Parent style - # Set value to empty or to this style's name if this style does not have a parent style - parent = prosilver + The previously used ``style.cfg`` file has been replaced with ``composer.json`` in phpBB 4.0. The new format is more flexible and allows for better integration. 4.iii. Template Events ---------------------- -Template events must follow this format: ```` +Template events **SHALL** follow this format: ``{% EVENT event_name %}``. Using the above example, files named ``event_name.html`` located within extensions will be injected into the location of the event. +.. note:: + + The previously used ```` syntax has been deprecated in phpBB 4.0 and will be removed in a later version of phpBB. Please use the new Twig syntax instead. + Template event naming guidelines ++++++++++++++++++++++++++++++++ diff --git a/development/extensions/modification_to_extension.rst b/development/extensions/modification_to_extension.rst index abaad51e..59a3df5c 100644 --- a/development/extensions/modification_to_extension.rst +++ b/development/extensions/modification_to_extension.rst @@ -25,7 +25,7 @@ matter which files, may it be styles, language or ACP module files. All of them should be moved into your extension's directory: .. csv-table:: - :header: "new directory", "current directory" + :header: new directory, current directory :delim: | ``acp/*_module.php`` | ``phpBB/includes/acp/`` @@ -188,7 +188,7 @@ In this example my **controller/main.php** would look like the following: * * @package NV Newspage Extension * @copyright (c) 2013 nickvergessen - * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2 + * @license https://opensource.org/license/gpl-2-0 GNU General Public License v2 * */ @@ -282,7 +282,7 @@ As for the ``main_info.php`` we need to adjust the class name from * * @package NV Newspage Extension * @copyright (c) 2013 nickvergessen - * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2 + * @license https://opensource.org/license/gpl-2-0 GNU General Public License v2 * */ @@ -325,7 +325,7 @@ In case of the module, just adjust the class name: * * @package NV Newspage Extension * @copyright (c) 2013 nickvergessen - * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2 + * @license https://opensource.org/license/gpl-2-0 GNU General Public License v2 * */ @@ -550,7 +550,7 @@ A complete file could look like this: * * @package migration * @copyright (c) 2013 phpBB Group - * @license http://opensource.org/licenses/gpl-license.php GNU Public License v2 + * @license https://opensource.org/license/gpl-2-0 GNU Public License v2 * */ @@ -652,7 +652,7 @@ implements a Symfony class: * * @package NV Newspage Extension * @copyright (c) 2013 nickvergessen - * @license http://opensource.org/licenses/gpl-2.0.php GNU General Public License v2 + * @license https://opensource.org/license/gpl-2-0 GNU General Public License v2 * */ @@ -774,7 +774,7 @@ Adding Events There are already numerous events available. However, if your extension needs to make use of an event which is not yet in the phpBB code, you can request the event be added to the core by creating a ticket in the -`phpBB Bug Tracker `_ and we will +`phpBB Bug Tracker `_ and we will endeavour to include it in the next release. Basics finished! diff --git a/development/extensions/new_in_rhea.rst b/development/extensions/new_in_rhea.rst index ad559eda..d0c50e48 100644 --- a/development/extensions/new_in_rhea.rst +++ b/development/extensions/new_in_rhea.rst @@ -29,7 +29,7 @@ New Language Object A new Language object has been introduced that decouples language functions from the User object. That is to say, the following language functions now belong to the ``\phpbb\language\language`` class: .. csv-table:: - :header: "Function", "Description" + :header: Function, Description :delim: | ``lang`` | "Advanced language substitution." @@ -79,7 +79,7 @@ As of phpBB 3.2, a new and more powerful BBCode formatting engine has been integ The new engine has already been equipped with many PHP events making it even easier than before for extensions to configure BBCodes and BBCode formatted text. The following are the new PHP events: .. csv-table:: - :header: "Event", "Description" + :header: Event, Description :delim: | ``core.text_formatter_s9e_configure_before`` | "Modify the s9e\TextFormatter configurator before the default settings are set." @@ -131,7 +131,7 @@ A major change introduced by the new engine is how text (in posts, PMs, signatur Extensions that are storing their own messages with BBCodes and smilies should consider adding a TextReparser class to ensure their messages are updated to the new XML format. See `New Text Reparser`_ for more information. .. seealso:: - The s9e/TextFormatter library `documentation and cookbook `_. + The s9e/TextFormatter library `documentation and cookbook `_. New Text Reparser ================= @@ -274,7 +274,7 @@ phpBB 3.2 includes the Font Awesome toolkit. It is used by the default style Pro The result of this is significant template changes to Prosilver, including some new CSS classes. Extensions written for phpBB 3.1 that make use of any of Prosilver's icons may need to be adjusted to be compatible with phpBB 3.2. -The benefit of the new `Font Awesome icons `_ is they make it easy to improve GUI elements of your extension. For example, if an extension has a "Delete" link or button, you can easily add a nice little Trash Can icon to the link or button: +The benefit of the new `Font Awesome icons `_ is they make it easy to improve GUI elements of your extension. For example, if an extension has a "Delete" link or button, you can easily add a nice little Trash Can icon to the link or button: .. code-block:: html diff --git a/development/extensions/tutorial_advanced.rst b/development/extensions/tutorial_advanced.rst index 98ffe22d..c223fcf5 100644 --- a/development/extensions/tutorial_advanced.rst +++ b/development/extensions/tutorial_advanced.rst @@ -184,7 +184,7 @@ executed until such time as false is returned. Using service collections ========================= In 3.1, a new concept is that of "services". You can read up on exactly what a -service is `here `_. +service is `here `_. The rest of this guide will assume you have basic knowledge of services and how to use them. A service collection is basically what it sounds like: a collection of services. Basically, @@ -255,7 +255,7 @@ loaded, which is especially useful in cases where service priority and/or depend requires they be loaded in a specified order. Ordered service collections are based on a normal service collection, but the -collection is sorted with `ksort `_. The usage of the +collection is sorted with `ksort `_. The usage of the sorted service collection is nearly the same as a normal service collection, except instead of using ``service_collection`` you should use ``ordered_service_collection``: @@ -403,7 +403,7 @@ Using service decoration ======================== .. seealso:: Read about Service Decoration at - `Symfony `_ + `Symfony `_ for complete documentation. From phpBB 3.2, you can use service decoration as the preferred method to replace @@ -471,7 +471,7 @@ file: } .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: | ``host`` | "Full URL to the host domain server." @@ -519,7 +519,7 @@ used for stable release versions suitable for a live forum. The unstable branch can be used to provide links to versions in development. .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: | ``current`` | "The current version of the extension in a given branch." diff --git a/development/extensions/tutorial_authentication.rst b/development/extensions/tutorial_authentication.rst index 045a1191..0d68e8fc 100644 --- a/development/extensions/tutorial_authentication.rst +++ b/development/extensions/tutorial_authentication.rst @@ -24,8 +24,8 @@ Creating an Authentication Provider Authentication providers in phpBB require a minimum of two files: a PHP class and a YAML service file. -The class file -^^^^^^^^^^^^^^ +.. rubric:: The class file + The provider class must implement the ``\phpbb\auth\provider\provider_interface`` in order to ensure proper functionality. However, it is recommended to extend ``\phpbb\auth\provider\base`` so as to not implement unneeded methods and to ensure @@ -39,7 +39,7 @@ authentication provider class is show below: namespace acme\demo\auth\provider; /** - * Database authentication provider for phpBB3 + * Database authentication provider for phpBB * * This is for authentication via the integrated user table */ @@ -104,8 +104,8 @@ authentication provider class is show below: } } -The service file -^^^^^^^^^^^^^^^^ +.. rubric:: service file + For proper :ref:`dependency injection ` the provider must be added to ``services.yml``. The name of the service must be in the form of ``auth.provider.`` in order for phpBB to register it. @@ -123,8 +123,8 @@ for the class to be made available in phpBB. tags: - { name: auth.provider } -The template file -^^^^^^^^^^^^^^^^^ +.. rubric:: template file + Following the above steps renders the authentication provider visible in the ACP. However, to allow an admin to configure your plugin the available fields need to be created in order to reach the configuration from the php-auth-provider plugin. @@ -162,14 +162,14 @@ get the data it needs from the service, and the service file which allows phpBB to find the class. To find out how you should most likely make calls to the OAuh service, it is recommended that you refer to the included OAuth services and to the examples provided by -`Lusitanian/PHPoAuthLib `_. +`carlos-mg89/PHPoAuthLib `_. The example files below show the minimum needed to enable an OAuth service in -phpBB. They are copies of the bitly service implementation from phpBB3's +phpBB. They are copies of the bitly service implementation from phpBB's develop branch. -The Class file -^^^^^^^^^^^^^^ +.. rubric:: The Class file + .. code-block:: php `` in order for phpBB to diff --git a/development/extensions/tutorial_basics.rst b/development/extensions/tutorial_basics.rst index 2a29e15d..b879c2d1 100644 --- a/development/extensions/tutorial_basics.rst +++ b/development/extensions/tutorial_basics.rst @@ -92,7 +92,7 @@ The details of the meta data are explained below the sample, but for now let's h It is important to remember that the last item or object in any JSON array must not contain a trailing comma. .. csv-table:: - :header: "Field", "Required", "Content" + :header: Field, Required, Content :delim: | ``name`` | Yes | "The vendor name and extension name, separated by ``/``, matching the folder @@ -124,7 +124,7 @@ authors You may have unlimited authors. At least one author is highly recommended. .. csv-table:: - :header: "Field", "Required", "Content" + :header: Field, Required, Content :delim: | ``name`` | Yes | "The name of an author." @@ -140,7 +140,7 @@ List the dependencies required by the extension, i.e. the PHP version and `third party libraries `_. .. csv-table:: - :header: "Field", "Content" + :header: Field, Content :delim: | ``php`` | "The minimum-stability version of PHP required by the extension. phpBB 3.2 requires PHP 5.4.0 or higher, @@ -163,7 +163,7 @@ This section can contain virtually any arbitrary data according to the composer two special entries in this array for extensions: .. csv-table:: - :header: "Field", "Content" + :header: Field, Content :delim: | ``display-name`` | "The name of your extension, e.g. Acme Demo Extension." diff --git a/development/extensions/tutorial_bbcodes.rst b/development/extensions/tutorial_bbcodes.rst index 1b15d44d..25e5db42 100644 --- a/development/extensions/tutorial_bbcodes.rst +++ b/development/extensions/tutorial_bbcodes.rst @@ -23,7 +23,7 @@ Toggle BBCodes On / Off BBCodes and other tags can be toggled before or after parsing using any of the following events: .. csv-table:: - :header: "Event", "Description" + :header: Event, Description :delim: | ``core.text_formatter_s9e_parser_setup`` | Triggers once, when the text Parser service is first created. @@ -34,7 +34,7 @@ Most common operations are available through the Parser service using the ``phpb This includes the functions: .. csv-table:: - :header: "Function", "Description" + :header: Function, Description :delim: | ``disable_bbcode($name)`` | Disable a BBCode @@ -80,7 +80,7 @@ The following sample code shows how BBCodes can be toggled and manipulated using .. seealso:: https://area51.phpbb.com/docs/code/3.2.x/phpbb/textformatter/parser_interface.html - http://s9etextformatter.readthedocs.io/Getting_started/Runtime_configuration/ + https://s9etextformatter.readthedocs.io/Getting_started/Runtime_configuration/ Executing PHP Code With BBCodes @@ -133,9 +133,9 @@ method to read and change its attributes during parsing based on who is being qu .. seealso:: - http://s9etextformatter.readthedocs.io/Filters/Attribute_filters/ - http://s9etextformatter.readthedocs.io/Filters/Tag_filters/ - http://s9etextformatter.readthedocs.io/Filters/Callback_signature/ + https://s9etextformatter.readthedocs.io/Filters/Attribute_filters/ + https://s9etextformatter.readthedocs.io/Filters/Tag_filters/ + https://s9etextformatter.readthedocs.io/Filters/Callback_signature/ Template Parameters @@ -147,7 +147,7 @@ that will only show its content to registered users. Default phpBB template parameters: .. csv-table:: - :header: "Variable", "Description" + :header: Variable, Description :delim: | ``S_IS_BOT`` | Whether the current user is a bot. @@ -210,7 +210,7 @@ users can see the contents of: Template parameters can also be set using any of the following events: .. csv-table:: - :header: "Event", "Description" + :header: Event, Description :delim: | ``core.text_formatter_s9e_renderer_setup`` | Triggers once, when the renderer service is created. @@ -242,8 +242,8 @@ your own template parameters, in addition to the default one's already available .. seealso:: - http://s9etextformatter.readthedocs.io/Templating/Template_parameters/ - http://s9etextformatter.readthedocs.io/Plugins/BBCodes/Use_template_parameters/ + https://s9etextformatter.readthedocs.io/Templating/Template_parameters/ + https://s9etextformatter.readthedocs.io/Plugins/BBCodes/Use_template_parameters/ Registering Custom Variables @@ -301,9 +301,9 @@ set the value before each parsing. .. seealso:: https://area51.phpbb.com/docs/code/3.2.x/phpbb/textformatter/parser_interface.html - http://s9etextformatter.readthedocs.io/Filters/Callback_signature/ - http://s9etextformatter.readthedocs.io/Filters/Attribute_filters/ - http://s9etextformatter.readthedocs.io/Filters/Tag_filters/ + https://s9etextformatter.readthedocs.io/Filters/Callback_signature/ + https://s9etextformatter.readthedocs.io/Filters/Attribute_filters/ + https://s9etextformatter.readthedocs.io/Filters/Tag_filters/ Enable Text Formatter Plugins ============================= @@ -354,4 +354,4 @@ settings are configured. .. seealso:: - http://s9etextformatter.readthedocs.io + https://s9etextformatter.readthedocs.io diff --git a/development/extensions/tutorial_controllers.rst b/development/extensions/tutorial_controllers.rst index 43c6a6a2..263264d9 100644 --- a/development/extensions/tutorial_controllers.rst +++ b/development/extensions/tutorial_controllers.rst @@ -5,9 +5,9 @@ Tutorial: Controllers and Routes Introduction ============ -phpBB 3.1 introduced Symfony's `HttpKernel `__, +phpBB 3.1 introduced Symfony's `HttpKernel `__, `Controller `__ and -`Routing `__ systems which +`Routing `__ systems which allow extensions to handle custom "front-facing" pages that users are able to view and interact with. @@ -280,7 +280,7 @@ our route definition: name: \d+ .. csv-table:: - :header: "Item", "Description" + :header: Item, Description :delim: | route | "The route name is a unique name and must be prefixed with the vendor and extension names. Use only lowercase letters and underscores." diff --git a/development/extensions/tutorial_events.rst b/development/extensions/tutorial_events.rst index 9a888018..9ea6a471 100644 --- a/development/extensions/tutorial_events.rst +++ b/development/extensions/tutorial_events.rst @@ -256,7 +256,7 @@ the link in the navigation bar should now display ``Demo`` instead of phpBB’s core PHP and template files have been prepared with dozens of event locations. However, if there are no events where your extension may need one, the phpBB development team welcomes event requests at the - `area51.com Event Requests `_ forum. + `area51.com Event Requests `_ forum. Prioritising event listeners (optional) --------------------------------------- diff --git a/development/extensions/tutorial_key_concepts.rst b/development/extensions/tutorial_key_concepts.rst index 15883073..7ef82ae8 100644 --- a/development/extensions/tutorial_key_concepts.rst +++ b/development/extensions/tutorial_key_concepts.rst @@ -135,17 +135,22 @@ then the ``IN_PHPBB`` test is required prior to any executable code: .. seealso:: - * The phpBB 3.1 `Coding Guidelines `_. + * The phpBB :doc:`Coding Guidelines <../development/index>`. * The phpBB Customisation Database `PHP Validation Policy `_. Template files ============== -Templating for extensions is no different than templating for phpBB3 in general. phpBB 3.1 has switched to the +Templating for extensions is no different than templating for phpBB in general. Since version 3.1, phpBB has switched to the Twig template engine but retains phpBB’s original templating syntax. Therefore, either phpBB or Twig template syntax is permissible in an extension. If you are not familiar with Twig, you may use phpBB’s syntax. +.. note:: + + phpBB 4.0 will be deprecating the phpBB template syntax in favour of Twig. Therefore, it is recommended to use Twig syntax + in your extensions to future-proof them. + An extension can contain two types of template files: custom templates and :ref:`template-events-label`. An extension's custom template files should have unique names, preferably prefixed with the vendor and extension names, to prevent conflicts with other extension or phpBB template files. In addition to template diff --git a/development/extensions/tutorial_modules.rst b/development/extensions/tutorial_modules.rst index 725eb651..87d14c12 100644 --- a/development/extensions/tutorial_modules.rst +++ b/development/extensions/tutorial_modules.rst @@ -74,7 +74,7 @@ The ``main_info`` class has only one method ``module()`` which returns an array with the following information: .. csv-table:: - :header: "Key", "Content" + :header: Key, Content :delim: | ``filename`` | "Fully name-spaced path to the `Module class`_, starting with a leading slash." @@ -86,7 +86,7 @@ with the following information: Note that we have defined one mode named ``settings`` with the following information: .. csv-table:: - :header: "Key", "Content" + :header: Key, Content :delim: | ``title`` | "Language key of the mode-title that is displayed in the ACP module diff --git a/development/extensions/tutorial_notifications.rst b/development/extensions/tutorial_notifications.rst index b7e152bb..a3793e46 100644 --- a/development/extensions/tutorial_notifications.rst +++ b/development/extensions/tutorial_notifications.rst @@ -309,7 +309,7 @@ Base Services The base notification type class (:class:`\\phpbb\\notification\\type\\base`) already has a few available services which can be used in our class's functions. .. csv-table:: - :header: "Object", "Class" + :header: Object, Class :delim: | ``$auth`` | :class:`\\phpbb\\auth\\auth` @@ -663,7 +663,7 @@ But if you are using the email method, then you should use this function to defi However, note that the phpBB core already defines some *default* variables for you: .. csv-table:: - :header: "Variable", "Description", "Defined in" + :header: Variable, Description, Defined in :delim: # ``USERNAME`` # The recipient's username # :class:`\\phpbb\\notification\\method\\messenger_base` ``notify_using_messenger()`` @@ -964,7 +964,7 @@ Optionally you can send a third argument, ``$options``, to specify which notific The options that can be defined are listed below: .. csv-table:: - :header: "Object", "Class" + :header: Object, Class :delim: # ``item_id`` # The item identifier for the notification. |br| Defaults to get_item_id_ @@ -1033,11 +1033,10 @@ This function is very simple to use, and requires only a few basic parameters: delete_notifications -------------------- -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **notification_type** # The notification service identifier. |br| Can be a single string or an array of service identifiers. |br| In this example: ``vendor.extension.notification.type.sample``. @@ -1080,11 +1079,10 @@ The following is a quick summary of the three methods available for marking noti mark_notifications ------------------ -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **notification_type** # Can be a single string or an array of service identifiers. |br| In this example: ``vendor.extension.notification.type.sample``. @@ -1096,11 +1094,10 @@ Parameters mark_notifications_by_parent ---------------------------- -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **notification_type** # Can be a single string or an array of service identifiers. |br| In this example: ``vendor.extension.notification.type.sample``. @@ -1117,11 +1114,10 @@ as most of the notification handling is done through the distinct item and/or pa However, there can be times where it is more convenient or accurate to work directly with the notification's unique id. For example, when the notifications are listed in the :abbr:`UCP (User Control Panel)` and a user can select specific notifications to be marked as read. -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **method_name** # The notification method service identifier |br| For example: ``notification.method.board`` diff --git a/development/extensions/tutorial_templates.rst b/development/extensions/tutorial_templates.rst index 86a6ef10..e50dd0bc 100644 --- a/development/extensions/tutorial_templates.rst +++ b/development/extensions/tutorial_templates.rst @@ -129,10 +129,10 @@ To make comments inside the template you can use ``{# #}``: {# Your comments can go here. #} -Variables ---------- +Template variables +------------------ -Variables in phpBB take the form of ``{{ X_YYYYY }}``, where the data is assigned from the source. However, most +Template variables in phpBB take the form of ``{{ X_YYYYY }}``, where the data is assigned from the source. However, most language strings are not assigned from the source. When a language variable is found, denoted as ``{{ lang('YYYYYY') }}``, phpBB first checks if an assigned variable with that name exists. If it does, it uses that. If not, it checks if an existing string defined in the language file exists. @@ -141,8 +141,8 @@ By using the language variable format, phpBB allows for more flexibility in the This allows for easy modifications of language strings in the language files without having to modify the source code directly. -Blocks ------- +Template blocks +--------------- The basic block level loop takes the form: diff --git a/development/language/guidelines.rst b/development/language/guidelines.rst index 13bf32f7..7cf65ced 100644 --- a/development/language/guidelines.rst +++ b/development/language/guidelines.rst @@ -161,7 +161,7 @@ If your language pack is denied and then resubmitted, it is placed at the end of .. _Customisations Database: https://www.phpbb.com/go/customise/language-packs/4.0 .. _Language Packs Database: https://www.phpbb.com/languages/ -.. _GNU General Public License 2.0: http://www.opensource.org/licenses/gpl-2.0.php +.. _GNU General Public License 2.0: https://opensource.org/license/gpl-2-0 .. _4.0 Translation (i18n/L10n) Guidelines: https://area51.phpbb.com/docs/40x/coding-guidelines.html#translation .. _4.0 Writing style: https://area51.phpbb.com/docs/40x/coding-guidelines.html#writingstyle .. _Notepad++: https://notepad-plus-plus.org/ diff --git a/development/language/plurals.rst b/development/language/plurals.rst index 5fc05c9a..54087003 100644 --- a/development/language/plurals.rst +++ b/development/language/plurals.rst @@ -218,6 +218,6 @@ Credits The system is based on `Unicode.org`_, which uses the "Plural Rules and Families" from -`GNU gettext documentation `_ and is used e.g. by Mozilla. +`GNU gettext documentation `_ and is used e.g. by Mozilla. .. _Unicode.org: https://www.unicode.org/cldr/charts/43/supplemental/language_plural_rules.html diff --git a/development/language/usage.rst b/development/language/usage.rst index 8aed308f..f529b7ba 100644 --- a/development/language/usage.rst +++ b/development/language/usage.rst @@ -151,7 +151,7 @@ directory. When writing or editing a language file, make sure to save it using utf-8 encoding **without BOM** - (`Byte Order Mark `_). + (`Byte Order Mark `_). Otherwise the forum will not function properly. Some editors call that mode "utf8 cookie". diff --git a/development/language/validation.rst b/development/language/validation.rst index cd6450bd..166a74eb 100644 --- a/development/language/validation.rst +++ b/development/language/validation.rst @@ -36,7 +36,7 @@ Package this folder. * Revision name in the `Customisation Database`_ should be left blank, contain the phpBB package version and/or package release name (e.g. ``3.3.10`` / - ``Bertie's translation` for 3.3.10) for more understanding. + ``Bertie's translation`` for 3.3.10) for more understanding. Package Validation ================== @@ -164,7 +164,7 @@ Please do not omit any of these lines, and fill them out carefully. .. note:: -The ``composer.json`` must be valid JSON code. You can validate it using ``composer.phar``, see: `composer.json validation`_. + The ``composer.json`` must be valid JSON code. You can validate it using ``composer.phar``, see: `composer.json validation`_. \*/index.htm ------------ @@ -307,7 +307,7 @@ License ------- * All translations must be released under - `GNU General Public License 2.0 `_ + `GNU General Public License 2.0 `_ .. _Customisation Database: https://www.phpbb.com/go/customise/language-packs/4.0 .. _Language Pack Submission Policy: https://area51.phpbb.com/docs/dev/master/language/guidelines.html#language-pack-submission-policy diff --git a/development/make.bat b/development/make.bat index b3cf6e0a..f67687bd 100644 --- a/development/make.bat +++ b/development/make.bat @@ -56,7 +56,7 @@ if errorlevel 9009 ( echo.may add the Sphinx directory to PATH. echo. echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ + echo.https://sphinx-doc.org/ exit /b 1 ) diff --git a/development/migrations/data_changes.rst b/development/migrations/data_changes.rst index db7f54b8..db4eff0e 100644 --- a/development/migrations/data_changes.rst +++ b/development/migrations/data_changes.rst @@ -63,8 +63,7 @@ If (Conditional) If call allows you to create a basic if statement which will be checked and, if true, the attached statement will be parsed. -How it works ------------- +.. rubric:: How it works .. code-block:: php @@ -73,8 +72,7 @@ How it works [/* Call to make if the statement is true */], ]], -Examples --------- +.. rubric:: Examples if config "captcha_gd" is true, update "captcha_plugin" with "phpbb_captcha_gd" @@ -105,8 +103,7 @@ Custom Custom calls allow you to specify the callable to your own function to be called. -How it works ------------- +.. rubric:: How it works .. code-block:: php @@ -114,8 +111,7 @@ How it works [/* Callable function */] ]], -Example -------- +.. rubric:: Example Call a function within the migrations file named some_function @@ -141,8 +137,7 @@ until null or true is returned. This should be used when something needs to be run that can take longer than the time limit (for example, resyncing topics). -Example -------- +.. rubric:: Example .. code-block:: php @@ -192,8 +187,7 @@ Passing parameters to custom functions array(/* Callable function */), array(/* Parameters to the function */), )), -Example -------- +.. rubric:: Example Call a function within the migrations file named some_function, passing it some parameters @@ -207,8 +201,7 @@ Call a function within the migrations file named some_function, passing it some The function called must accept the specified parameters -Example -------- +.. rubric:: Example Fully compatible with multi step process diff --git a/development/migrations/dependencies.rst b/development/migrations/dependencies.rst index da7c088d..414801d4 100644 --- a/development/migrations/dependencies.rst +++ b/development/migrations/dependencies.rst @@ -59,7 +59,7 @@ depends_on creates a tree Imagine the following situation: .. csv-table:: - :header: "Migration", "Dependencies", "Note" + :header: Migration, Dependencies, Note :delim: | ``migration_1`` | ``phpbb\db\migration\data\\v310\\dev`` | Initial release, 1.0.0, requires phpBB 3.1.0 @@ -74,7 +74,7 @@ installed when an individual Migration was installed manually. *Assumes* .. csv-table:: - :header: "Install", "Migrations that are installed" + :header: Install, Migrations that are installed :delim: | ``migration_1`` | ``migration_1`` diff --git a/development/migrations/index.rst b/development/migrations/index.rst index 81e0d672..e9291b11 100644 --- a/development/migrations/index.rst +++ b/development/migrations/index.rst @@ -8,7 +8,7 @@ Migrations was built because of the difficulties of distributed development and maintaining an updated database setup across all developers. RFC Topic if you're interested in the reasons: -``_ +``_ .. toctree:: :maxdepth: 1 diff --git a/development/migrations/tools/config.rst b/development/migrations/tools/config.rst index 77774b82..3038a67d 100644 --- a/development/migrations/tools/config.rst +++ b/development/migrations/tools/config.rst @@ -13,8 +13,7 @@ Add a new config setting ['config.add', [config name, config value, is dynamic (default: false) ]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -35,8 +34,7 @@ Update a config setting ['config.update', [config name, new config value]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -57,8 +55,7 @@ value ['config.update_if_equals', [compare to, config name, new config value]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -78,8 +75,7 @@ Delete a config setting ['config.remove', [config name]], -Example -------- +.. rubric:: Example .. code-block:: php diff --git a/development/migrations/tools/config_text.rst b/development/migrations/tools/config_text.rst index 890a432f..fcdb428a 100644 --- a/development/migrations/tools/config_text.rst +++ b/development/migrations/tools/config_text.rst @@ -16,8 +16,7 @@ Add a new config_text setting ['config_text.add', [config name, config value]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -38,8 +37,7 @@ Update a config_text setting ['config_text.update', [config name, new config value]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -59,8 +57,7 @@ Delete a config_text setting ['config_text.remove', [config name]], -Example -------- +.. rubric:: Example .. code-block:: php diff --git a/development/migrations/tools/module.rst b/development/migrations/tools/module.rst index a6df93b4..f15bfd3d 100644 --- a/development/migrations/tools/module.rst +++ b/development/migrations/tools/module.rst @@ -14,7 +14,7 @@ Add a new module ['module.add', [ mixed $class [, mixed $parent [, array $data [, mixed $include_path ]]] ]] .. csv-table:: - :header: "Parameter", "Required/Default", "Usage" + :header: Parameter, Required/Default, Usage :delim: | class | Required | The module class: acp, mcp, or ucp @@ -22,8 +22,7 @@ Add a new module data | default [] | An array of the data on the new module. This can be setup in two different ways. (see below) include_path | default false | Optionally specify a custom include path (only works when using the automatic module add method) -Manually specifying module info -------------------------------- +.. rubric:: Manually specifying module info The "manual" way for inserting a category or one module at a time. It will be merged with the base array shown a bit below, but at the very least requires @@ -43,8 +42,7 @@ just a category) you must send ``module_basename`` and ``module_mode``. 'module_auth' => '', ]; -Automatically determining module info -------------------------------------- +.. rubric:: Automatically determining module info The "automatic" way. For inserting multiple modules at a time based on the specs in the ``_info`` file for the module(s). For this to work the modules must be @@ -62,8 +60,7 @@ file): Optionally you may omit 'modes' and it will insert all of the modules in that info file. -Example -------- +.. rubric:: Example .. code-block:: php @@ -112,7 +109,7 @@ Parameters ---------- .. csv-table:: - :header: "Parameter", "Required/Default", "Usage" + :header: Parameter, Required/Default, Usage :delim: | class | Required | The module class: acp, mcp, or ucp @@ -120,14 +117,12 @@ Parameters module | default '' | The module_id or module_langname of the module to remove (more information below) include_path | default false | Optionally specify a custom include path (only works when using the automatic module add method) -Manually specifying module info -------------------------------- +.. rubric:: Manually specifying module info The "manual" way. When removing the module using the manual method you may specify a string (module_langname) or an integer (module_id) -Automatically determining module info -------------------------------------- +.. rubric:: Automatically determining module info The "automatic" way. When removing the module using the automatic method you may use the same information sent through the $data array when using the @@ -135,8 +130,7 @@ automatic method of the module_add function. Just as with the automatic add method, this will automatically find the modules listed according to the given module_basename and modes from the _info file. -Example -------- +.. rubric:: Example .. code-block:: php diff --git a/development/migrations/tools/permission.rst b/development/migrations/tools/permission.rst index 6d2d67c5..0778a107 100644 --- a/development/migrations/tools/permission.rst +++ b/development/migrations/tools/permission.rst @@ -14,8 +14,7 @@ Add a new permission ['permission.add', [permission name, global (default: true) , copy from (default: false) ]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -41,8 +40,7 @@ Delete a permission ['permission.remove', [permission name, global (default: true) ]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -65,8 +63,7 @@ Add a new permission role ['permission.role_add', [role name, role type (u_, m_, a_), role description]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -88,8 +85,7 @@ Update a permission role ['permission.role_update', [old role name, new role name]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -109,8 +105,7 @@ Remove a permission role ['permission.role_remove', [role name]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -132,8 +127,7 @@ Set a permission (to Yes or Never) ['permission.permission_set', [role/group name, permission name(s), type ('role', 'group', default: role), has permission (default: true) ]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -156,8 +150,7 @@ Remove a permission (set to No) ['permission.permission_unset', [role/group name, permission name(s), type ('role', 'group', default: role) ]], -Example -------- +.. rubric:: Example .. code-block:: php @@ -177,8 +170,7 @@ Check if a permission role exists before attempting to set/unset permissions on ['permission.role_exists', [role name]], -Example -------- +.. rubric:: Example .. code-block:: php diff --git a/development/request/request.rst b/development/request/request.rst index c19ea3be..2288b67c 100644 --- a/development/request/request.rst +++ b/development/request/request.rst @@ -88,11 +88,10 @@ If no super global is specified, it will default to the ``REQUEST`` super global $submit = $request->variable('submit', \phpbb\request\request_interface::POST); $session = $request->variable('user_sid', \phpbb\request\request_interface::COOKIE); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **variable** # The name of the variable to check @@ -115,11 +114,10 @@ This is a short hand for ``$request->variable('variable', \phpbb\request\request // The form was submitted with a POST request } -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **variable** # The name of the variable to check @@ -202,11 +200,10 @@ The nesting increased with each value provided. * Please note that the last array is 0-based. */ -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **variable** # The name of the variable to retrieve @@ -233,11 +230,10 @@ So for ```` the variable name is ``attachme $file = $upload->handle_upload('files.types.form', 'avatar_upload_file'); } -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **variable** # The name of the HTML file input's name attribute @@ -262,11 +258,10 @@ This function is a shortcut to retrieve the value of the client's HTTP headers. // ... } -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **variable** # The name of the header to retrieve @@ -288,11 +283,10 @@ It also provides a fallback to ``getenv()`` as some CGI setups may need it. $server_port = $request->server('SERVER_PORT', 0); -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **variable** # The name of the variable to retrieve @@ -328,11 +322,10 @@ Changes which are performed on the super globals directly will **not** have any $request->overwrite('confirm_key', null, \phpbb\request\request_interface::POST); } -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **variable** # The name of the variable that should be overwritten @@ -375,11 +368,10 @@ It will then return all the names *(keys)* that exist for that super global. return $hidden; -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **super_global** # The super global to get the variable names from. |br| Can be any of ``GET|POST|REQUEST|COOKIE|SERVER|FILES``. |br| Defaults to ``REQUEST``. @@ -413,11 +405,10 @@ It will then return the original array with all the variables for that super glo $auth_provider->unlink_account($link_data); } -Parameters -^^^^^^^^^^ +.. rubric:: Parameters .. csv-table:: - :header: "Parameter", "Description" + :header: Parameter, Description :delim: # **super_global** # The super global to get the original array from. |br| Can be any of ``GET|POST|REQUEST|COOKIE|SERVER|FILES``. |br| Defaults to ``REQUEST``. diff --git a/development/start/getting_started.rst b/development/start/getting_started.rst index e2fb3f59..925982db 100644 --- a/development/start/getting_started.rst +++ b/development/start/getting_started.rst @@ -51,7 +51,7 @@ Although we are rather proud of the included styles, we realise that they may no For more information about styles, please see: https://www.phpbb.com/styles/ -**Please note** that 3rd party styles downloaded for versions of phpBB2 will **not** work in phpBB3. It is also important to ensure that the style is updated to match the current version of the phpBB software you are using. +**Please note** that 3rd party styles downloaded for previous versions of phpBB will **not** work. It is important to ensure that the style is updated to match the current version of the phpBB software you are using. Once you have downloaded a style, the usual next step is to unarchive (or upload the unarchived contents of) the package into your ``styles/`` directory. You then need to visit ``Administration Control Panel -> Customise tab -> Style management -> Install Styles`` where you should see the new style available. Click "Install style" to install the style. @@ -128,7 +128,7 @@ This is a stable release of phpBB. The 3.2.x line is feature frozen, with point Those interested in the development of phpBB should keep an eye on the development forums to see how things are progressing: -http://area51.phpbb.com/phpBB/ +https://area51.phpbb.com/phpBB/ Please note that the development forums should **NOT** be used to seek support for phpBB, the main community forums are the place for this. @@ -139,7 +139,7 @@ Please note that the development forums should **NOT** be used to seek support f The phpBB developers use a bug tracking system to store, list and manage all reported bugs, it can be found at the location listed below. Please **DO NOT** post bug reports to our forums. In addition please **DO NOT** use the bug tracker for support requests. Posting such a request will only see you directed to the support forums (while taking time away from working on real bugs). -http://tracker.phpbb.com/browse/PHPBB3 +https://tracker.phpbb.com/browse/PHPBB While we very much appreciate receiving bug reports (the more reports the more stable phpBB will be) we ask you carry out a few steps before adding new entries: @@ -159,7 +159,7 @@ The relevant database type/version is listed within the administration control p Please be as detailed as you can in your report, and if possible, list the steps required to duplicate the problem. If you have a patch that fixes the issue, please attach it to the ticket or submit a pull request to our repository on `GitHub `_. -If you create a patch, it is very much appreciated (but not required) if you follow the phpBB coding guidelines. Please note that the coding guidelines are somewhat different between different versions of phpBB. For phpBB 3.2.x the coding guidelines may be found here: http://area51.phpbb.com/docs/32x/coding-guidelines.html +If you create a patch, it is very much appreciated (but not required) if you follow the phpBB coding guidelines. Please note that the coding guidelines are somewhat different between different versions of phpBB. For phpBB 3.2.x the coding guidelines may be found here: https://area51.phpbb.com/docs/32x/coding-guidelines.html Once a bug has been submitted you will be emailed any follow up comments added to it. **Please** if you are requested to supply additional information, do so! It is frustrating for us to receive bug reports, ask for additional information but get nothing. In these cases we have a policy of closing the bug, which may leave a very real problem in place. Obviously we would rather not have this situation arise. diff --git a/development/start/install.rst b/development/start/install.rst index cb8fbdd9..3cfab675 100644 --- a/development/start/install.rst +++ b/development/start/install.rst @@ -5,23 +5,23 @@ Installation 1. Quick install ================ -If you have basic knowledge of using FTP and are sure your hosting service or server will run phpBB3 you can use these steps to quickly get started. For a more detailed explanation you should skip this and go to `2. Requirements`_ below. +If you have basic knowledge of using FTP and are sure your hosting service or server will run phpBB you can use these steps to quickly get started. For a more detailed explanation you should skip this and go to `2. Requirements`_ below. -Decompress the phpBB3 archive to a local directory on your system. +Decompress the phpBB archive to a local directory on your system. Upload all the files contained in this archive (retaining the directory structure) to a web accessible directory on your server or hosting account. Change the permissions on config.php to be writable by all (``666`` or ``-rw-rw-rw-`` within your FTP Client) Change the permissions on the following directories to be writable by all (``777`` or ``-rwxrwxrwx`` within your FTP Client): ``store/``, ``cache/``, ``files/`` and ``images/avatars/upload/``. -Point your web browser to the location where you uploaded the phpBB3 files with the addition of ``install/app.php`` or simply ``install/``, e.g. ``http://www.example.com/phpBB3/install/app.php``, ``http://www.example.com/forum/install/``. +Point your web browser to the location where you uploaded the phpBB files with the addition of ``install/app.php`` or simply ``install/``, e.g. ``http://www.example.com/phpBB/install/app.php``, ``http://www.example.com/forum/install/``. Click the **INSTALL** tab, follow the steps and fill out all the requested information. Change the permissions on config.php to be writable only by yourself (``644`` or ``-rw-r--r--`` within your FTP Client) -phpBB3 should now be available, please **MAKE SURE** you read at least `6. Conversion from phpBB 2.0.x to phpBB 3.2.x`_ below for important, security related post-installation instructions, and also take note of `7. Important (security related) post-Install tasks for all installation methods`_ regarding anti-spam measures. +phpBB should now be available, please **MAKE SURE** you read at least `6. Conversion from phpBB 2.0.x to phpBB 3.2.x`_ below for important, security related post-installation instructions, and also take note of `7. Important (security related) post-Install tasks for all installation methods`_ regarding anti-spam measures. If you experienced problems or do not know how to proceed with any of the steps above please read the rest of this document. 2. Requirements =============== -phpBB 3.2.x has a few requirements which must be met before you are able to install and use it. +phpBB has a few requirements which must be met before you are able to install and use it. A webserver or web hosting account running on any major Operating System with support for PHP A SQL database system, **one of**: @@ -53,7 +53,7 @@ All .php, .sql, .cfg, .css, .js, .html, .htaccess and .txt files should be uploa phpBB comes supplied with British English as its standard language. However, a number of separate packs for different languages are available. If you are not a native English speaker you may wish to install one or more of these packages before continuing. The installation process below will allow you to select a default language from those available (you can, of course, change this default at a later stage). For more details on language packs, where to obtain them and how to install them please see :ref:`i-languages-internationalisation-i18n`. -Once all the files have been uploaded to your site, you should point your browser at this location with the addition of ``/install/``. For example, if your domain name is ``www.example.com`` and you placed the phpBB files in the directory ``/phpBB3`` off your web root you would enter ``http://www.example.com/phpBB3/install/`` or (alternatively) ``http://www.example.com/phpBB3/install/app.php`` into your browser. When you have done this, you should see the **phpBB Introduction** screen appear. +Once all the files have been uploaded to your site, you should point your browser at this location with the addition of ``/install/``. For example, if your domain name is ``www.example.com`` and you placed the phpBB files in the directory ``/phpBB`` off your web root you would enter ``http://www.example.com/phpBB/install/`` or (alternatively) ``http://www.example.com/phpBB/install/app.php`` into your browser. When you have done this, you should see the **phpBB Introduction** screen appear. 3.i. Introduction ------------------- @@ -166,7 +166,7 @@ To perform the update, either follow the instructions from the **Administration - Go to the `downloads page `_ and download the latest update package listed there, matching your current version. - Upload the uncompressed archive contents to your phpBB installation - only the ``install/`` and ``vendor/`` folders are required. Upload these folders in their entirety, retaining the file structure. - After the install folder is present, phpBB will go offline automatically. -- Point your browser to the install directory, for example ``http://www.example.com/phpBB3/install/`` +- Point your browser to the install directory, for example ``http://www.example.com/phpBB/install/`` - Choose the "Update" Tab and follow the instructions @@ -198,23 +198,23 @@ Delete the ``install/`` directory 6. Conversion from phpBB 2.0.x to phpBB 3.2.x ============================================= -This paragraph explains the steps necessary to convert your existing phpBB2 installation to phpBB3. +This paragraph explains the steps necessary to convert your existing phpBB2 installation to the latest phpBB. 6.i. Requirements before converting ----------------------------------- -Before converting, we heavily recommend you do a **full backup of your database and files!** If you are unsure how to achieve this, please ask your hosting provider for advice. You basically need to follow the instructions given for `3. New installation`_. Please **do not** overwrite any old files - install phpBB3 at a different location. +Before converting, we heavily recommend you do a **full backup of your database and files!** If you are unsure how to achieve this, please ask your hosting provider for advice. You basically need to follow the instructions given for `3. New installation`_. Please **do not** overwrite any old files - install phpBB in a different location. -Once you made a backup of everything and also have a brand new phpBB3 installation, you can now begin the conversion. +Once you made a backup of everything and also have a brand new phpBB installation, you can now begin the conversion. -Note that the conversion requires ``CREATE`` and ``DROP`` privileges for the phpBB3 database user account. +Note that the conversion requires ``CREATE`` and ``DROP`` privileges for the phpBB database user account. 6.ii. Converting ---------------- -To begin the conversion, visit the ``install/`` folder of your phpBB3 installation (the same as you have done for installing). Now you will see a new tab **Convert**. Click this tab. +To begin the conversion, visit the ``install/`` folder of your phpBB installation (the same as you have done for installing). Now you will see a new tab **Convert**. Click this tab. -As with install, the conversion is automated. Your previous 2.0.x database tables will not be changed and the original 2.0.x files will remain unaltered. The conversion is actually only filling your phpBB3 database tables and copying additional data over to your phpBB3 installation. This has the benefit that if something goes wrong, you are able to either re-run the conversion or continue a conversion, while your old board is still accessible. We really recommend that you disable your old installation while converting, else you may have inconsistent data after the conversion. +As with install, the conversion is automated. Your previous 2.0.x database tables will not be changed and the original 2.0.x files will remain unaltered. The conversion is actually only filling your phpBB database tables and copying additional data over to your phpBB installation. This has the benefit that if something goes wrong, you are able to either re-run the conversion or continue a conversion, while your old board is still accessible. We really recommend that you disable your old installation while converting, else you may have inconsistent data after the conversion. Please note that this conversion process may take quite some time and depending on your hosting provider this may result in it failing (due to web server resource limits or other timeout issues). If this is the case, you should ask your provider if they are willing to allow the convert script to temporarily exceed their limits (be nice and they will probably be quite helpful). If your host is unwilling to increase the limits to run the convertor, please see this article for performing the conversion on your local machine: `Knowledge Base - Offline Conversions `_ @@ -231,7 +231,7 @@ During the conversion, the search index is not created or transferred. This mean After verifying the settings in the ACP, you can delete the install directory to enable the board. The board will stay disabled until you do so. -Once you are pleased with your new installation, you may want to give it the name of your old installation, changing the directory name. With phpBB3 this is possible without any problems, but you may still want to check your cookie settings within the administration panel; in case your cookie path needs to be adjusted prior to renaming. +Once you are pleased with your new installation, you may want to give it the name of your old installation, changing the directory name. With phpBB this is possible without any problems, but you may still want to check your cookie settings within the administration panel; in case your cookie path needs to be adjusted prior to renaming. 6.iv. Common conversion problems -------------------------------- @@ -240,9 +240,9 @@ Once you are pleased with your new installation, you may want to give it the nam **http 500 / white pages** The conversion is a load-heavy procedure. Restrictions imposed by some server hosting providers can cause problems. The most common causes are: values too low for the PHP settings ``memory_limit`` and ``max_execution_time``. Limits on the allowed CPU time are also a frequent cause for such errors, as are limits on the number of database queries allowed. If you cannot change such settings, then contact your hosting provider or run the conversion procedure on a different computer. The phpBB.com forums are also an excellent location to ask for support. -**Password conversion** Due to the utf-8 based handling of passwords in phpBB3, it is not always possible to transfer all passwords. For passwords "lost in translation" the easiest workaround is to use the **I forgot my password** link on the login page. +**Password conversion** Due to the utf-8 based handling of passwords in phpBB, it is not always possible to transfer all passwords. For passwords "lost in translation" the easiest workaround is to use the **I forgot my password** link on the login page. -**Path to your former board** The convertor expects the relative path to your old board's files. So, for instance, if the old board is located at ``http://www.yourdomain.com/forum`` and the phpBB3 installation is located at ``http://www.yourdomain.com/phpBB3``, then the correct value would be ``../forum``. Note that the webserver user must be able to access the source installation's files. +**Path to your former board** The convertor expects the relative path to your old board's files. So, for instance, if the old board is located at ``http://www.yourdomain.com/forum`` and the phpBB installation is located at ``http://www.yourdomain.com/phpBB``, then the correct value would be ``../forum``. Note that the webserver user must be able to access the source installation's files. **Missing images** If your default board language's language pack does not include all images, then some images might be missing in your installation. Always use a complete language pack as default language. @@ -292,4 +292,4 @@ For **Windows** based servers using **IIS** there are ``web.config`` files alrea 8. Anti-Spam Measures ===================== -Like any online site that allows user input, your board could be subject to unwanted posts; often referred to as `forum spam `_. The vast majority of these attacks will be from automated computer programs known as `spambots `_. The attacks, generally, are not personal as the spammers are just trying to find accessible targets. phpBB has a number of anti-spam measures built in, including a range of CAPTCHAs. However, administrators are strongly urged to read and follow the advice for `Preventing Spam in phpBB `_ as soon as possible after completing the installation of your board. +Like any online site that allows user input, your board could be subject to unwanted posts; often referred to as `forum spam `_. The vast majority of these attacks will be from automated computer programs known as `spambots `_. The attacks, generally, are not personal as the spammers are just trying to find accessible targets. phpBB has a number of anti-spam measures built in, including a range of CAPTCHAs. However, administrators are strongly urged to read and follow the advice for `Preventing Spam in phpBB `_ as soon as possible after completing the installation of your board. diff --git a/development/testing/functional_testing.rst b/development/testing/functional_testing.rst index e985d97d..5c707a02 100644 --- a/development/testing/functional_testing.rst +++ b/development/testing/functional_testing.rst @@ -88,8 +88,8 @@ you will catch early. For more information what you can do with Goutte, check out the `GitHub project `_, -`Ryan Weaver's Goutte tutorial `_ -and `Symfony's testing documentation `_. +`Ryan Weaver's Goutte tutorial `_ +and `Symfony's testing documentation `_. Authentication -------------- diff --git a/development/testing/unit_testing.rst b/development/testing/unit_testing.rst index 4db1bce4..133d5263 100644 --- a/development/testing/unit_testing.rst +++ b/development/testing/unit_testing.rst @@ -123,7 +123,7 @@ Most important to know for db-tests is: 1. All data from the database is truncated first. 2. The data from the getDataSet function is loaded into the database. **No data from any other test is available!** -3. If you use a table that has a column which has no default value specified (such as text columns), be sure to specify them. (see `PHPBB3-10667 `_) +3. If you use a table that has a column which has no default value specified (such as text columns), be sure to specify them. (see `PHPBB3-10667 `_) Code of a DB-DataSet --------------------