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 45d49f30..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. @@ -59,9 +60,9 @@ # built documents. # # The short X.Y version. -version = '3.3' +version = 'master' # The full version, including alpha/beta/rc tags. -release = '3.3.x' +release = 'master' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -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 34e7000d..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. @@ -531,3 +526,519 @@ Parameters .. |br| raw:: html
+ +The boolean structure system +============================ + +Intro +----- + +This feature helps extension authors to edit SQL queries in an easy and quick way without the need to parse the SQL queries, most likely, using regex and complex text editing. +Instead of a single string, this allows editing the WHERE clause in an SQL query by adding, removing and editing php arrays. Using this method, finding the portion of the query to edit should be much more straightforward. + +If done correctly, incompatibilities between extensions that use the same SQL query can be averted. Where a regex match could easly force the author into making very complex matches. With this, finding and replacing the content is just tree-like transversal as they are only arrays. Compatibility between extensions becomes much easier. + +Althought this will definitely reduce the probability of inter-incompatibilities between extensions, it is not magic. This is just a tool that helps solving the same issue. + + +Main use-case ideals +-------------------- + +1. To flexibly the build of the WHERE clause in SQL queries +2. To ease, simplify and prevent errors when doing SQL query editing by phpBB's extensions + +Why not... +---------- + +1. Doctrine dbal -> The issue with Doctrine dbal is that its query builder is not ready for the 2nd major use case listed above. There is no way of altering an SQL query. If you want to alter something, you have to rebuild the whole SQL query. +2. Linq -> I didn't know the assistance of Linq until today. From what I searched, not only it has the same issue as Doctrine, while also its interface is unnecessarily complex for the common folk who just wants to change a small amount of information. + + +The Data structure +------------------ + +This builder uses a tree-like information organization for the boolean comparisons in SQL queries. +Each node of such tree is a php array. +Each node can have one of 3 formats: + +type1 +^^^^^ + +The 1st type contains 3 elements: + +Left hand, operator, right hand. +E.g. + +.. code-block:: php + + ['f.forum_id', '=', 1] + ['f.forum_id', '<>', 1] + ['f.forum_id', 'IN', []] + ['f.forum_id', 'IN', [1,2,5,6,7]] + ['f.forum_id', 'NOT_IN', [1,2,5,6,7]] + ['f.forum_id', 'IS', NULL] + +For the operator, there are 6 special values (everything else is taken literally): + +1. IN +2. NOT_IN +3. LIKE +4. NOT_LIKE +5. IS +6. IS_NOT + +All of them are special because they call the dbal's methods to process the data. +For example, if you use the **IN** operator, it calls $db->sql_in_set() with the right hand data. + +type2 +^^^^^ + +The 2nd type is variable length. It is identified by having the string 'AND', 'OR' or 'NOT' in the first position of the array. + +The first element contains the boolean operator that is used to join together all its other elements. + +E.g. + +.. code-block:: php + + ['OR', + ['t.forum_id', '=', 3], + ['t.topic_type', '=', 0], + ['t.topic_id', 'IN', [2,3,4]], + ) + +which outputs (after reindenting) + +.. code-block:: SQL + + t.forum_id = 3 OR + t.topic_type = 0 OR + t.topic_id IN (2, 3, 4) + + +type3 +^^^^^ + +The 3rd type has 5 elements +Left hand, operator, sub query operator, sub query SELECT type, the sub query. + +This is used when you require a subquery in your DB query. +Essentially, what this does is that it will call sql_build_query() recursively with the 4th and the 5th elements. + +.. code-block:: php + + ['f.forum_id', '=', 'ANY', 'SELECT', [ + 'SELECT' => [/*...*/], + 'FROM' => [/*...*/], + ]] + + ['f.forum_id', '', 'IN', 'SELECT', [ + 'SELECT' => [/*...*/], + 'FROM' => [/*...*/], + ]] + +Why arrays? +----------- + +The motivation to use arrays comes from the needs: + +1. This is information that is going to be used quite a lot. + 1.1. In the ideal case, every SQL query with either an ON or a WHERE clause (just about all) will use this. +2. The implementation on which this works on top of already uses arrays. +3. Editing arrays is a quite trivial task for any piece of code. + +Why not Objects? +^^^^^^^^^^^^^^^^ + +1. Tranversing Objects forming a tree is **seriously slow** in php. + 1.1. This wouldn't much be noticed on vanilla phpBB but, as you add extensions, it would easily be dead slow. +2. Doing this with immutable objects is completely unviable. + 2.1. It would require the code that manipulates it to know how to rebuild everything related for almost any change. +3. Mutable objects with an easy-enough-to-use API is hell to design. + 3.1. How would a script know how to specify the changes that are required to make without using a complex API? + 3.2. How would a user script swiftly test if a query has the correct format? + +Mostly due to those reasons above arrays was decided as the medium. + +How to use +---------- + +This system is used when building queries using the db's sql_build_query() method. + +While building the array to send to it as the 2nd parameter, when writing the WHERE clause, you may use this system instead of simply typing a string or making your own accumulator of conditionals. + +For the sake of the examples below, I will simulate an execution that exists in phpBB and assume that the query has to go through an event that does a small change to it. + + +How to use in phpBB +------------------- +In the ideal situation, all DB queries that may use multiple stages where SQL data is manipulated or changed should use this, specially if they also go through an event. + + +Translate SQL to the structured conditional +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Here's a step-by-step guide to transform a query made using a string into the format that this feature uses. + +Now imagine you want something like this (source: viewforum.php:277): + +.. code-block:: php + + $sql = 'SELECT COUNT(topic_id) AS num_topics + FROM ' . TOPICS_TABLE . " + WHERE forum_id = $forum_id + AND (topic_last_post_time >= $min_post_time + OR topic_type = " . POST_ANNOUNCE . ' + OR topic_type = ' . POST_GLOBAL . ') + AND ' . $phpbb_content_visibility->get_visibility_sql('topic', $forum_id); + + +Looks quite direct to the point, right? +OK, **step1**, prepare it for sql_build_query(); + +According to the manual for this transformation, it should look like this: + + +.. code-block:: php + + $sql_ary = [ + 'SELECT' => 'COUNT(topic_id) AS num_topics', + 'FROM' => [ + TOPICS_TABLE => '', + ], + 'WHERE' => "forum_id = $forum_id + AND (topic_last_post_time >= $min_post_time + OR topic_type = " . POST_ANNOUNCE . ' + OR topic_type = ' . POST_GLOBAL . ') + AND ' . $phpbb_content_visibility->get_visibility_sql('topic', $forum_id), + ]; + + $db->sql_build_query('SELECT', $sql_ary); + +That's fine and all but it does not use this processor yet. +**Step 2** +Now to focus on the WHERE clause only + +Hum... Let's see... There's a set of AND's to join in. Let's start there. + +.. code-block:: php + + // ... + 'WHERE' => ['AND, + "forum_id = $forum_id", + "(topic_last_post_time >= $min_post_time + OR topic_type = " . POST_ANNOUNCE . ' + OR topic_type = ' . POST_GLOBAL . ')', + $phpbb_content_visibility->get_visibility_sql('topic', $forum_id) + ], + // ... + +Inside the set of AND's, one of them is a set of OR's. + +.. code-block:: php + + // ... + 'WHERE' => ['AND, + "forum_id = $forum_id", + ['OR', + "topic_last_post_time >= $min_post_time", + 'topic_type = ' . POST_ANNOUNCE, + 'topic_type = ' . POST_GLOBAL, + ), + $phpbb_content_visibility->get_visibility_sql('topic', $forum_id) + ), + // ... + +There! Better! But it still isn't that easy to work with. There's a string for each comparison. BUT! If I use the type1 array mentioned above, I can separate each one of those into a single thing! In this case... + +.. code-block:: php + + // ... + 'WHERE' => ['AND, + ['forum_id', '=', $forum_id], + ['OR', + ['topic_last_post_time', '>=', $min_post_time], + ['topic_type', '=', POST_ANNOUNCE], + ['topic_type', '=', POST_GLOBAL], + ), + [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)], + // ... + +There you go! No variable interpolation, no explicit string concatenation, in case of a requirement to build it or change it later, it becomes a very straightforward task (see next section) and all data is properly escaped. + +Just for the last piece of code in this section, here's how the full SQL query should be written when using this system: + + +.. code-block:: php + + $sql_ary = [ + 'SELECT' => 'COUNT(topic_id) AS num_topics', + 'FROM' => [ + TOPICS_TABLE => '', + ], + 'WHERE' => ['AND, + ['forum_id', '=', $forum_id], + ['OR', + ['topic_last_post_time', '>=', $min_post_time], + ['topic_type', '=', POST_ANNOUNCE], + ['topic_type', '=', POST_GLOBAL], + ], + [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)], + ], + ]; + + $db->sql_build_query('SELECT', $sql_ary); + + +Modify the structured conditional in an extension +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +One of the major reasons why this feature is designed in this very way is mostly because of what is exemplified in this section. +Same as the sub-section above, I will present you practical example(s) on how to use this feature. +Piking up the code above as an example: + +.. code-block:: php + + $sql = [ + 'SELECT' => 'COUNT(topic_id) AS num_topics', + 'FROM' => [ + TOPICS_TABLE => '', + ], + 'WHERE' => ['AND, + ['forum_id', '=', $forum_id], + ['OR', + ['topic_last_post_time', '>=', $min_post_time], + ['topic_type', '=', POST_ANNOUNCE], + ['topic_type', '=', POST_GLOBAL], + ), + [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)] + ], + ]; + + +Imagine you are building an extension that requires modifying that query above. For example, you want to make topic_last_post_time as a forced requirement for this query. +In other words, you want the query to be like this: + +.. code-block:: php + + $sql = [ + 'SELECT' => 'COUNT(topic_id) AS num_topics', + 'FROM' => [ + TOPICS_TABLE => '', + ], + 'WHERE' => ['AND, + ['forum_id', '=', $forum_id], + ['topic_last_post_time', '>=', $min_post_time], + [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)], + ], + ]; + +Just as a good practice and to help other extension writers to modify this query in an easier way, let's make it like this instead: + +.. code-block:: php + + $sql = [ + 'SELECT' => 'COUNT(topic_id) AS num_topics', + 'FROM' => [ + TOPICS_TABLE => '', + ], + 'WHERE' => ['AND, + ['forum_id', '=', $forum_id], + ['OR', + ['topic_last_post_time', '>=', $min_post_time], + ], + [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)], + ], + ]; + +Do notice that I kept the OR clause. This is just so that these changes have as little chance as possible to break other extensions. +Anyway, moving on. + +In your function: + +.. code-block:: php + + function eventGrabber($event) + { + +You will have an $event['sql'] which will contain the query. +Below, I use nesting of "if", if you prefer, you may use exceptions instead. +In order to access what we want, we can do it like this: + +.. code-block:: php + + // May be required by PHP + $sql = $event['sql']; + // Is the element I expect there? + if(isset($sql['WHERE'][2][0])) + { + if(is_array($sql['WHERE'][2])) + { + if($sql['WHERE'][2][0] === 'OR') + { + // This should be the array with the OR I wanted + if(isset($sql['WHERE'][2][0][1]) && $sql['WHERE'][2][0][1][0] === 'topic_last_post_time') + { + // Confirmed to be what I want it to be! + // this array_slice() will remove the elements after the above-mentioned topic_last_post_time + $sql['WHERE'][2][0][1] = array_slice($sql['WHERE'][2][0][1], 1); + + $event['sql'] = $sql; + return; + } + } + else + { + // For example, write code to log this happened so that an admin can help you making your + // extension compatible with other extensions or even for you to be warned about phpBB changes. + } + } + else + { + // For example, write code to log this happened so that an admin can help you making your + // extension compatible with other extensions or even for you to be warned about phpBB changes. + } + } + else + { + // For example, write code to log this happened so that an admin can help you making your + // extension compatible with other extensions or even for you to be warned about phpBB changes. + } + + + +If you are thinking: +Eh?!??!? That's too complicated... How is this better than before?!?! + +Well, I'm just safeguarding myself above. I'm just doing in a way to make sure it will surely work. +If you don't feel like it, however, then this is enough: + +.. code-block:: php + + function myEventListener($event) + { + $sql = $event['sql']; + $sql['WHERE'][2][0][1] = array_slice($sql['WHERE'][2][0][1], 1); + $event['sql'] = $sql; + } + +Or to protect yourself slightly: + +.. code-block:: php + + function myEventListener($event) + { + $sql = $event['sql']; + if(!empty($sql['WHERE'][2][0][1]) && is_array($sql['WHERE'][2][0][1])) + { + $sql['WHERE'][2][0][1] = array_slice($sql['WHERE'][2][0][1], 1); + } + else + { + // For example, write code to log this happened so that an admin can help you making your + // extension compatible with other extensions or even for you to be warned about phpBB changes. + } + $event['sql'] = $sql; + } + +I've shown you the above one first because I wanted you to experience the will to do everybody's work the easiest and most flexible way. + +**Example 2:** + +Now imagining that you want to add a condition to the OR statement list. +For example, you want sticky posts to not be counted. + +The long/self.protected way uses just about the same formula as 3 samples above. +The short way is about as much as this: + +.. code-block:: php + + function myEventListener($event) + { + $sql = $event['sql']; + if(!empty($sql['WHERE'][2][0][1]) && is_array($sql['WHERE'][2][0][1])) + { + $sql['WHERE'][2][0][1][] = ['topic_type', '=', POST_STICKY]; + } + else + { + // For example, write code to log this happened so that an admin can help you making your + // extension compatible with other extensions or even for you to be warned about phpBB changes. + } + $event['sql'] = $sql; + } + +... And you are done. No Regex, no need to write down your own 'OR' or anything like that. +As a bonus, if what you write follows basic rules on how SQL is written, it is guaranteed that the output will be valid SQL. + +Usage examples +-------------- +Here I present code samples that exemplify how to use this system. + +In phpBB's code +^^^^^^^^^^^^^^^ + +.. code-block:: php + + $db->sql_build_query('SELECT', [ + 'SELECT' => ['f.forum_id', 'f.forum_title'], + 'FROM' => [ + FORUMS_TABLE => 'f', + TOPICS_TABLE => 't', + ], + 'WHERE' => [ + 'AND', + ['t.topic_poster', '=', 1], + ['f.forum_id', '>=', 'ALL', 'SELECT', [ + 'SELECT' => ['t.forum_id'], + 'FROM' => [TOPICS_TABLE => 't'], + 'WHERE' => ['t.topic_poster', '=', 1], + ], + ], + ); + +.. code-block:: php + + ['OR', + ['t.forum_id', '=', 3], + ['t.topic_type', '=', 0], + ) + +.. code-block:: php + + ['AND, + ['t.forum_id', '=', 3], + ['t.topic_type', '=', 0], + ['t.topic_id', '>', 5], + ['t.topic_poster', '<>', 5], + ), + +.. code-block:: php + + ['AND, + ['t.forum_id', '=', 3], + ['NOT', + ['t.topic_type', '=', 0], + ], + ['t.topic_id', '>', 5], + ['t.topic_poster', '<>', 5], + ], + +.. code-block:: php + + t.forum_id = 3 + AND NOT ( t.topic_type = 0 ) + AND t.topic_id > 5 + AND t.topic_poster <> 5 + +In phpBB's extensions code +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: php + + function myEventListener($event) + { + $sql = $event['sql']; + $sql['WHERE'][2][0][1] = array_slice($sql['WHERE'][2][0][1], 1); + $event['sql'] = $sql; + } + +More will come as people submit more useful examples. diff --git a/development/db/structured_conditionals.rst b/development/db/structured_conditionals.rst deleted file mode 100644 index 8c5323fa..00000000 --- a/development/db/structured_conditionals.rst +++ /dev/null @@ -1,524 +0,0 @@ -============================ -The boolean structure system -============================ - -Intro -===== - -This feature helps extension authors to edit SQL queries in an easy and quick way without the need to parse the SQL queries, most likely, using regex and complex text editing. -Instead of a single string, this allows editing the WHERE clause in an SQL query by adding, removing and editing php arrays. Using this method, finding the portion of the query to edit should be much more straightforward. - -If done correctly, incompatibilities between extensions that use the same SQL query can be averted. Where a regex match could easly force the author into making very complex matches. With this, finding and replacing the content is just tree-like transversal as they are only arrays. Compatibility between extensions becomes much easier. - -Althought this will definitely reduce the probability of inter-incompatibilities between extensions, it is not magic. This is just a tool that helps solving the same issue. - - -Main use-case ideals -==================== - -1. To flexibly the build of the WHERE clause in SQL queries -2. To ease, simplify and prevent errors when doing SQL query editing by phpBB's extensions - -Why not... -========== - -1. Doctrine dbal -> The issue with Doctrine dbal is that its query builder is not ready for the 2nd major use case listed above. There is no way of altering an SQL query. If you want to alter something, you have to rebuild the whole SQL query. -2. Linq -> I didn't know the assistance of Linq until today. From what I searched, not only it has the same issue as Doctrine, while also its interface is unnecessarily complex for the common folk who just wants to change a small amount of information. - - -The Data structure -================== - -This builder uses a tree-like information organization for the boolean comparisons in SQL queries. -Each node of such tree is a php array. -Each node can have one of 3 formats: - -type1 ------ - -The 1st type contains 3 elements: - -Left hand, operator, right hand. -E.g. - -.. code-block:: php - - ['f.forum_id', '=', 1] - ['f.forum_id', '<>', 1] - ['f.forum_id', 'IN', []] - ['f.forum_id', 'IN', [1,2,5,6,7]] - ['f.forum_id', 'NOT_IN', [1,2,5,6,7]] - ['f.forum_id', 'IS', NULL] - -For the operator, there are 6 special values (everything else is taken literally): - -1. IN -2. NOT_IN -3. LIKE -4. NOT_LIKE -5. IS -6. IS_NOT - -All of them are special because they call the dbal's methods to process the data. -For example, if you use the **IN** operator, it calls $db->sql_in_set() with the right hand data. - -type2 ------ - -The 2nd type is variable length. It is identified by having the string 'AND', 'OR' or 'NOT' in the first position of the array. - -The first element contains the boolean operator that is used to join together all its other elements. - -E.g. - -.. code-block:: php - - ['OR', - ['t.forum_id', '=', 3], - ['t.topic_type', '=', 0], - ['t.topic_id', 'IN', [2,3,4]], - ) - -which outputs (after reindenting) - -.. code-block:: SQL - - t.forum_id = 3 OR - t.topic_type = 0 OR - t.topic_id IN (2, 3, 4) - - -type3 ------ - -The 3rd type has 5 elements -Left hand, operator, sub query operator, sub query SELECT type, the sub query. - -This is used when you require a subquery in your DB query. -Essentially, what this does is that it will call sql_build_query() recursively with the 4th and the 5th elements. - -.. code-block:: php - - ['f.forum_id', '=', 'ANY', 'SELECT', [ - 'SELECT' => [/*...*/], - 'FROM' => [/*...*/], - ]] - - ['f.forum_id', '', 'IN', 'SELECT', [ - 'SELECT' => [/*...*/], - 'FROM' => [/*...*/], - ]] - -Why arrays? -=========== - -The motivation to use arrays comes from the needs: - -1. This is information that is going to be used quite a lot. - 1.1. In the ideal case, every SQL query with either an ON or a WHERE clause (just about all) will use this. -2. The implementation on which this works on top of already uses arrays. -3. Editing arrays is a quite trivial task for any piece of code. - -Why not Objects? ----------------- - -1. Tranversing Objects forming a tree is **seriously slow** in php. - 1.1. This wouldn't much be noticed on vanilla phpBB but, as you add extensions, it would easily be dead slow. -2. Doing this with immutable objects is completely unviable. - 2.1. It would require the code that manipulates it to know how to rebuild everything related for almost any change. -3. Mutable objects with an easy-enough-to-use API is hell to design. - 3.1. How would a script know how to specify the changes that are required to make without using a complex API? - 3.2. How would a user script swiftly test if a query has the correct format? - -Mostly due to those reasons above arrays was decided as the medium. - -How to use -========== - -This system is used when building queries using the db's sql_build_query() method. - -While building the array to send to it as the 2nd parameter, when writing the WHERE clause, you may use this system instead of simply typing a string or making your own accumulator of conditionals. - -For the sake of the examples below, I will simulate an execution that exists in phpBB and assume that the query has to go through an event that does a small change to it. - - -How to use in phpBB -=================== -In the ideal situation, all DB queries that may use multiple stages where SQL data is manipulated or changed should use this, specially if they also go through an event. - - -Translate SQL to the structured conditional -------------------------------------------- -Here's a step-by-step guide to transform a query made using a string into the format that this feature uses. - -Now imagine you want something like this (source: viewforum.php:277): - -.. code-block:: php - - $sql = 'SELECT COUNT(topic_id) AS num_topics - FROM ' . TOPICS_TABLE . " - WHERE forum_id = $forum_id - AND (topic_last_post_time >= $min_post_time - OR topic_type = " . POST_ANNOUNCE . ' - OR topic_type = ' . POST_GLOBAL . ') - AND ' . $phpbb_content_visibility->get_visibility_sql('topic', $forum_id); - - -Looks quite direct to the point, right? -OK, **step1**, prepare it for sql_build_query(); - -According to the manual for this transformation, it should look like this: - - -.. code-block:: php - - $sql_ary = [ - 'SELECT' => 'COUNT(topic_id) AS num_topics', - 'FROM' => [ - TOPICS_TABLE => '', - ], - 'WHERE' => "forum_id = $forum_id - AND (topic_last_post_time >= $min_post_time - OR topic_type = " . POST_ANNOUNCE . ' - OR topic_type = ' . POST_GLOBAL . ') - AND ' . $phpbb_content_visibility->get_visibility_sql('topic', $forum_id), - ]; - - $db->sql_build_query('SELECT', $sql_ary); - -That's fine and all but it does not use this processor yet. -**Step 2** -Now to focus on the WHERE clause only - -Hum... Let's see... There's a set of AND's to join in. Let's start there. - -.. code-block:: php - - // ... - 'WHERE' => ['AND, - "forum_id = $forum_id", - "(topic_last_post_time >= $min_post_time - OR topic_type = " . POST_ANNOUNCE . ' - OR topic_type = ' . POST_GLOBAL . ')', - $phpbb_content_visibility->get_visibility_sql('topic', $forum_id) - ], - // ... - -Inside the set of AND's, one of them is a set of OR's. - -.. code-block:: php - - // ... - 'WHERE' => ['AND, - "forum_id = $forum_id", - ['OR', - "topic_last_post_time >= $min_post_time", - 'topic_type = ' . POST_ANNOUNCE, - 'topic_type = ' . POST_GLOBAL, - ), - $phpbb_content_visibility->get_visibility_sql('topic', $forum_id) - ), - // ... - -There! Better! But it still isn't that easy to work with. There's a string for each comparison. BUT! If I use the type1 array mentioned above, I can separate each one of those into a single thing! In this case... - -.. code-block:: php - - // ... - 'WHERE' => ['AND, - ['forum_id', '=', $forum_id], - ['OR', - ['topic_last_post_time', '>=', $min_post_time], - ['topic_type', '=', POST_ANNOUNCE], - ['topic_type', '=', POST_GLOBAL], - ), - [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)], - // ... - -There you go! No variable interpolation, no explicit string concatenation, in case of a requirement to build it or change it later, it becomes a very straightforward task (see next section) and all data is properly escaped. - -Just for the last piece of code in this section, here's how the full SQL query should be written when using this system: - - -.. code-block:: php - - $sql_ary = [ - 'SELECT' => 'COUNT(topic_id) AS num_topics', - 'FROM' => [ - TOPICS_TABLE => '', - ], - 'WHERE' => ['AND, - ['forum_id', '=', $forum_id], - ['OR', - ['topic_last_post_time', '>=', $min_post_time], - ['topic_type', '=', POST_ANNOUNCE], - ['topic_type', '=', POST_GLOBAL], - ], - [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)], - ], - ]; - - $db->sql_build_query('SELECT', $sql_ary); - - -Modify the structured conditional in an extension -------------------------------------------------- -One of the major reasons why this feature is designed in this very way is mostly because of what is exemplified in this section. -Same as the sub-section above, I will present you practical example(s) on how to use this feature. -Piking up the code above as an example: - -.. code-block:: php - - $sql = [ - 'SELECT' => 'COUNT(topic_id) AS num_topics', - 'FROM' => [ - TOPICS_TABLE => '', - ], - 'WHERE' => ['AND, - ['forum_id', '=', $forum_id], - ['OR', - ['topic_last_post_time', '>=', $min_post_time], - ['topic_type', '=', POST_ANNOUNCE], - ['topic_type', '=', POST_GLOBAL], - ), - [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)] - ], - ]; - - -Imagine you are building an extension that requires modifying that query above. For example, you want to make topic_last_post_time as a forced requirement for this query. -In other words, you want the query to be like this: - -.. code-block:: php - - $sql = [ - 'SELECT' => 'COUNT(topic_id) AS num_topics', - 'FROM' => [ - TOPICS_TABLE => '', - ], - 'WHERE' => ['AND, - ['forum_id', '=', $forum_id], - ['topic_last_post_time', '>=', $min_post_time], - [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)], - ], - ]; - -Just as a good practice and to help other extension writers to modify this query in an easier way, let's make it like this instead: - -.. code-block:: php - - $sql = [ - 'SELECT' => 'COUNT(topic_id) AS num_topics', - 'FROM' => [ - TOPICS_TABLE => '', - ], - 'WHERE' => ['AND, - ['forum_id', '=', $forum_id], - ['OR', - ['topic_last_post_time', '>=', $min_post_time], - ], - [$phpbb_content_visibility->get_visibility_sql('topic', $forum_id)], - ], - ]; - -Do notice that I kept the OR clause. This is just so that these changes have as little chance as possible to break other extensions. -Anyway, moving on. - -In your function: - -.. code-block:: php - - function eventGrabber($event) - { - -You will have an $event['sql'] which will contain the query. -Below, I use nesting of "if", if you prefer, you may use exceptions instead. -In order to access what we want, we can do it like this: - -.. code-block:: php - - // May be required by PHP - $sql = $event['sql']; - // Is the element I expect there? - if(isset($sql['WHERE'][2][0])) - { - if(is_array($sql['WHERE'][2])) - { - if($sql['WHERE'][2][0] === 'OR') - { - // This should be the array with the OR I wanted - if(isset($sql['WHERE'][2][0][1]) && $sql['WHERE'][2][0][1][0] === 'topic_last_post_time') - { - // Confirmed to be what I want it to be! - // this array_slice() will remove the elements after the above-mentioned topic_last_post_time - $sql['WHERE'][2][0][1] = array_slice($sql['WHERE'][2][0][1], 1); - - $event['sql'] = $sql; - return; - } - } - else - { - // For example, write code to log this happened so that an admin can help you making your - // extension compatible with other extensions or even for you to be warned about phpBB changes. - } - } - else - { - // For example, write code to log this happened so that an admin can help you making your - // extension compatible with other extensions or even for you to be warned about phpBB changes. - } - } - else - { - // For example, write code to log this happened so that an admin can help you making your - // extension compatible with other extensions or even for you to be warned about phpBB changes. - } - - - -If you are thinking: -Eh?!??!? That's too complicated... How is this better than before?!?! - -Well, I'm just safeguarding myself above. I'm just doing in a way to make sure it will surely work. -If you don't feel like it, however, then this is enough: - -.. code-block:: php - - function myEventListener($event) - { - $sql = $event['sql']; - $sql['WHERE'][2][0][1] = array_slice($sql['WHERE'][2][0][1], 1); - $event['sql'] = $sql; - } - -Or to protect yourself slightly: - -.. code-block:: php - - function myEventListener($event) - { - $sql = $event['sql']; - if(!empty($sql['WHERE'][2][0][1]) && is_array($sql['WHERE'][2][0][1])) - { - $sql['WHERE'][2][0][1] = array_slice($sql['WHERE'][2][0][1], 1); - } - else - { - // For example, write code to log this happened so that an admin can help you making your - // extension compatible with other extensions or even for you to be warned about phpBB changes. - } - $event['sql'] = $sql; - } - -I've shown you the above one first because I wanted you to experience the will to do everybody's work the easiest and most flexible way. - -**Example 2:** - -Now imagining that you want to add a condition to the OR statement list. -For example, you want sticky posts to not be counted. - -The long/self.protected way uses just about the same formula as 3 samples above. -The short way is about as much as this: - -.. code-block:: php - - function myEventListener($event) - { - $sql = $event['sql']; - if(!empty($sql['WHERE'][2][0][1]) && is_array($sql['WHERE'][2][0][1])) - { - $sql['WHERE'][2][0][1][] = ['topic_type', '=', POST_STICKY]; - } - else - { - // For example, write code to log this happened so that an admin can help you making your - // extension compatible with other extensions or even for you to be warned about phpBB changes. - } - $event['sql'] = $sql; - } - -... And you are done. No Regex, no need to write down your own 'OR' or anything like that. -As a bonus, if what you write follows basic rules on how SQL is written, it is guaranteed that the output will be valid SQL. - -Usage examples -============== -Here I present code samples that exemplify how to use this system. - -In phpBB's code ---------------- - - -.. code-block:: php - - $db->sql_build_query('SELECT', [ - 'SELECT' => ['f.forum_id', 'f.forum_title'], - 'FROM' => [ - FORUMS_TABLE => 'f', - TOPICS_TABLE => 't', - ], - 'WHERE' => [ - 'AND', - ['t.topic_poster', '=', 1], - ['f.forum_id', '>=', 'ALL', 'SELECT', [ - 'SELECT' => ['t.forum_id'], - 'FROM' => [TOPICS_TABLE => 't'], - 'WHERE' => ['t.topic_poster', '=', 1], - ], - ], - ); - - - -.. code-block:: php - - ['OR', - ['t.forum_id', '=', 3], - ['t.topic_type', '=', 0], - ) - -.. code-block:: php - - ['AND, - ['t.forum_id', '=', 3], - ['t.topic_type', '=', 0], - ['t.topic_id', '>', 5], - ['t.topic_poster', '<>', 5], - ), - -.. code-block:: php - - ['AND, - ['t.forum_id', '=', 3], - ['NOT', - ['t.topic_type', '=', 0], - ], - ['t.topic_id', '>', 5], - ['t.topic_poster', '<>', 5], - ], - - -.. code-block:: php - - t.forum_id = 3 - AND NOT ( t.topic_type = 0 ) - AND t.topic_id > 5 - AND t.topic_poster <> 5 - - -In phpBB's extensions code --------------------------- - -.. code-block:: php - - function myEventListener($event) - { - $sql = $event['sql']; - $sql['WHERE'][2][0][1] = array_slice($sql['WHERE'][2][0][1], 1); - $event['sql'] = $sql; - } - - - - -More will come as people submit more useful examples diff --git a/development/development/css/css_guidelines.rst b/development/development/css/css_guidelines.rst new file mode 100644 index 00000000..def8eae9 --- /dev/null +++ b/development/development/css/css_guidelines.rst @@ -0,0 +1,334 @@ +Introduction +------------ + +CSS is not a pretty language. While it is simple to learn and get started with, it soon becomes problematic at any reasonable scale. There isn’t much we can do to change how CSS works, but we can make changes to the way we author and structure it. + +There are a variety of techniques we must employ in order to satisfy these goals, and CSS Guidelines is a document of recommendations and approaches that will help us to do so. + +The first part of this will deal with syntax, formatting, and CSS anatomy. The second part will deal with approach, mindframe, and attitude toward writing/architecting CSS. + +Syntax and Formatting +--------------------- + +One of the simplest forms of a styleguide is a set of rules regarding syntax and formatting. Having a standard way of writing (literally writing) CSS means that code will always look and feel familiar to all members of the team. + +Further, code that looks clean feels clean. It is a much nicer environment to work in, and prompts other team members to maintain the standard of cleanliness that they found. Ugly code sets a bad precedent. + +The chosen code format must ensure that code is: easy to read, easy to clearly comment, minimizes the chance of accidentally introducing errors, and results in useful diffs and blames. + +At a very high-level, we want + +- Tab (4 space width) indents +- 80 character wide columns +- multi-line CSS +- a meaningful use of comments & whitespace + +Anatomy of a Ruleset +~~~~~~~~~~~~~~~~~~~~ + +Before we discuss how we write out our rulesets, let’s first familiarize ourselves with the relevant terminology: + +The following is a ``[ruleset]`` + +.. code-block:: + + [selector], + [selector] { + [property]: [value]; | + [property]: [value]; | <- [declaration-block] + [property]: [value]; | + [<--declaration--->] + } + +Formating +~~~~~~~~~ + +- Use one discrete selector per line in multi-selector rulesets +- The opening brace (``{``) should be on the same line as our last selector +- Include a single space before the opening brace (``{``) +- Include properties and values on the same line +- Include one declaration per line in a declaration block +- Use one level of indentation for each declaration +- Include a single space after the colon (``:``) of a declaration +- Use lowercase hex values, e.g. #abc123 +- Use quotes consistently. **Preference double quotes**, e.g. ``content: ""`` +- Always quote attribute values in selectors, e.g. ``input[type="checkbox"]`` +- Avoid specifying units for zero-values, e.g. ``margin: 0`` +- Always use leading zeros, e.g. ``font-size: 0.875rem`` +- Include a space after each comma (``,``) in comma-separated property or function values +- Include a semi-colon (``;``) at the end of every declaration including the last in a declaration block +- Place the closing brace (``}``) of a ruleset in the same column as the first character of the ruleset, on its own line +- Separate each ruleset by a blank line + +Example: + +.. code:: scss + + .selector-1, + .selector-2, + .selector-3[type="text"] { + -webkit-box-sizing: border-box; + -moz-box-sizing: border-box; + box-sizing: border-box; + display: block; + padding: 0; + font-family: helvetica, arial, sans-serif; + color: #333333; + background: #ffffff; + background: linear-gradient(#ffffff, rgba(0, 0, 0, 0.8)); + } + + .selector-a, + .selector-b { + padding: 10px; + } + +This format seems to be the largely universal standard (except for variations in indentation). + +As such, the following would be incorrect: + +.. code:: scss + + .foo, .foo-bar, .baz + { + display:block; + background-color:green; + color:red } + +Problems here include + +- 2 spaces instead of tabs (4 space width) +- selectors on the same line +- the opening brace (``{``) on its own line +- the closing brace (``}``) does not sit on its own line +- the last semi-colon (``;``) is missing +- no spaces after colons (``:``) + +Multi-line CSS +~~~~~~~~~~~~~~ + +CSS should be written across multiple lines, except in very specific circumstances. There are a number of benefits to this: + +- A reduced chance of merge conflicts, because each piece of functionality exists on its own line. +- More ‘truthful’ and reliable ``diffs``, because one line only ever carries one change. + +Exceptions to this rule should be fairly apparent, such as similar rulesets that only carry one declaration each, for example: + +.. code:: css + + .icon { + display: inline-block; + width: 16px; + height: 16px; + background-image: url(/img/sprite.svg); + } + + .icon-home { background-position: 0 0; } + .icon-person { background-position: -16px 0; } + .icon-files { background-position: 0 -16px; } + .icon-settings { background-position: -16px -16px; } + +These types of ruleset benefit from being single-lined because + +- they still conform to the one-reason-to-change-per-line rule +- they share enough similarities that they don’t need to be read as thoroughly as other rulesets - there is more benefit in being able to scan their selectors, which are of more interest to us in these cases + +Declaration order +~~~~~~~~~~~~~~~~~ + +declarations are to be consistently ordered by related property declarations following the order + +#. Typographic +#. Visual +#. Positioning +#. Box model +#. Misc + +Example: + +.. code:: scss + + .declaration-order { + /* Typography */ + font: normal 13px "Helvetica Neue", sans-serif; + line-height: 1.5; + text-align: center; + + /* Visual */ + background-color: #f5f5f5; + border: 1px solid #e5e5e5; + border-radius: 3px; + color: #333333; + + /* Positioning */ + position: absolute; + z-index: 100; + top: 0; + right: 0; + bottom: 0; + left: 0; + + /* Box-model */ + display: block; + float: right; + width: 100px; + height: 100px; + margin: 0; + padding: 8px; + + /* Misc */ + content: "-"; + } + +Proper use of units +~~~~~~~~~~~~~~~~~~~ + +Because CSS allows for the use of several different unit types, it can get confusing when using more than one type of unit throughout. For that reason it's beneficial to stick to a strict set of rules for what unit types are to be used for certain selectors. + +Furthermore there are certain reasons to use or avoid using specific units in certain places. + +EM +^^ + +The ‘em’ unit. This is a very problematic unit which wreaks havoc on countless projects due to the way it's calculated. As such, this unit type must be avoid except for very very minimal use cases. We prevent the use of ``em`` except for ``letter-spacing`` & ``word-spacing``. It is also used for icon sizing, but that is an edge case. + +Line-heights +^^^^^^^^^^^^ + +All line-heights are to be specified as ``unitless`` in order to prevent improper inheritance. By nature when using units with line-heights, the children inherit by default. This can lead to unwanted effects and bloated code. A ``sass`` function called ``unitless`` is provided which will convert px values for convenience, but for clarity the math is simply + +.. code:: scss + + line-height: (desired px value) / (current elements font-size) + +Font-size +^^^^^^^^^ + +All ``font-size`` should be specified either in ``px`` or ``%`` in small cases. All px values will be converted to ``rem`` during the build process as ``rem`` provides for control in responsive situations. + +Margins & Paddings +^^^^^^^^^^^^^^^^^^ + +All ``margin`` & ``padding`` should be specified in ``px`` values or ``%``. All ``px`` values will be converted to ``rem`` during the build process as ``rem`` provides for control in responsive situations. + +PX +^^ + +All ``px`` will be whole numbers. Browsers do not render ``px`` in fractional values despite what your browser may say it is. Only calculated values will display as fractional ``px``. For clarification a calculated value would be units like ``rem``, ``em``, ``%``, & even ``unitless`` as is the case with line-heights. + +Dimensions +^^^^^^^^^^ + +All dimensional values ``width``, ``min-width``, ``height``, & ``min-height`` should be specified in ``px`` or ``%``. A case can be made for ``vw`` & ``vh``, but they are still on the fringe of browser acceptance, as such fallbacks in ``px`` or ``%`` are required. These values will remain as px if specified. This is done as ``height`` is more effectively and appropriately controlled via the ``line-height`` property, and ``width`` is better specified using the objects box-model via ``padding`` unless its fluid in which ``100%`` can be specified or you can also use ``left: 0; right: 0;`` + +Indenting Sass +^^^^^^^^^^^^^^ + +Sass provides nesting functionality. That is to say, by writing this: + +.. code:: + + .foo { + color: red; + + .bar { + color: blue; + } + } + +… we will be left with this compiled CSS: + +.. code:: css + + .foo { color: red; } + .foo .bar { color: blue; } + +When indenting Sass, we stick to the same four space tab indentation, and we also leave a blank line before and after the nested ruleset. + +**N.B.** Nesting in Sass should be avoided in most cases. See the Specificity section for more data + +CSS Variables +~~~~~~~~~~~~~ + +CSS Variables allow you to store and reuse values throughout your stylesheets. This promotes maintainability and reduces the risk of inconsistencies. + +Here are some guidelines for using CSS variables effectively in phpBB styles: + +- Store project-wide values: + + Use variables to define core UI aspects like colors, spacing, and fonts. Prefix these variables with `--phpbb-` in the phpBB core to avoid naming conflicts. + For example: + + .. code:: css + + :root { + --phpbb-primary-color: #1abc9c; + --phpbb-secondary-color: #34495e; + --phpbb-text-color: #ecf0f1; + --phpbb-font-size: 16px; + --phpbb-line-height: 1.5; + } + +- Create style-specific variables: + If styles differ or might differ between phpBB styles (e.g. prosilver), use the style's name as a prefix (e.g. --prosilver-) for style-specific variables. + This allows for customization without affecting other styles. For instance: + + .. code:: css + + :root { + --prosilver-background-color: #f5f5f5; + --prosilver-border-color: #ddd; + } + + .content { + background-color: var(--prosilver-background-color); + border: 1px solid var(--prosilver-border-color); + } + + In this example, `--phpbb-primary-color` defines the primary color used throughout the project, while `--prosilver-background-color` sets the background color specifically for the prosilver style. + +By following these recommendations, you can leverage the power of CSS variables to create a more maintainable and efficient codebase for your phpBB styles. + +Benefits of Using CSS Variables: + +- Improved Maintainability: Makes it easier to update core styles or style-specific customizations by changing the variable value in one place. +- Reduced Repetition: Eliminates the need to repeat the same value throughout your stylesheets. +- Flexibility: Provides greater control over styles and the ability to create themes with unique appearances. + +For a detailed explanation of CSS Variables, refer to the `MDN Web Docs: Using CSS custom properties (variables) `_. + + +Enforcing standardization +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Our project makes use of several tools to lint and keep code up to standards. + +1. `stylelint.io`_ +^^^^^^^^^^^^^^^^^^ + +.. note:: This is used to provide detailed linting for our standards via the ``.stylelintrc`` file in the root of the project. + +2. `postcss-sorting`_ +^^^^^^^^^^^^^^^^^^^^^ + +.. note:: This is used to provide automatic sorting to our declaration order via the ``.postcss-sorting.json`` file in the root of the project. + +3. `postcss-pxtorem`_ +^^^^^^^^^^^^^^^^^^^^^ + +.. note:: This is used to ensure that proper units are consistently used throughout the project during the build process via ``gulp`` as well as on save in your editor. + +4. `stylefmt`_ +^^^^^^^^^^^^^^ + +.. 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`_ & `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: 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/ +.. _Visual Studio Code: https://code.visualstudio.com/ +.. _Editor Setup: /editor-setup diff --git a/development/development/css/css_naming.rst b/development/development/css/css_naming.rst new file mode 100644 index 00000000..6583b198 --- /dev/null +++ b/development/development/css/css_naming.rst @@ -0,0 +1,243 @@ +Naming Conventions +------------------ + +Naming conventions in CSS are hugely useful in making your code more strict, more transparent, and more informative. + +A good naming convention will tell you and your team + +- what type of thing a class does +- where a class can be used +- what (else) a class might be related to + +The naming convention we follow are as follows + +- Hyphen (``-``) delimited strings +- Layer namespacing +- A variation on BEM-like naming for action modifiers + +It’s worth noting that not all the naming conventions are normally useful in the CSS side of development; they really come into their own when viewed in HTML. + +Hyphen Delimited +~~~~~~~~~~~~~~~~ + +All strings in classes are delimited with a hyphen (``-``), like so: + +.. code:: css + + .page-head { } + + .sub-content { } + +Camel case and underscores are not used for regular classes; the following are incorrect: + +.. code:: css + + .pageHead { } + + .sub_content { } + +Modified BEM-like Naming +~~~~~~~~~~~~~~~~~~~~~~~~ + +For larger, more interrelated pieces of UI that require a number of classes, we use a modified BEM-like naming convention. + +BEM, meaning Block, Element, Modifier, is a front-end methodology coined by developers working at Yandex. Whilst BEM is a complete methodology, here we are only concerned with its naming convention. Further, the naming convention here only is BEM-like; the principles are exactly the same, but the actual syntax differs. + +BEM splits components’ classes into three groups: + +- Block: The sole root of the component. +- Element: A component part of the Block. +- Modifier: A variant or extension of the Block. + +To take an analogy (note, not an example): + +.. code:: css + + .dropdown { } + .dropdown-item { } + .dropdown--active { } + +Elements are delimited with one (1) hyphen (``-``), and Modifiers are delimited by two (2) hyphens (``--``). + +Here we can see that ``.dropdown {}`` is the Block; it is the sole root of a discrete entity. ``.dropdown-item {}`` is an Element; it is a smaller part of the ``.dropdown {}`` Block. Finally, ``.dropdown--active {}`` is a Modifier; it is a specific variant of the ``.dropdown {}`` Block. + +Starting Context +^^^^^^^^^^^^^^^^ + +Your Block context starts at the most logical, self-contained, discrete location. To continue with our dropdown-based analogy, we’d not have a class like ``.header-dropdown {}``, as the header is another, much higher context. We’d probably have separate Blocks, like so: + +.. code:: css + + .header { } + + .header-nav { } + + + .dropdown { } + + .dropdown-item { } + +If we did want to denote a ``.dropdown {}`` inside a ``.header {}``, it is more correct to use a selector like ``.header .dropdown {}`` which bridges two Blocks than it is to increase the scope of existing Blocks and Elements. + +A more realistic example of properly scoped blocks might look something like this, where each chunk of code represents its own Block: + +.. code:: css + + .page { } + + + .content { } + + + .footer { } + + .footer-copyright { } + +Incorrect notation for this would be: + +.. code:: css + + .page { } + + .page-content { } + + .page-footer { } + + .page-copyright { } + +It is important to know when BEM scope starts and stops. As a rule, BEM applies to self-contained, discrete parts of the UI. + +More Layers +^^^^^^^^^^^ + +If we were to add another Element—called, let’s say, ``.dropdown-link {}``—to this ``.dropdown {}`` component, we would not need to step through every layer of the DOM. That is to say, the correct notation would be ``.dropdown-link {}``, and not ``.dropdown-item-link {}``. Your classes do not reflect the full paper-trail of the DOM. + +Layer Namespacing +~~~~~~~~~~~~~~~~~ + +There are a number of common problems when working with CSS at scale, but the major two that namespacing aims to solve are clarity and confidence: + +- **Clarity:** How much information can we glean from the smallest possible source? Is our code self-documenting? Can we make safe assumptions from a single context? How much do we have to rely on external or supplementary information in order to learn about a system? +- **Confidence:** Do we have enough knowledge about a system to be able to safely interface with it? Do we know enough about our code to be able to confidently make changes? Do we have a way of knowing the potential side effects of making a change? Do we have a way of knowing what we might be able to remove? + +This gets further complicated when dealing with `ITCSS`_. Knowing what layer a class is coming from is not always apparent. To combat this and provide complete transparency we use layer based namespacing. + +In no particular order, here are the individual namespaces and a brief description. We’ll look at each in more detail in a moment, but the following list should acquaint you. + +- ``o-``: Signify that something is an Object, and that it may be used in any number of unrelated contexts to the one you can currently see it in. Making modifications to these types of class could potentially have knock-on effects in a lot of other unrelated places. Tread carefully. +- ``c-``: Signify that something is a Component. This is a concrete, implementation-specific piece of UI. All of the changes you make to its styles should be detectable in the context you’re currently looking at. Modifying these styles should be safe and have no side effects. +- ``u-``: Signify that this class is a Utility class. It has a very specific role (often providing only one declaration) and should not be bound onto or changed. It can be reused and is not tied to any specific piece of UI. You will probably recognize this namespace from libraries and methodologies like `SUITcss`_. +- ``t-``: Signify that a class is responsible for adding a Theme to a view. It lets us know that UI Components’ current cosmetic appearance may be due to the presence of a theme. Vastly improves templating for large projects +- ``s-``: Signify that a class creates a new styling context or Scope. Similar to a Theme, but not necessarily cosmetic, these should be used sparingly—they can be open to abuse and lead to poor CSS if not used wisely. +- ``is-``, ``has-``: Signify that the piece of UI in question is currently styled a certain way because of a state or condition. This stateful namespace is gorgeous, and comes from `SMACSS`_. It tells us that the DOM currently has a temporary, optional, or short-lived style applied to it due to a certain state being invoked. +- ``_``: Signify that this class is the worst of the worst—a hack! Sometimes, although incredibly rarely, we need to add a class in our markup in order to force something to work. If we do this, we need to let others know that this class is less than ideal, and hopefully temporary (i.e. do not bind onto this). + +Even from this short list alone, we can see just how much more information we can communicate to developers simply by placing a character or two at the front of our existing classes. + +CSS Variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kebap-case +^^^^^^^^^^ + +We specifically use kebab-case (lowercase words separated by hyphens) for CSS variable names. This aligns with the convention used by Bootstrap itself and other CSS frameworks. +Kebab-case improves readability and avoids naming conflicts, especially when working with custom properties. + +Here's an example: + +.. code:: css + + :root { + --primary-color: #1abc9c; + --secondary-color: #34495e; + --text-color: #ecf0f1; + } + + .btn { + background-color: var(--primary-color); + color: var(--text-color); + } + +Variable prefixed +^^^^^^^^^^^^^^^^^ + +To organize your CSS variables effectively, a prefix system shall be used: + +- Project-wide variables: + Use the --phpbb- prefix for variables that apply to all styles. These variables will likely define core aspects of the UI, like colors, spacing, and fonts. + +- Theme-specific variables: + For variables that are specific to a particular style (e.g. prosilver), use the style's name as a prefix followed by a hyphen (-). This helps distinguish theme-specific customizations from project-wide styles. + +**Example:** + +.. code:: css + + :root { + /* Project-wide variables */ + --phpbb-primary-color: #1abc9c; + --phpbb-secondary-color: #34495e; + --phpbb-text-color: #ecf0f1; + + /* Prosilver-specific variables */ + --prosilver-background-color: #f5f5f5; + --prosilver-border-color: #ddd; + } + + .button { + background-color: var(--phpbb-primary-color); + color: var(--phpbb-text-color); + } + + /* Prosilver-specific style */ + .content { + background-color: var(--prosilver-background-color); + border: 1px solid var(--prosilver-border-color); + } + +In this example: + +- `--phpbb-primary-color`, `--phpbb-secondary-color` and `--phpbb-text-color` are project-wide variables that shall be accessed throughout the codebase. +- `--prosilver-background-color` and `--prosilver-border-color` are specific to the prosilver style, allowing for easy customization without affecting other styles. + +**Benefits of Prefixed Variables:** + +- Improved Organization: Clearly separates project-wide styles from style-specific customizations. +- Reduced Conflicts: Prevents naming clashes between variables of different scopes. +- Maintainability: Makes it easier to find and manage variables across your CSS code. + +**Additional Tips:** + +- Keep variable names concise while maintaining clarity. +- Consider using a linter (like `stylelint`) or code formatter to enforce consistent naming conventions. +- Document your variables in a central location for easy reference. + +By following these guidelines, you'll create a well-structured and maintainable system for managing CSS variables in your phpBB Extension or Style. + +Further Reading +^^^^^^^^^^^^^^^ + + - `UI Selector Namspacing`_ + +JavaScript Hooks +~~~~~~~~~~~~~~~~ + +As a rule, it is unwise to bind your CSS and your JS onto the same class in your HTML. This is because doing so means you can’t have (or remove) one without (removing) the other. It is much cleaner, much more transparent, and much more maintainable to bind your JS onto data attributes. + +example: + +.. code:: html + + + +This means that we can have an element elsewhere which can carry the style of ``.btn {}``, but without the behavior of ``data-execute="addSomething"``. + +``data-*`` Attributes +^^^^^^^^^^^^^^^^^^^^^ + +It is our preferred practice to use ``data-*`` attributes as JS hooks. ``data-*`` attributes, as per the spec, are typically used to store custom data private to the page or application’. however since you are already binding this attribute to your js, it makes sense to use the same attribute as the js hook. + +.. _ITCSS: https://www.youtube.com/watch?v=1OKZOV-iLj4 +.. _SUITcss: https://suitcss.github.io/ +.. _SMACSS: https://smacss.com/ +.. _UI Selector Namspacing: https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/ diff --git a/development/development/css/css_selectors.rst b/development/development/css/css_selectors.rst new file mode 100644 index 00000000..ba411d14 --- /dev/null +++ b/development/development/css/css_selectors.rst @@ -0,0 +1,256 @@ +CSS Selectors +------------- + +Perhaps somewhat surprisingly, one of the most fundamental, critical aspects of writing maintainable and scalable CSS is selectors. Their specificity, their portability, and their reusability all have a direct impact on the mileage you will get out of the CSS, and the headaches it might bring you. + +Selector Intent +~~~~~~~~~~~~~~~ + +It is important when writing CSS that you scope the selectors correctly, and that you're selecting the right things for the right reasons. Selector Intent is the process of deciding and defining what you want to style and how you will go about selecting it. For example, if you are wanting to style your website’s main navigation menu, a selector like this would be incredibly unwise: + +.. code:: css + + header ul { } + +This selector’s intent is to style any ``ul`` inside any ``header`` element, whereas your intent was to style the site’s main navigation. This is poor Selector Intent: you can have any number of ``header`` elements on a page, and they in turn can house any number of ``uls``, so a selector like this runs the risk of applying very specific styling to a very wide number of elements. This will result in having to write more CSS to undo the greedy nature of such a selector. + +A better approach would be a selector like: + +.. code:: css + + .site-nav { } + +An unambiguous, explicit selector with good Selector Intent. Explicitly selecting the right thing for exactly the right reason. + +Poor Selector Intent is one of the biggest reasons for headaches on CSS projects. Writing rules that are far too greedy, and apply very specific treatments via very far reaching selectors. This causes unexpected side effects and leads to very tangled stylesheets, with selectors overstepping their intentions and impacting and interfering with otherwise unrelated rulesets. + +CSS cannot be encapsulated, it is inherently leaky, but you can mitigate some of these effects by not writing such globally operating selectors: **your selectors should be as explicit and well reasoned as your reason for wanting to select something.** + +Reusability +~~~~~~~~~~~ + +With a move toward a more component based approach to constructing UIs, the idea of reusability is paramount. You want the option to be able to move, recycle, duplicate, and syndicate components across our projects. + +To this end, make heavy use of classes. IDs, as well as being hugely over specific, cannot be used more than once on any given page. Classes can be reused an infinite amount of times. Everything you choose, from the type of selector to its name, should lend itself toward being reused. + +Location Independence +~~~~~~~~~~~~~~~~~~~~~ + +Given the ever changing nature of most UI projects, and the move to more component based architectures, it is in your best interest not to style things based on where they are, but on what they are. That is to say, your components’ styling should not be reliant upon where its placed. They should remain entirely location independent. + +Let’s take an example of a call-to-action button that has been styled via the following selector: + +.. code:: css + + .promo a { } + +Not only does this have poor Selector Intent, it will greedily style any and every link inside of a ``.promo`` to look like a button. It is also pretty wasteful as a result of being so locationally dependent: you can’t reuse that button with its correct styling outside of ``.promo`` because it is explicitly tied to that location. A far better selector would have been: + +.. code:: css + + .btn { } + +This single class can be reused anywhere outside of ``.promo`` and will always carry its correct styling. As a result of a better selector, this piece of UI is more portable, more recyclable, doesn’t have any dependencies, and has much better Selector Intent. **A component shouldn’t have to live in a certain place to look a certain way.** + +Portability +~~~~~~~~~~~ + +Reducing or removing, location dependence means that you can move components around our markup more freely, but how about improving the ability to move classes around components? On a much lower level, there are changes you can make to your selectors that make the selectors themselves, as opposed to the components they create more portable. Take the following example: + +.. code:: css + + input.btn { } + +This is a *qualified* selector; the leading ``input`` ties this ruleset to only being able to work on ``input`` elements. By omitting this qualification, you allow the reuse of the ``.btn`` class on any element you choose, like an ``a``, for example, or a ``button``. + +Qualified selectors do not lend themselves well to being reused, and every selector you write should be authored with reuse in mind. + +Of course, there are times when you may want to legitimately qualify a selector, you might need to apply some very specific styling to a particular element when it carries a certain class, for example: + +.. code:: css + + /** + * Embolden and color any element with a class of `.error`. + */ + .error { + color: red; + font-weight: bold; + } + + /** + * If the element is a `div`, also give it some box-like styling. + */ + div.error { + padding: 10px; + border: 1px solid; + } + +This is one example where a qualified selector might be justifiable, but the recommend approach would be: + +.. code:: css + + /** + * Text-level errors. + */ + .error-text { + color: red; + font-weight: bold; + } + + /** + * Elements that contain errors. + */ + .error-box { + padding: 10px; + border: 1px solid; + } + +This means that you can apply ``.error-box`` to any element, and not just a ``div`` it is more reusable than a qualified selector. + +Quasi-Qualified Selectors +^^^^^^^^^^^^^^^^^^^^^^^^^ + +One thing that qualified selectors can be useful for is signaling where a class might be expected or intended to be used, for example: + +.. code:: css + + ul.nav { } + +Here you can see that the ``.nav`` class is meant to be used on a ``ul`` element, and not on a ``nav``. By using *quasi-qualified selectors* you can still provide that information without actually qualifying the selector: + +.. code:: css + + /*ul*/.nav { } + +By commenting out the leading element, you can still leave it to be read, but avoid qualifying and increasing the specificity of the selector. + +Naming +~~~~~~ + +As Phil Karlton once said + + ‘There are only two hard things in Computer Science: cache + invalidation and naming things.’ + +Without commenting on the former claim here, but the latter has plagued people for years. Our advice with regard to naming things in CSS is to pick a name that is sensible, but somewhat ambiguous: aim for high reusability. For example, instead of a class like ``.site-nav``, choose something like ``.primary-nav``; rather than ``.footer-links``, favor a class like ``.sub-links``. + +The differences in these names is that the first of each two examples is tied to a very specific use case: they can only be used as the site’s navigation or the footer’s links respectively. By using slightly more ambiguous names, you can increase the ability to reuse these components in different circumstances. + +To quote Nicolas Gallagher: + + 'Tying your class name semantics tightly to the nature of the content + has already reduced the ability of your architecture to scale or be + easily put to use by other developers.' + +That is to say, you should use sensible names or classes. For example ``.border`` or ``.red`` are never advisable, avoid using classes which describe the exact nature of the content and/or its use cases. **Using a class name to describe content is redundant because content describes itself.** + +The debate surrounding semantics has raged for years, but it is important that you adopt a more pragmatic, sensible approach to naming things in order to work more efficiently and effectively. Instead of focussing on ‘semantics’, look more closely at sensibility and longevity, choose names based on ease of maintenance, not for their perceived meaning. + +Name things for people; they’re the only ones that actually read your classes (everything else merely matches them). Once again, it is better to strive for reusable, recyclable classes rather than writing for specific use cases. Let’s take an example: + +.. code:: css + + /** + * Runs the risk of becoming out of date; not very maintainable. + */ + .blue { color: blue; } + + /** + * Depends on location in order to be rendered properly. + */ + .header span { color: blue; } + + /** + * Too specific; limits the ability to reuse. + */ + .header-color { color: blue; } + + /** + * Nicely abstracted, very portable, doesn’t risk becoming out of date. + */ + .highlight-color { color: blue; } + +It is important to strike a balance between names that do not literally describe the style that the class brings, but also ones that do not explicitly describe specific use cases. Instead of ``.home-page-panel``, choose ``.masthead``; instead of ``.site-nav``, favor ``.primary-nav``; instead of ``.btn-login``, opt for ``.btn-primary``. + +Selector Performance +~~~~~~~~~~~~~~~~~~~~ + +A topic which is with the quality of today’s browsers, more interesting than it is important, is selector performance. That is to say, how quickly a browser can match the selectors you write in CSS up with the nodes it finds in the DOM. + +Generally speaking, the longer a selector is (i.e. the more component parts) the slower it is, for example: + +.. code:: css + + body.home div.header ul { } + +…is a far less efficient selector than: + +.. code:: css + + .primary-nav { } + +This is because browsers read CSS selectors right-to-left. A browser will read the first selector as + +- find all ``ul`` elements in the DOM +- now check if they live anywhere inside an element with a class of ``.header`` +- next check that ``.header`` class exists on a ``div`` element +- now check that that all lives anywhere inside any elements with a class of ``.home`` +- finally, check that ``.home`` exists on a ``body`` element + +The second, in contrast, is simply a case of the browser reading, find all the elements with a class of ``.primary-nav``. + +To further compound the problem, the example uses descendant selectors (e.g. ``.foo .bar {}``). The upshot of this is that a browser is required to start with the rightmost part of the selector (i.e. ``.bar``) and keep looking up the DOM indefinitely until it finds the next part (i.e. ``.foo``). This could mean stepping up the DOM dozens of times until a match is found. + +This is just one reason why **nesting with preprocessors is often a false economy**; as well as making selectors unnecessarily more specific, and creating location dependency, it also creates more work for the browser. + +By using a child selector (e.g. ``.foo > .bar {}``) you can make the process much more efficient, because this only requires the browser to look one level higher in the DOM, and it will stop regardless of whether or not it found a match. + +The Key Selector +^^^^^^^^^^^^^^^^ + +Because browsers read selectors right-to-left, the rightmost selector is often critical in defining a selector’s performance: this is called the key selector. + +The following selector might appear to be highly performant at first glance. It uses an ID which is nice and fast, and there can only ever be one on a page, so surely this will be a nice and speedy lookup, just find that one ID and then style everything inside of it: + +.. code:: css + + #foo * { } + +The problem with this selector is that the key selector (``*``) is very, very far reaching. What this selector actually does is find every single node in the DOM (even ````, ``<link>``, and ``<head>`` elements; everything) and then looks to see if it lives anywhere at any level within #foo. This is a very, very expensive selector, and should most likely be avoided or rewritten. + +Thankfully, by writing selectors with good Selector Intent, you are probably avoiding inefficient selectors by default; you are very unlikely to have greedy key selectors if you’re targeting the right things for the right reason. + +That said, however, CSS selector performance should be fairly low on your list of things to optimize; browsers are fast, and are only ever getting faster, and it is only on notable edge cases that inefficient selectors would be likely to pose a problem. + +As well as their own specific issues, nesting, qualifying, and poor Selector Intent all contribute to less efficient selectors. + +General Rules +~~~~~~~~~~~~~ + +Your selectors are fundamental to writing good CSS. To very briefly sum up the above sections: + +- **Select what you want explicitly**, rather than relying on circumstance or coincidence. Good Selector Intent will rein in the reach and leak of your styles. +- **Write selectors for reusability**, so that you can work more efficiently and reduce waste and repetition. +- **Do not nest selectors unnecessarily**, because this will increase specificity and affect where else you can use your styles. +- **Do not qualify selectors unnecessarily**, as this will impact the number of different elements you can apply styles to. +- **Keep selectors as short as possible**, in order to keep specificity down and performance up. + +Focussing on these points will keep your selectors a lot more sane and easy to work with on changing and long running projects. + +Further Reading +^^^^^^^^^^^^^^^ + +- `Shoot to kill; CSS selector intent`_ +- `‘Scope’ in CSS`_ +- `Keep your CSS selectors short`_ +- `About HTML semantics and front-end architecture`_ +- `Naming UI components in OOCSS`_ +- `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 new file mode 100644 index 00000000..6abe3100 --- /dev/null +++ b/development/development/css/css_specificity.rst @@ -0,0 +1,281 @@ +Specificity +----------- + +As we’ve seen, CSS isn’t the most friendly of languages: globally operating, very leaky, dependent on location, hard to encapsulate, based on inheritance… But! None of that even comes close to the horrors of specificity. + +No matter how well considered your naming, regardless of how perfect your source order and cascade are managed, and how well you’ve scoped your rulesets, just one overly-specific selector can undo everything. It is a gigantic curveball, and undermines CSS’ very nature of the cascade, inheritance, and source order. + +The problem with specificity is that it sets precedents and trumps that cannot simply be undone. If we take the following example + +.. code:: css + + #content table { } + +Not only does this exhibit poor **Selector Intent**, we didn’t actually want every ``table`` in the ``#content`` area. We wanted a specific type of ``table`` that just happened to live there. This is a hugely over-specific selector. It becomes apparent, when we needed a second type of ``table``: + +.. code:: css + + #content table { } + + /** + * Uh oh! My styles get overwritten by `#content table {}`. + */ + .my-new-table { } + +The first selector was trumping the specificity of the one defined after it, working against CSS’ source-order based application of styles. In order to remedy this, we have two main options. we could + +#. refactor the CSS and HTML to remove that ID; +#. write a more specific selector to override it. + +Unfortunately, refactoring would take a long time in a mature product and the knock-on effects of removing this ID would be more substantial business cost than the second option: just write a more specific selector. + +.. code:: css + + #content table { } + + #content .my-new-table { } + +Now we have a selector that is even more specific still! And if we ever want to override this one, we will need another selector of at least the same specificity defined after it. We’ve started on a downward spiral. + +Specificity can, among other things, + +- limit your ability to extend and manipulate a codebase +- interrupt and undo CSS’ cascading, inheriting nature +- cause avoidable verbosity in your project +- prevent things from working as expected when moved into different environments +- lead to serious developer frustration + +All of these issues are greatly magnified when working on a larger project with a number of developers contributing code. + +Keep It Low at All Times +~~~~~~~~~~~~~~~~~~~~~~~~ + +The problem with specificity isn’t necessarily that it’s high or low; it’s the fact it is so variant and that it cannot be opted out of: the only way to deal with it is to get progressively more specific—the notorious specificity wars we looked at above. + +One of the single, simplest tips for an easier life when writing CSS, particularly at any reasonable scale—is to always try to keep specificity as low as possible at all times. Try to make sure there isn’t a lot of variance between selectors in the codebase, and that all selectors strive for as low a specificity as possible. + +Doing so will instantly help us tame and manage the project, meaning that no overly-specific selectors are likely to impact or affect anything of a lower specificity elsewhere. It also means we’re less likely to need to fight our way out of specificity corners, and we’ll probably also be writing much smaller stylesheets. + +Simple changes to the way we work include, but are not limited to, + +- not using IDs in your CSS +- not nesting selectors +- not qualifying classes +- not chaining selectors + +**Specificity can be wrangled and understood, but it is safer just to avoid it entirely.** + +IDs in CSS +~~~~~~~~~~ + +If we want to keep specificity low, which we do, we have one really quick-win, simple, easy-to-follow rule that we can employ to help us: + +.. warning:: **NEVER USE IDs in CSS** + +Not only are IDs inherently non-reusable, they are also vastly more specific than any other selector, and therefore become specificity anomalies. Where the rest of your selectors are relatively low specificity, your ID-based selectors are, comparatively, much, much higher. + +In fact, to highlight the severity of this difference, see how one thousand chained classes cannot override the specificity of a single ID: `jsfiddle.net/0yb7rque`_. + +.. warning:: Please note that in Firefox you may see the text rendering in blue: this is a `known bug`_, and an ID will be overridden by 256 chained classes. + +.. note:: **N.B.** It is still perfectly okay to use IDs in HTML and JavaScript; it is only in CSS that they prove troublesome. + +It is often suggested that developers who choose not to use IDs in CSS merely don’t understand how specificity works. This is as incorrect as it is offensive: no matter how experienced a developer you are, this behavior cannot be circumvented; no amount of knowledge will make an ID less specific. + +Opting into this way of working only introduces the chance of problems occurring further down the line, and—particularly when working at scale—all efforts should be made to avoid the potential for problems to arise. In a sentence: + +**It is just not worth introducing the risk.** + +Nesting +~~~~~~~ + +We’ve already looked at how nesting can lead to location dependent and potentially inefficient code, but now it’s time to take a look at another of its pitfalls: it makes selectors more specific. + +When we talk about nesting, we don’t necessarily mean preprocessor nesting, like so: + +.. code:: scss + + .foo { + + .bar { } + + } + + +We’re actually talking about descendant or child selectors; selectors which rely on a thing within a thing. That could look like any one of the following: + +.. code:: css + + /** + * An element with a class of `.bar` anywhere inside an element with a class of + * `.foo`. + */ + .foo .bar { } + + + /** + * An element with a class of `.module-title` directly inside an element with a + * class of `.module`. + */ + .module > .module-title { } + + + /** + * Any `li` element anywhere inside a `ul` element anywhere inside a `nav` + * element + */ + nav ul li { } + +Whether you arrive at this CSS via a preprocessor or not isn’t particularly important, but it is worth noting **that preprocessors tout this as a feature, where it is actually to be avoided wherever possible.** + +Generally speaking, each part in a compound selector adds specificity. Ergo, the fewer parts to a compound selector then the lower its overall specificity, and we always want to keep specificity low. To quote Jonathan Snook: + + …whenever declaring your styles, **use the least number of selectors required to style an element.** + +Let’s look at an example: + +.. code:: css + + .widget { + padding: 10px; + } + + .widget > .widget-title { + color: red; + } + +To style an element with a class of ``.widget-title``, we have a selector that is twice as specific as it needs to be. That means that if we want to make any modifications to ``.widget-title``, we’ll need another at-least-equally specific selector: + +.. code:: + + .widget { ... } + + .widget > .widget-title { ... } + + .widget > .widget-title-sub { + color: blue; + } + +Not only is this entirely avoidable—we caused this problem ourselves—we have a selector that is literally double the specificity it needs to be. We used 200% of the specificity actually required. And not only that, but this also leads to needless verbosity in our code—more to send over the wire. + +.. warning:: As a rule, **if a selector will work without it being nested then do not nest it.** + +Scope +~~~~~ + +One possible advantage of nesting—which, unfortunately, does not outweigh the disadvantages of increased specificity—is that it provides us with a namespace of sorts. A selector like ``.widget .title`` scopes the styling of ``.title`` to an element that only exists inside of an element carrying a class of ``.widget``. + +This goes some way to providing our CSS with scope and encapsulation, but does still mean that our selectors are twice as specific as they need to be. A better way of providing this scope would be via a namespace—which does not lead to an unnecessary increase in specificity. + +Now we have better scoped CSS with minimal specificity—the best of both worlds. + +.. seealso:: + + - `‘Scope’ in CSS`_ + +``!important`` +~~~~~~~~~~~~~~ + +The word ``!important`` sends shivers down the spines of almost all front-end developers. ``!important`` is a direct manifestation of problems with specificity; it is a way of cheating your way out of specificity wars, but usually comes at a heavy price. It is often viewed as a last resort—a desperate, defeated stab at patching over the symptoms of a much bigger problem with your code. + +The general rule is that ``!important`` is always a bad thing, but, to quote Jamie Mason: + + Rules are the children of principles. + +That is to say, a single rule is a simple, black-and-white way of adhering to a much larger principle. When you’re starting out, the rule never use ``!important`` is a good one. + +However, once you begin to grow and mature as a developer, you begin to understand that the principle behind that rule is simply about keeping specificity low. You’ll also learn when and where the rules can be bent… + +``!important`` does have a place in CSS projects, but only if used sparingly and proactively. + +Proactive use of ``!important`` is when it is used *before* you’ve encountered any specificity problems; when it is used as a guarantee rather than as a fix. + +For example: + +.. code:: css + + .one-half { + width: 50% !important; + } + + .hidden { + display: none !important; + } + +These two helper, or *utility*, classes are very specific in their intentions: you would only use them if you wanted something to be rendered at 50% width or not rendered at all. If you didn’t want this behavior, you would not use these classes, therefore whenever you do use them you will definitely want them to win. + +Here we proactively apply ``!important`` to ensure that these styles always win. This is the correct use of ``!important`` to guarantee that these trumps always work, and don’t accidentally get overridden by something else more specific. + +Incorrect, reactive use of ``!important`` is when it is used to combat specificity problems after the fact: applying ``!important`` to declarations because of poorly architected CSS. For example, let’s imagine we have this HTML: + +.. code:: html + + <div class="content"> + <h2 class="heading-sub">...</h2> + </div> + +…and this CSS: + +.. code:: css + + .content h2 { + font-size: 2rem; + } + + .heading-sub { + font-size: 1.5rem !important; + } + +Here we can see how we’ve used ``!important`` to force our ``.heading-sub {}`` styles to reactively override our ``.content h2 {}`` selector. This could have been circumvented by any number of things, including using better Selector Intent, or avoiding nesting. + +In these situations, it is preferable that you investigate and refactor any offending rulesets to try and bring specificity down across the board, as opposed to introducing such specificity heavyweights. + +.. warning:: **Only use** ``!important`` **proactively, not reactively.** + +Hacking Specificity +~~~~~~~~~~~~~~~~~~~ + +With all that said on the topic of specificity, and keeping it low, it is inevitable that we will encounter problems. No matter how hard we try, and how conscientious we are, there will always be times that we need to hack and wrangle specificity. + +When these situations do arise, it is important that we handle the hacks as safely and elegantly as possible. + +In the event that you need to increase the specificity of a class selector, there are a number of options. We could nest the class inside something else to bring its specificity up. For example, we could use ``.header .site-nav {}`` to bring up the specificity of a simple ``.site-nav {}`` selector. + +The problem with this, as we’ve discussed, is that it introduces location dependency: these styles will only work when the ``.site-nav`` component is in the ``.header`` component. + +Instead, we can use a much safer hack that will not impact this component’s portability: we can chain that class with itself: + +.. code:: css + + .site-nav.site-nav { } + +This chaining doubles the specificity of the selector, but does not introduce any dependency on location. + +In the event that we do, for whatever reason, have an ID in our markup that we cannot replace with a class, select it via an attribute selector as opposed to an ID selector. For example, let’s imagine we have embedded a third-party widget on our page. We can style the widget via the markup that it outputs, but we have no ability to edit that markup ourselves: + +.. code:: html + + <div id="third-party-widget"> + ... + </div> + +Even though we know not to use IDs in CSS, what other option do we have? We want to style this HTML but have no access to it, and all it has on it is an ID. + +We do this: + +.. code:: css + + [id="third-party-widget"] { } + +Here we are selecting based on an attribute rather than an ID, and attribute selectors have the same specificity as a class. This allows us to style based on an ID, but without introducing its specificity. + +Do keep in mind that these are hacks, and should not be used unless you have no better alternative. + +.. seealso:: + + - `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 new file mode 100644 index 00000000..9b45f66e --- /dev/null +++ b/development/development/css/css_standards.rst @@ -0,0 +1,258 @@ +In working on large, long running projects with dozens of developers, it is important that we all work in a unified way in order to, among other things: + +- Keep code maintainable +- Keep code transparent and readable +- Keep code scalable + +There are a variety of techniques we must employ in order to satisfy these goals. + +The Importance of a Styleguide +------------------------------ + +A coding styleguide (note, not a visual styleguide) is a valuable tool for teams who + +- build and maintain products for a reasonable length of time +- have developers of differing abilities and specialisms +- have a number of different developers working on a product at any given time +- on-board new staff regularly +- have a number of codebases that developers dip in and out of + +Whilst styleguides are typically more suited to production teams—large codebases on long-lived and evolving projects, with multiple developers contributing over prolonged periods of time—all developers should strive for a degree of standardization in their code. + +A good styleguide, when well followed, will + +- set the standard for code quality across a codebase +- promote consistency across codebases +- give developers a feeling of familiarity across codebases +- increase productivity + +Disclaimers +~~~~~~~~~~~ + +These Guidelines are a styleguide; they may not be the styleguide. They contain methodologies, techniques, and tips that we firmly recommend to teams + +They are opinionated, but have been repeatedly tried, tested, stressed, refined, broken, reworked, and revisited over a number of years on projects of all sizes. + +They should be learned, understood, and implemented at all times on this project, any deviation must be fully justified. + +Some General principles +----------------------- + + “Part of being a good steward to a successful project is realizing + that writing code for yourself is a Bad Idea™. If thousands of + people are using your code, then write your code for maximum + clarity, not your personal preference of how to get clever within + the spec.” - Idan Gazit + +- Don’t try to prematurely optimize your code; keep it readable and understandable +- All code should look like a single person typed it, even when many people are contributing to it +- We use a strictly enforced agreed-upon style based on existing common patterns + +Meaningful Whitespace +--------------------- + +Only one style should exist across the entire source of all your code-base. Always be consistent in your use of whitespace. Use whitespace to improve readability. + +- Never mix spaces and tabs for indentation. Stick to your choice without fail (**Preference: tabs**) +- Choose the number of preferred characters used per indentation level (**Preference: 4 spaces**) + +.. warning:: configure your editor to “show invisibles” or to automatically remove end-of-line whitespace. The use of an `EditorConfig`_ file is being used to help maintain the basic whitespace conventions. + +As well as indentation, we can provide a lot of information through liberal and judicious use of whitespace between rulesets. We use: + +- One (1) empty line between closely related rulesets +- Two (2) empty lines between loosely related rulesets + +For example: + +.. code:: scss + + //------------------------------------------------------------------------------ + // #FOO + //------------------------------------------------------------------------------ + + .foo { } + + .foo__bar { } + + + .foo--baz { } + +There should never be a scenario in which two rulesets do not have an empty line between them. This would be incorrect: + +.. code:: scss + + .foo { } + .foo__bar { } + .foo--baz { } + +Multiple Files +~~~~~~~~~~~~~~ + +With the meteoric rise of preprocessors of late, more often is the case that developers are splitting CSS across multiple files. + +Even if not using a preprocessor, it is a good idea to split discrete chunks of code into their own files, which are concatenated during a build step. + +We follow the ITCSS principles for the organization of our code and as such everything is broken up into partials. All partials are to be named to reflect the contained component/module and lead by an underscore (``_``) to prevent self rendering. + +Commenting +---------- + +**CSS needs more comments.** + +The cognitive overhead of working with CSS is huge. With so much to be aware of, and so many project-specific nuances to remember, the worst situation most developers find themselves in is being the-person-who-didn’t-write-this-code. Remembering your own classes, rules, objects, and helpers is manageable to an extent, but anyone inheriting CSS barely stands a chance. + +This is why well commented code is extremely important. Take time to describe components, how they work, their limitations, and the way they are constructed. Don’t leave others in the project guessing as to the purpose of uncommon or non-obvious code. + +Comment style should be simple and consistent within the code base. + +- Place comments on a new line above their subject +- Keep line-length to a sensible maximum, e.g., 80 columns +- Make liberal use of comments to break CSS code into discrete sections +- Use “sentence case” comments and consistent text indentation + +As CSS is something of a declarative language that doesn’t really leave much of a paper-trail, it is often hard to discern—from looking at the CSS alone + +- whether some CSS relies on other code elsewhere +- what effect changing some code will have elsewhere +- where else some CSS might be used +- what styles something might inherit (intentionally or otherwise) +- what styles something might pass on (intentionally or otherwise) +- where the author intended a piece of CSS to be used + +This doesn’t even take into account some of CSS’ many quirks—such as various sates of ``overflow`` triggering block formatting context, or certain transform properties triggering hardware acceleration—that make it even more baffling to developers inheriting projects. + +As a result of CSS not telling its own story very well, it is a language that really does benefit from being heavily commented. As a rule, you should comment anything that isn’t immediately obvious from the code alone. That is to say, there is no need to tell someone that ``color: red;`` will make something red, but if you’re using ``overflow: hidden;`` to clear floats—as opposed to clipping an element’s overflow—this is probably something worth documenting. + +.. warning:: Tip: you can configure your editor to provide you with shortcuts to output agreed-upon comment patterns. + +Comment Example: + +.. code:: scss + + //------------------------------------------------------------------------------ + // #[LAYER]: PARTIAL NAME + //------------------------------------------------------------------------------ + // #description + // + // This is a description of the PARTIAL + // + //------------------------------------------------------------------------------ + + // + // #settings + + // Layout Variables + $variable: [value] + + // Theme Variables + $variable: [value] + + // + // #scss + + // + // 1. inline comment + // 2. inline comment + // 3. inline comment + // + + [selector] { + [property]: [value]; + [property]: [value]; // [1] + [property]: [value]; // [1] + [property]: [value]; // [2] + [property]: [value]; + [property]: [value]; // [3] + } + + // + // Section Block Comment + //------------------------------------------------------------------------------ + // + // 1. inline comment + // 2. inline comment + // 3. inline comment + // + [selector] { + [property]: [value]; + [property]: [value]; // [1] + [property]: [value]; // [1] + [property]: [value]; // [2] + [property]: [value]; + [property]: [value]; // [3] + } + +Low-level +~~~~~~~~~ + +Oftentimes we want to comment on specific declarations (i.e. lines) in a ruleset. To do this we use a kind of reverse footnote. Here is a more complex comment detailing the larger site headers mentioned above: + +.. code:: + + // + // 1. Allow us to style box model properties. + // 2. Line different sized buttons up a little nicer. + // 3. Make buttons inherit font styles (often necessary when styling `input`s as + // buttons). + // 4. Reset/normalize some styles. + // 5. Force all button-styled elements to appear clickable. + // 6. Fixes odd inner spacing in IE7. + // 7. Subtract the border size from the padding value so that buttons do not + // grow larger as we add borders. + // 8. Prevent button text from being selectable. + // 9. Prevent default browser outline halo + // + .o-btn { + @include type(button); + @include shadow(2); + line-height: unitless($btn-height, map-get(map-get($type-styles, button), font-size)); + text-align: center; // [4] + vertical-align: middle; // [2] + white-space: nowrap; + text-decoration: none; // [4] + background-color: $btn-background-color; + border: none; + border-radius: $btn-border-radius; + outline: none; // [9] + color: $btn-text-color; + position: relative; + display: inline-block; // [1] + overflow: hidden; // [6] + min-width: $btn-min-width; + margin: 0; // [4] + padding: 0 $btn-spacing; // [7] + cursor: pointer; + user-select: none; // [8] + transition: + box-shadow 0.2s $animation-curve-fast-out-linear-in, + background-color 0.2s $default-animation-curve, + color 0.2s $default-animation-curve; + will-change: box-shadow; + } + +These types of comment allow us to keep all of our documentation in one place whilst referring to the parts of the ruleset to which they belong. + +Titling +~~~~~~~ + +Begin every new major section of a CSS project with a title: + +.. code:: scss + + //------------------------------------------------------------------------------ + // #SECTION-TITLE + //------------------------------------------------------------------------------ + + .selector { } + +The title of the section is prefixed with a hash (``#``) symbol to allow us to perform more targeted searches (e.g. ``grep``, etc.): instead of searching for just ``SECTION-TITLE``—which may yield many results—a more scoped search of ``#SECTION-TITLE`` should return only the section in question. + +Leave a carriage return between this title and the next line of code (be that a comment, some Sass, or some CSS). + +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: https://editorconfig.org/ diff --git a/development/development/css/index.rst b/development/development/css/index.rst new file mode 100644 index 00000000..3a7a7a0b --- /dev/null +++ b/development/development/css/index.rst @@ -0,0 +1,22 @@ +CSS Coding Guidelines +====================== + +We use `stylelint <https://stylelint.io/>`_ for checking the quality, linting, and ensuring consistent CSS code standards. There is a ``.stylelintrc`` file and a ``postcss-sorting.json`` file in the root of the project, and your editor probably has a plugin available which will show you when you violate these standards. + +We employ a set of standards loosely based on the following widely used +`CSS Guidelines <https://cssguidelin.es/>`_ + +.. 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 + +.. _PhpStorm: https://www.jetbrains.com/phpstorm/ +.. _ATOM: https://atom.io +.. _Editor Setup: /editor-setup + +.. toctree:: + :maxdepth: 2 + + css_standards + css_guidelines + css_naming + css_selectors + css_specificity diff --git a/development/development/git.rst b/development/development/git.rst index 5d236524..6f6c95a3 100644 --- a/development/development/git.rst +++ b/development/development/git.rst @@ -36,12 +36,12 @@ See `Set Up Git <https://help.github.com/articles/set-up-git>`_ for help on sett Branches ^^^^^^^^ -- `master <http://github.com/phpbb/phpbb/tree/master>`_ - The latest unstable development version with new features etc. -- `3.3.x <http://github.com/phpbb/phpbb/tree/3.3.x>`_ - Development branch of the 3.3 line. Bug fixes and minor feature changes are applied here. -- `3.2.x <http://github.com/phpbb/phpbb/tree/3.2.x>`_ - Development branch of the 3.2 line. Bug fixes and minor feature changes are applied here. -- `3.1.x <http://github.com/phpbb/phpbb/tree/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 <http://github.com/phpbb/phpbb/tree/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 <http://github.com/phpbb/phpbb/tree/2.0.x>`_ - Development branch of the deprecated 2.0 line. +- `master <https://github.com/phpbb/phpbb/tree/master>`_ - The latest unstable development version with new features etc. +- `3.3.x <https://github.com/phpbb/phpbb/tree/3.3.x>`_ - Development branch of the 3.3 line. Bug fixes and minor feature changes are applied here. +- `3.2.x <https://github.com/phpbb/phpbb/tree/3.2.x>`_ - Development branch of the 3.2 line. Bug fixes and minor feature changes are applied here. +- `3.1.x <https://github.com/phpbb/phpbb/tree/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 <https://github.com/phpbb/phpbb/tree/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 <https://github.com/phpbb/phpbb/tree/2.0.x>`_ - Development branch of the deprecated 2.0 line. Tags ^^^^ @@ -145,8 +145,10 @@ Review `Forking and Cloning`_. Configuration ------------- -Git -^^^ + +.. rubric:: Git + :heading-level: 4 + Add your Username to Git on your system: :: @@ -169,8 +171,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. @@ -186,8 +189,9 @@ Ignore any *abandoned package* warnings. `Introduction - Composer <https://getcomposer.org/doc/00-intro.md>`_ 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 @@ -203,8 +207,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 <http://vimdoc.sourceforge.net/htmldoc/>`__ or -`Emacs <https://www.gnu.org/software/emacs/manual/html_node/emacs/Help.html>`__. The +using `Vim <https://vimhelp.org/>`__ or +`Emacs <https://www.gnu.org/software/emacs/manual/html_node/emacs/Help-Summary.html>`__. The hooks will take care of formatting your entire commit message in the required format (see `Commit Messages`_). @@ -481,7 +485,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 <http://code.google.com/p/tortoisegit/>`_ +**For those who use** `TortoiseGit <https://tortoisegit.org/>`_ **(and used to work with TortoiseSVN):** When you use TortoiseGit the first time, you need to disable ``AutoCrlf`` in @@ -496,9 +500,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 @@ -532,16 +533,11 @@ Commands Further reading =============== -* `Git Community Book (online) <http://book.git-scm.com/>`__ -* `Pro Git Book (online) <http://progit.org/book/>`__ -* `GitCasts <http://gitcasts.com/>`__ -* `Getting Git <http://www.techscreencast.com/tool/versioncontrol/railsconf-git-talk/810>`__ -* `RailsConf 2008 <http://en.oreilly.com/rails2008/public/content/home>`__ Git Talk by Scott Chacon -* `Official Git Documentation <http://git-scm.com/documentation>`__ -* `Git Crash Course for SVN users <http://git-scm.com/course/svn.html>`__ -* `GitHub Guides <http://github.com/guides/home>`__ -* `Learn.GitHub <http://learn.github.com/>`__ -* `Git for the lazy <http://www.spheredev.org/wiki/Git_for_the_lazy>`__ +* `Git Community Book (online) <https://git-scm.com/book/en/v2>`__ +* `Official Git Documentation <https://git-scm.com/doc>`__ +* `GitHub Git Guide <https://github.com/git-guides>`__ +* `Git and GitHub learning resources <https://docs.github.com/en/get-started/start-your-journey/git-and-github-learning-resources>`__ +* `Git for the lazy <https://wiki.spheredev.org/index.php/Git_for_the_lazy>`__ External links ============== @@ -552,4 +548,4 @@ External links * `phpBB Extensions GitHub account <https://github.com/phpbb-extensions>`__ * `TortoiseGit <https://tortoisegit.org/>`__ - A windows Git client based on TortoiseSVN * `TortoiseGit on github <https://github.com/TortoiseGit/TortoiseGit/>`__ - GitHub repository -* `Open Source Contribution Etiquette <http://tirania.org/blog/archive/2010/Dec-31.html>`__ +* `Open Source Contribution Etiquette <https://tirania.org/blog/archive/2010/Dec-31.html>`__ diff --git a/development/development/html/guidance.rst b/development/development/html/guidance.rst new file mode 100644 index 00000000..fcdc9e13 --- /dev/null +++ b/development/development/html/guidance.rst @@ -0,0 +1,205 @@ +Idiomatic HTML Guidelines +================================================ + +1. Whitespace +---------------- + +Only one style should exist across the entire source of your code-base. +Always be consistent in your use of whitespace. Use whitespace to +improve readability. + +- Never mix spaces and tabs for indentation. +- Preference: ``Tabs`` + +.. tip: configure your editor to “show invisibles”. This will allow you to + eliminate end of line whitespace, eliminate unintended blank line + whitespace, and avoid polluting commits. + +2. Format +------------ + +- Always use lowercase tag and attribute names. +- Write one discrete element per line. +- Use one additional level of indentation for each nested element. +- Use valueless boolean attributes (e.g. ``checked`` rather than + ``checked="checked"``). +- Always use double quotes to quote attribute values. +- Omit the ``type`` attributes from ``link`` stylesheet, ``style`` and + ``script`` elements. +- Always include closing tags. ``<p>Some text</p>`` **NOT** ``<p>Some text`` +- Don’t include a trailing slash in self-closing elements. ``<img src="#" alt="something">`` **NOT** ``<img src="#" alt="something" />`` + +Example: + +.. code:: html + + <div class="tweet"> + <a href="path/to/somewhere"> + <img src="path/to/image.png" alt=""> + </a> + <p>[tweet text]</p> + <button disabled>Reply</button> + </div> + +3. Attribute order +------------------ + +HTML attributes should be listed in an order that reflects the fact that +class names are the primary interface through which CSS and JavaScript +select elements. + +1. ``class`` +2. ``id`` +3. ``data-*`` +4. Everything else + +Example: + +.. code:: html + + <a class="[value]" id="[value]" data-name="[value]" href="[url]">[text]</a> + +4. Line Breaks +-------------- + +We highly recommend using ``<p>`` **OR** ``<span>`` to wrap all blocks of text over using ``<br>`` to control line breaks. You are not able to stlye the ``<br>`` tag which limits the control of the content on a page. +Prefer the use of paragrphs or block level spans over breaks as you can not style a ``br`` tag. ``<p>Some text</p><p>Some More Text</p>`` **OR** ``<span class="something">Some text</span><span class="display-block-class">Some More Text</span>`` **NOT** ``Some text<br>Some More Text`` + +**Example with bad formated text:** + +.. code:: html + + <div class="content"> + + <h3> + This is a Title<br> + <small>This is a subtitle</small> + </h3> + + <p> + Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<br> + Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.<br> + Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.<br> + Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<br> + </p> + + </div> + +**Example with good formated text:** + +.. code:: css + + .subtitle { + display: block; + } + + .no-margin { + padding: 0; + margin: 0; + } + +.. code:: html + + <div class="content"> + + <h3> + This is a Title + <small class="subtitle">This is a subtitle</small> + </h3> + + <p class="no-margin"> + Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. + </p> + <p class="no-margin"> + Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. + </p> + <p class="no-margin"> + Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. + </p> + <p class="no-margin"> + Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + </p> + + </div> + +5. Naming +--------- + +Naming is hard, but very important. It’s a crucial part of the process +of developing a maintainable code base, and ensuring that you have a +relatively scalable interface between your HTML and CSS/JS. + +- Use clear, thoughtful, and appropriate names for HTML classes. The + names should be informative both within HTML and CSS files. +- Avoid *systematic* use of abbreviated class names. Don’t make things + difficult to understand. + +**Example with bad names:** + +.. code:: html + + <div class="cb s-scr"></div> + +.. code:: css + + .s-scr { + overflow: auto; + } + + .cb { + background: #000; + } + +**Example with better names:** + +.. code:: html + + <div class="column-body is-scrollable"></div> + +.. code:: css + + .is-scrollable { + overflow: auto; + } + + .column-body { + background: #000; + } + +6. Practical example +-------------------- + +An example of various conventions. + +.. code:: html + + <!DOCTYPE html> + <html> + <head> + <meta charset="utf-8"> + <title>Document + + + + + + + diff --git a/development/development/html/index.rst b/development/development/html/index.rst new file mode 100644 index 00000000..6e465235 --- /dev/null +++ b/development/development/html/index.rst @@ -0,0 +1,18 @@ +HTML Coding Guidelines +====================== + +We use `HTMLHint `_ for checking the quality, linting, and ensuring consistent HTML code standards. There is a ``.htmlhintrc`` file in the root of the project, and your editor probably has a plugin available which will show you when you violate these standards. + +We employ a set of standards based on the following widely used +`Idiomatic HTML Guidelines `_ + +.. 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 + +.. _PhpStorm: https://www.jetbrains.com/phpstorm/ +.. _ATOM: https://atom.io +.. _Editor Setup: /editor-setup + +.. toctree:: + :maxdepth: 2 + + guidance diff --git a/development/development/coding_guidelines.rst b/development/development/index.rst similarity index 65% rename from development/development/coding_guidelines.rst rename to development/development/index.rst index 9a7a0c10..56afbd3c 100644 --- a/development/development/coding_guidelines.rst +++ b/development/development/index.rst @@ -12,11 +12,10 @@ latest versions on area51: These documents are automatically updated when changes are made to them. -JavaScript Linting ------------------- - -We use JSHint and JSCS for checking the quality of the JavaScript—JSHint for -linting, and JSCS for ensuring consistent code. There is a .jshintrc and a -.jscs file in the root of the project, and your editor probably has a plugin -available which will show you when you violate these standards. +.. toctree:: + :maxdepth: 2 + php/index + js/index + css/index + html/index diff --git a/development/development/js/index.rst b/development/development/js/index.rst new file mode 100644 index 00000000..a7a08b12 --- /dev/null +++ b/development/development/js/index.rst @@ -0,0 +1,13 @@ +JavaScript Guidelines +===================== + +We use `XO.js `_ for checking the quality, linting, and ensuring consistent JS code standards. Its installed via npm as a module and is configured via the ``package.json`` file in the root. Your editor probably has a plugin available which will show you when you violate these standards. ``XO.js`` is an `ESLint `_ wrapper. Its essentially a custom `config `_ for ESlint, but simplifies the use as we do not have to maintain/update the standards. This means we do not need to manage an ``eslintrc`` file. + +.. 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 + +.. _PhpStorm: https://www.jetbrains.com/phpstorm/ +.. _ATOM: https://atom.io +.. _Editor Setup: /editor-setup + +.. toctree:: + :maxdepth: 2 diff --git a/development/development/php/character_set_and_encodings.rst b/development/development/php/character_set_and_encodings.rst new file mode 100644 index 00000000..b235e223 --- /dev/null +++ b/development/development/php/character_set_and_encodings.rst @@ -0,0 +1,62 @@ +5. Character Sets and Encodings +=============================== + +What are Unicode, UCS and UTF-8? +-------------------------------- + +The `Universal Character Set (UCS) `_ described in ISO/IEC 10646 consists of a large amount of characters. Each of them has a unique name and a code point which is an integer number. `Unicode `_ - which is an industry standard - complements the Universal Character Set with further information about the characters' properties and alternative character encodings. More information on Unicode can be found on the `Unicode Consortium's website `_. One of the Unicode encodings is the `8-bit Unicode Transformation Format (UTF-8) `_. It encodes characters with up to four bytes aiming for maximum compatibility with the `American Standard Code for Information Interchange `_ which is a 7-bit encoding of a relatively small subset of the UCS. + +phpBB's use of Unicode +++++++++++++++++++++++ + +Unfortunately PHP does not facilitate the use of Unicode prior to version 6. Most functions simply treat strings as sequences of bytes assuming that each character takes up exactly one byte. This behaviour still allows for storing UTF-8 encoded text in PHP strings but many operations on strings have unexpected results. To circumvent this problem we have created some alternative functions to PHP's native string operations which use code points instead of bytes. These functions can be found in ``/includes/utf/utf_tools.php``. A lot of native PHP functions still work with UTF-8 as long as you stick to certain restrictions. For example ``explode`` still works as long as the first and the last character of the delimiter string are ASCII characters. + +phpBB only uses the ASCII and the UTF-8 character encodings. Still all Strings are UTF-8 encoded because ASCII is a subset of UTF-8. The only exceptions to this rule are code sections which deal with external systems which use other encodings and character sets. Such external data should be converted to UTF-8 using the ``utf8_recode()`` function supplied with phpBB. It supports a variety of other character sets and encodings, a full list can be found below. + +With ``$request->variable()`` you can either allow all UCS characters in user input or restrict user input to ASCII characters. This feature is controlled by the method's third parameter called ``$multibyte``. You should allow multibyte characters in posts, PMs, topic titles, forum names, etc. but it's not necessary for internal uses like a ``$mode`` variable which should only hold a predefined list of ASCII strings anyway. + +.. code: php + // an input string containing a multibyte character + $_REQUEST['multibyte_string'] = 'Käse'; + + // print request variable as a UTF-8 string allowing multibyte characters + echo $request->variable('multibyte_string', '', true); + // print request variable as ASCII string + echo $request->variable('multibyte_string', ''); + +This code snippet will generate the following output: + +.. code: text + Käse + K??se + +Case Folding +++++++++++++ + +Case insensitive comparison of strings is no longer possible with ``strtolower`` or ``strtoupper`` as some characters have multiple lower case or multiple upper case forms depending on their position in a word. The ``utf8_strtolower`` and the ``utf8_strtoupper`` functions suffer from the same problem so they can only be used to display upper/lower case versions of a string but they cannot be used for case insensitive comparisons either. So instead you should use case folding which gives you a case insensitive version of the string which can be used for case insensitive comparisons. An NFC normalized string can be case folded using ``utf8_case_fold_nfc()``. + +**Bad - The strings might be the same even if strtolower differs:** + +.. code:: php + + if (strtolower($string1) == strtolower($string2)) + { + echo '$string1 and $string2 are equal or differ in case'; + } + +**Good - Case folding is really case insensitive:** + +.. code:: php + + if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2)) + { + echo '$string1 and $string2 are equal or differ in case'; + } + +Confusables Detection ++++++++++++++++++++++ + +phpBB offers a special method ``utf8_clean_string`` which can be used to make sure string identifiers are unique. +This method uses Normalization Form Compatibility Composition (NFKC) instead of NFC and replaces similarly looking +characters with a particular representative of the equivalence class. This method is currently used for usernames and +group names to avoid confusion with similarly looking names. diff --git a/development/development/php/defaults.rst b/development/development/php/defaults.rst new file mode 100644 index 00000000..0cc18455 --- /dev/null +++ b/development/development/php/defaults.rst @@ -0,0 +1,218 @@ +1. Introduction +=============== + +The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", +"**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**NOT RECOMMENDED**", "**MAY**", and "**OPTIONAL**" +in this document are to be interpreted as described in `BCP 14 ` [`RFC2119 `] [`RFC8174 `] when, +and only when, they appear in all capitals, as shown here. + +2. Defaults +=========== + +2.i. Editor Settings +-------------------- + +Tabs vs Spaces ++++++++++++++++ + +In order to make this as simple as possible, we will be using tabs, not spaces. We enforce 4 (four) spaces for one tab - therefore you need to set your tab width within your editor to 4 spaces. Make sure that when you **save** the file, it's saving tabs and not spaces. This way, we can each have the code be displayed the way we like it, without breaking the layout of the actual files. + +Tabs in front of lines are no problem, but having them within the text can be a problem if you do not set it to the amount of spaces every one of us uses. Here is a short example of how it should look like: + +.. code:: php + + {TAB}$mode{TAB}{TAB}= $request->variable('mode', ''); + {TAB}$search_id{TAB}= $request->variable('search_id', ''); + +If entered with tabs (replace the {TAB}) both equal signs need to be on the same column. + +Linefeeds +++++++++++ + +Ensure that your editor is saving files in the UNIX (LF) line ending format. This means that lines are terminated with a newline, not with Windows Line endings (CR/LF combo) as they are on Win32 or Classic Mac (CR) Line endings. Any decent editor should be able to do this, but it might not always be the default setting. Know your editor. If you want advice for an editor for your Operating System, just ask one of the developers. Some of them do their editing on Win32. + +2.ii. File Layout +----------------- + +Standard header for new files: +This template of the header must be included at the start of all phpBB files: + +.. code:: php + + /** + * + * This file is part of the phpBB Forum Software package. + * + * @copyright (c) phpBB Limited + * @license GNU General Public License, version 2 (GPL-2.0) + * + * For full copyright and license information, please see + * the docs/CREDITS.txt file. + * + */ + +Please see the `2.iii. File Locations`_ section for the correct package name. + +PHP closing tags +++++++++++++++++ + +A file containg only PHP code should not end with the optional PHP closing tag ``?>`` to avoid issues with whitespace following it. + +Newline at end of file +++++++++++++++++++++++ + +All files should end in a newline so the last line does not appear as modified in diffs, when a line is appended to the file. + +Files containing inline code +++++++++++++++++++++++++++++ + +For those files you have to put an empty comment directly after the header to prevent the documentor assigning the header to the first code element found. + +.. code:: php + + /** + * {HEADER} + */ + + /** + */ + {CODE} + +Files containing only functions ++++++++++++++++++++++++++++++++ + +Do not forget to comment the functions (especially the first function following the header). Each function should have +at least a comment of what this function does. For more complex functions it is recommended to document the parameters too. + +Files containing only classes ++++++++++++++++++++++++++++++ + +Do not forget to comment the class. Classes need a separate @package definition, it is the same as the header package +name. Apart from this special case the above statement for files containing only functions needs to be applied to +classes and it's methods too. + +Code following the header but only functions/classes file ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +If this case is true, the best method to avoid documentation confusions is adding an ignore command, for example: + +.. code:: php + + /** + * {HEADER} + */ + + /** + * @ignore + */ + Small code snipped, mostly one or two defines or an if statement + + /** + * {DOCUMENTATION} + */ + class ... + +2.iii. File Locations +--------------------- + +Functions used by more than one page should be placed in functions.php, functions specific to one page should be placed on that page (at the bottom) or within the relevant sections functions file. Some files in /includes are holding functions responsible for special sections, for example uploading files, displaying "things", user related functions and so forth. + +The following packages are defined, and related new features/functions should be placed within the mentioned files/locations, as well as specifying the correct package name. The package names are bold within this list: + +**phpBB** +Core files and all files not assigned to a separate package +**acm** +``/phpbb/cache`` +Cache System +**acp** +``/adm``, ``/includes/acp``, ``/includes/functions_admin.php`` +Administration Control Panel +**dbal** +``/phpbb/db``, ``/includes/db`` +Database Abstraction Layer. +``/phpbb/db/driver/`` +Database Abstraction Layer classes +``/phpbb/db/migration/`` +Migrations are used for updating the database from one release to another +**diff** +``/includes/diff`` +Diff Engine +**images** +``/images`` +All global images not connected to styles +**install** +``/install`` +Installation System +**language** +``/language`` +All language files +**login** +``/phpbb/auth`` +Login Authentication Plugins +**VC** +``/includes/captcha`` +CAPTCHA +**mcp** +``mcp.php``, ``/includes/mcp``, ``report.php`` +Moderator Control Panel +**ucp** +``ucp.php``, ``/includes/ucp`` +User Control Panel +**utf** +``/includes/utf`` +UTF8-related functions/classes +**search** +``/phpbb/search``, ``search.php`` +Search System +**styles** +``/styles`` +phpBB Styles/Templates/Themes + +2.iv. Special Constants +----------------------- + +There are some special constants application developers are able to utilize to bend some of phpBB's internal functionality to suit their needs. + +.. code:: php + + PHPBB_MSG_HANDLER (overwrite message handler) + PHPBB_DB_NEW_LINK (overwrite new_link parameter for sql_connect) + PHPBB_ROOT_PATH (overwrite $phpbb_root_path) + PHPBB_ADMIN_PATH (overwrite $phpbb_admin_path) + PHPBB_USE_BOARD_URL_PATH (use generate_board_url() for image paths instead of $phpbb_root_path) + PHPBB_DISABLE_ACP_EDITOR (disable ACP style editor for templates) + PHPBB_DISABLE_CONFIG_CHECK (disable ACP config.php writeable check) + + PHPBB_ACM_MEMCACHE_PORT (overwrite memcached port, default is 11211) + PHPBB_ACM_MEMCACHE_COMPRESS (overwrite memcached compress setting, default is disabled) + PHPBB_ACM_MEMCACHE_HOST (overwrite memcached host name, default is localhost) + + PHPBB_ACM_REDIS_HOST (overwrite redis host name, default is localhost) + PHPBB_ACM_REDIS_PORT (overwrite redis port, default is 6379) + PHPBB_ACM_REDIS_PASSWORD (overwrite redis password, default is empty) + PHPBB_ACM_REDIS_DB (overwrite redis default database) + + PHPBB_QA (Set board to QA-Mode, which means the updater also checks for RC-releases) + +PHPBB_USE_BOARD_URL_PATH +++++++++++++++++++++++++ + +If the ``PHPBB_USE_BOARD_URL_PATH`` constant is set to true, phpBB uses generate_board_url() (this will return the boards url with the script path included) on all instances where web-accessible images are loaded. The exact locations are: + +- /phpbb/user.php - \phpbb\user::img() +- /includes/functions_content.php - smiley_text() + +Path locations for the following template variables are affected by this too: + +- {T_ASSETS_PATH} - assets (non-style specific, static resources) +- {T_THEME_PATH} - styles/xxx/theme +- {T_TEMPLATE_PATH} - styles/xxx/template +- {T_SUPER_TEMPLATE_PATH} - styles/xxx/template +- {T_IMAGES_PATH} - images/ +- {T_SMILIES_PATH} - $config['smilies_path']/ +- {T_AVATAR_GALLERY_PATH} - $config['avatar_gallery_path']/ +- {T_ICONS_PATH} - $config['icons_path']/ +- {T_RANKS_PATH} - $config['ranks_path']/ +- {T_UPLOAD_PATH} - $config['upload_path']/ +- {T_STYLESHEET_LINK} - styles/xxx/theme/stylesheet.css +- New template variable {BOARD_URL} for the board url + script path. diff --git a/development/development/php/index.rst b/development/development/php/index.rst new file mode 100644 index 00000000..a0213726 --- /dev/null +++ b/development/development/php/index.rst @@ -0,0 +1,11 @@ +PHP Coding Guidelines +====================== + +.. toctree:: + :maxdepth: 2 + + defaults + layout_guidelines + templating + character_set_and_encodings +.. translation_guidelines diff --git a/development/development/php/layout_guidelines.rst b/development/development/php/layout_guidelines.rst new file mode 100644 index 00000000..203f3857 --- /dev/null +++ b/development/development/php/layout_guidelines.rst @@ -0,0 +1,1046 @@ +3. Code Layout/Guidelines +========================= + +Please note that these guidelines apply to all php, html, javascript and css files. + +3.i. Variable/Function/Class Naming +----------------------------------- + +We will not be using any form of hungarian notation in our naming conventions. Many of us believe that hungarian naming is one of the primary code obfuscation techniques currently in use. + +Variable Names +++++++++++++++ + +In PHP, variable names should be in all lowercase, with words separated by an underscore, example: + +``$current_user`` is right, but ``$currentuser`` and ``$currentUser`` are not. + +In JavaScript, variable names should use camel case: + +``currentUser`` is right, but ``currentuser`` and ``current_user`` are not. + +Names should be descriptive, but concise. We don't want huge sentences as our variable names, but typing an extra couple of characters is always better than wondering what exactly a certain variable is for. + +Loop Indices +++++++++++++ + +The **only** situation where a one-character variable name is allowed is when it's the index for some looping construct. In this case, the index of the outer loop should always be ``$i``. If there's a loop inside that loop, its index should be ``$j``, followed by ``$k``, and so on. If the loop is being indexed by some already-existing variable with a meaningful name, this guideline does not apply, example: + +.. code:: php + + for ($i = 0; $i < $outer_size; $i++) + { + for ($j = 0; $j < $inner_size; $j++) + { + foo($i, $j); + } + } + +Function Names +++++++++++++++ + +Functions should also be named descriptively. We're not programming in C here, we don't want to write functions called things like "stristr()". Again, all lower-case names with words separated by a single underscore character in PHP, and camel caps in JavaScript. Function names should be prefixed with `phpbb_` and preferably have a verb in them somewhere. Good function names are ``phpbb_print_login_status()``, ``phpbb_get_user_data()``, etc. Constructor functions in JavaScript should begin with a capital letter. + +Function Arguments +++++++++++++++++++ + +Arguments are subject to the same guidelines as variable names. We don't want a bunch of functions like: ``do_stuff($a, $b, $c)``. In most cases, we'd like to be able to tell how to use a function by just looking at its declaration. + +Class Names ++++++++++++ + +Apart from following the rules for function names, all classes should meet the following conditions: + +- Every class must be defined in a separate file. +- The classes have to be located in a subdirectory of ``phpbb/``. +- Classnames must be namespaced with ``\phpbb\`` to avoid name clashes. +- Class names/namespaces have to reflect the location of the file they are defined in. The namespace must be the directory in which the file is located. So the directory names must not contain any underscores, but the filename may. +- Directories should typically be a singular noun (e.g. ``dir`` in the example below, not ``dirs``. + +So given the following example directory structure you would result in the below listed lookups + +.. code:: text + + phpbb/ + class_name.php + dir/ + class_name.php + subdir/ + class_name.php + +.. code:: text + + \phpbb\class_name - phpbb/class_name.php + \phpbb\dir\class_name - phpbb/dir/class_name.php + \phpbb\dir\subdir\class_name - phpbb/dir/subdir/class_name.php + +Summary ++++++++ + +The basic philosophy here is to not hurt code clarity for the sake of laziness. This has to be balanced by a little bit of common sense, though; ``phpbb_print_login_status_for_a_given_user()`` goes too far, for example -- that function would be better named ``phpbb_print_user_login_status()``, or just ``phpbb_print_login_status()``. + +Special Namings ++++++++++++++++ + +For all emoticons use the term ``smiley`` in singular and ``smilies`` in plural. For emails we use the term ``email`` (without dash between “e” and “m”). + +3.ii. Code Layout +----------------- + +Always include the braces ++++++++++++++++++++++++++ + +This is another case of being too lazy to type 2 extra characters causing problems with code clarity. Even if the body of some construct is only one line long, do not drop the braces. Just don't, examples: + +**These are all wrong:** + +.. code:: php + + if (condition) do_stuff(); + + if (condition) + do_stuff(); + + while (condition) + do_stuff(); + + for ($i = 0; $i < size; $i++) + do_stuff($i); + +**These are all right:** + +.. code:: php + + if (condition) + { + do_stuff(); + } + + while (condition) + { + do_stuff(); + } + + for ($i = 0; $i < size; $i++) + { + do_stuff(); + } + +Where to put the braces ++++++++++++++++++++++++ + +In PHP code, braces always go on their own line. The closing brace should also always be at the same column as the corresponding opening brace, examples: + +.. code:: php + + if (condition) + { + while (condition2) + { + ... + } + } + else + { + ... + } + + for ($i = 0; $i < $size; $i++) + { + ... + } + + while (condition) + { + ... + } + + function do_stuff() + { + ... + } + +Use spaces between tokens ++++++++++++++++++++++++++ + +This is another simple, easy step that helps keep code readable without much effort. Whenever you write an assignment, expression, etc.. Always leave one space between the tokens. Basically, write code as if it was English. Put spaces between variable names and operators. Don't put spaces just after an opening bracket or before a closing bracket. Don't put spaces just before a comma or a semicolon. This is best shown with a few examples, examples: + +**Each pair shows the wrong way followed by the right way:** + +.. code:: php + + $i=0; + $i = 0; + + if($i<7) ... + if ($i < 7) ... + + if ( ($i < 7)&&($j > 8) ) ... + if ($i < 7 && $j > 8) ... + + do_stuff( $i, 'foo', $b ); + do_stuff($i, 'foo', $b); + + for($i=0; $i<$size; $i++) ... + for ($i = 0; $i < $size; $i++) ... + + $i=($j < $size)?0:1; + $i = ($j < $size) ? 0 : 1; + +Operator precedence ++++++++++++++++++++ + +Do you know the exact precedence of all the operators in PHP? Neither do I. Don't guess. Always make it obvious by using brackets to force the precedence of an equation so you know what it does. Remember to not over-use this, as it may harden the readability. Basically, do not enclose single expressions. Examples: + +**What's the result? who knows:** + +``$bool = ($i < 7 && $j > 8 || $k == 4);`` + +**Now you can be certain what I'm doing here:** + +``$bool = (($i < 7) && (($j < 8) || ($k == 4)));`` + +**But this one is even better, because it is easier on the eye but the intention is preserved:** + +``$bool = ($i < 7 && ($j < 8 || $k == 4));`` + +Quoting strings ++++++++++++++++ + +There are two different ways to quote strings in PHP - either with single quotes or with double quotes. The main difference is that the parser does variable interpolation in double-quoted strings, but not in single quoted strings. Because of this, you should always use single quotes unless you specifically need variable interpolation to be done on that string. This way, we can save the parser the trouble of parsing a bunch of strings where no interpolation needs to be done. + +Also, if you are using a string variable as part of a function call, you do not need to enclose that variable in quotes. Again, this will just make unnecessary work for the parser. Note, however, that nearly all of the escape sequences that exist for double-quoted strings will not work with single-quoted strings. Be careful, and feel free to break this guideline if it's making your code easier to read, examples: + +**Wrong:** + +.. code:: php + + $str = "This is a really long string with no variables for the parser to find."; + + do_stuff("$str"); + +**Right:** + +.. code:: php + + $str = 'This is a really long string with no variables for the parser to find.'; + + do_stuff($str); + +**Sometimes single quotes are just not right:** + +.. code:: php + + $post_url = $phpbb_root_path . 'posting.' . $phpEx . '?mode=' . $mode . '&start=' . $start; + +**Double quotes are sometimes needed to not overcrowd the line with concatenations:** + +.. code:: php + + $post_url = "{$phpbb_root_path}posting.$phpEx?mode=$mode&start=$start"; + +In SQL statements mixing single and double quotes is partly allowed (following the guidelines listed here about SQL formatting), else one should try to only use one method - mostly single quotes. + +Array syntax +++++++++++++ + +Short array syntax is preferred over the classical array syntax and **SHOULD** be used. + +**Not recommended:** + +.. code:: php + + $foo = array( + 'bar' => 42, + 'boo' => 23, + ); + +**Recommended:** + +.. code:: php + + $foo = [ + 'bar' => 42, + 'boo' => 23, + ]; + + +Commas after every array element +++++++++++++++++++++++++++++++++ + +If an array is defined with each element on its own line, you still have to modify the previous line to add a comma when appending a new element. PHP allows for trailing (useless) commas in array definitions. These should always be used so each element including the comma can be appended with a single line. In JavaScript, do not use the trailing comma, as it causes browsers to throw errors. + +**Wrong:** + +.. code:: php + + $foo = [ + 'bar' => 42, + 'boo' => 23 + ]; + +**Right:** + +.. code:: php + + $foo = [ + 'bar' => 42, + 'boo' => 23, + ]; + +Associative array keys +++++++++++++++++++++++ + +In PHP, it's legal to use a literal string as a key to an associative array without quoting that string. We don't want to do this -- the string should always be quoted to avoid confusion. Note that this is only when we're using a literal, not when we're using a variable, examples: + +**Wrong:** + +.. code:: php + + $foo = $assoc_array[blah]; + +**Right:** + +.. code:: php + + $foo = $assoc_array['blah']; + +**Wrong:** + +.. code:: php + + $foo = $assoc_array["$var"]; + +**Right:** + +.. code:: php + + $foo = $assoc_array[$var]; + +Comments +++++++++ + +Each complex function should be preceded by a comment that tells a programmer everything they need to know to use that function. The meaning of every parameter, the expected input, and the output are required as a minimal comment. The function's behaviour in error conditions (and what those error conditions are) should also be present - but mostly included within the comment about the output. + +Especially important to document are any assumptions the code makes, or preconditions for its proper operation. Any one of the developers should be able to look at any part of the application and figure out what's going on in a reasonable amount of time. + +Avoid using ``/* */`` comment blocks for one-line comments, ``//`` should be used for one/two-liners. + +Magic numbers ++++++++++++++ + +Don't use them. Use named constants for any literal value other than obvious special cases. Basically, it's ok to check if an array has 0 elements by using the literal 0. It's not ok to assign some special meaning to a number and then use it everywhere as a literal. This hurts readability AND maintainability. The constants ``true` and `false`` should be used in place of the literals 1 and 0 -- even though they have the same values (but not type!), it's more obvious what the actual logic is when you use the named constants. Typecast variables where it is needed, do not rely on the correct variable type (PHP is currently very loose on typecasting which can lead to security problems if a developer does not keep a very close eye on it). + +Shortcut operators +++++++++++++++++++ + +The only shortcut operators that cause readability problems are the shortcut increment $i++ and decrement $j-- operators. These operators should not be used as part of an expression. They can, however, be used on their own line. Using them in expressions is just not worth the headaches when debugging, examples: + +**Wrong:** + +.. code:: php + + $array[++$i] = $j; + $array[$i++] = $k; + +**Right:** + +.. code:: php + + $i++; + $array[$i] = $j; + + $array[$i] = $k; + $i++; + +Inline conditionals ++++++++++++++++++++ + +Inline conditionals should only be used to do very simple things. Preferably, they will only be used to do assignments, and not for function calls or anything complex at all. They can be harmful to readability if used incorrectly, so don't fall in love with saving typing by using them, examples: + +**Bad place to use them:** + +.. code:: php + + ($i < $size && $j > $size) ? do_stuff($foo) : do_stuff($bar); + +**OK place to use them:** + +.. code:: php + + $min = ($i < $j) ? $i : $j; + +Don't use uninitialized variables ++++++++++++++++++++++++++++++++++ + +For phpBB, we intend to use a higher level of run-time error reporting. This will mean that the use of an uninitialized variable will be reported as a warning. These warnings can be avoided by using the built-in isset() function to check whether a variable has been set - but preferably the variable is always existing. For checking if an array has a key set this can come in handy though, examples: + +**Wrong:** + +.. code:: php + + if ($forum) ... + +**Right:** + +.. code:: php + + if (isset($forum)) ... + +**Also possible:** + +.. code:: php + + if (isset($forum) && $forum == 5) + +The ``empty()`` function is useful if you want to check if a variable is not set or being empty (an empty string, 0 as an integer or string, NULL, false, an empty array or a variable declared, but without a value in a class). Therefore empty should be used in favor of ``isset($array) && count($array) > 0`` - this can be written in a shorter way as ``!empty($array)``. + +Switch statements ++++++++++++++++++ + +Switch/case code blocks can get a bit long sometimes. To have some level of notice and being in-line with the opening/closing brace requirement (where they are on the same line for better readability), this also applies to switch/case code blocks and the breaks. An example: + +**Wrong:** + +.. code:: php + + switch ($mode) + { + case 'mode1': + // I am doing something here + break; + case 'mode2': + // I am doing something completely different here + break; + } + +**Good:** + + +.. code:: php + + switch ($mode) + { + case 'mode1': + // I am doing something here + break; + + case 'mode2': + // I am doing something completely different here + break; + + default: + // Always assume that a case was not caught + break; + } + +**Also good, if you have more code between the case and the break:** + +.. code:: php + + switch ($mode) + { + case 'mode1': + + // I am doing something here + + break; + + case 'mode2': + + // I am doing something completely different here + + break; + + default: + + // Always assume that a case was not caught + + break; + } + +Even if the break for the default case is not needed, it is sometimes better to include it just for readability and completeness. + +If no break is intended, please add a comment instead. An example: + +**Example with no break:** + +.. code:: php + + switch ($mode) + { + case 'mode1': + + // I am doing something here + + // no break here + + case 'mode2': + + // I am doing something completely different here + + break; + + default: + + // Always assume that a case was not caught + + break; + } + +Class Members ++++++++++++++ + +Use the explicit visibility qualifiers ``public``, ``private`` and ``protected`` for all properties instead of ``var``. + +Place the ``static`` qualifier *after* the visibility qualifiers. + +**Wrong:** + +.. code:: php + + var $x; + static private function f() + +**Right:** + +.. code:: php + + public $x; + private static function f() + +Constants ++++++++++ + +Prefer class constants over global constants created with ``define()``. + +Type declarations ++++++++++++++++++ + +Use type declarations for arguments, properties and return types. +The declaration of return types is optional for ``void`` types but preferred for uniformity. + +There **SHALL BE** *no* space before the colon and *exactly* one space after the colon for type declarations. + +**Wrong:** + +.. code:: php + + public $x; + + private function do_stuff($input) : string + { + return $input . 'appended'; + } + +**Right:** + +.. code:: php + + public int $x; + + private function do_stuff(string $input): string + { + return $input . 'appended'; + } + +`Union types ` **SHALL** be used when more than one type is allowed. This does also include nullable types. +The `null` type **SHALL** be the last element, other types **SHALL** follow alphabetical order. + +**Wrong:** + +.. code:: php + + public bool|int|null|string $x; + + private function do_stuff(?string $input) : ?string + { + return $input !== null ? $input . 'appended' : null; + } + +**Right:** + +.. code:: php + + public bool|int|string|null $x; + + private function do_stuff(string|null $input): string|null + { + return $input !== null ? $input . 'appended' : null; + } + +3.iii. SQL/SQL Layout +--------------------- + +Common SQL Guidelines ++++++++++++++++++++++ + +All SQL should be cross-DB compatible, if DB specific SQL is used alternatives must be provided which work on all supported DB's (MySQL3/4/5, MSSQL (7.0 and 2000), PostgreSQL (8.3+), SQLite, Oracle8, ODBC (generalised if possible)). + +All SQL commands should utilise the DataBase Abstraction Layer (DBAL) + +SQL code layout ++++++++++++++++ + +SQL Statements are often unreadable without some formatting, since they tend to be big at times. Though the formatting of sql statements adds a lot to the readability of code. SQL statements should be formatted in the following way, basically writing keywords: + +.. code:: php + + $sql = 'SELECT * + <-one tab->FROM ' . SOME_TABLE . ' + <-one tab->WHERE a = 1 + <-two tabs->AND (b = 2 + <-three tabs->OR b = 3) + <-one tab->ORDER BY b'; + +**Here the example with the tabs applied:** + +.. code:: php + + $sql = 'SELECT * + FROM ' . SOME_TABLE . ' + WHERE a = 1 + AND (b = 2 + OR b = 3) + ORDER BY b'; + +SQL Quotes +++++++++++ + +Use double quotes where applicable. (The variables in these examples are typecasted to integers beforehand.) Examples: + +**Wrong:** + +.. code:: php + + "UPDATE " . SOME_TABLE . " SET something = something_else WHERE a = $b"; + + 'UPDATE ' . SOME_TABLE . ' SET something = ' . $user_id . ' WHERE a = ' . $something; + +**Right:** + +.. code:: php + + 'UPDATE ' . SOME_TABLE . " SET something = something_else WHERE a = $b"; + + 'UPDATE ' . SOME_TABLE . " SET something = $user_id WHERE a = $something"; + +In other words use single quotes where no variable substitution is required or where the variable involved shouldn't appear within double quotes. Otherwise use double quotes. + +Avoid DB specific SQL ++++++++++++++++++++++ + +The "not equals operator", as defined by the SQL:2003 standard, is "<>" + +**Wrong:** + +.. code:: php + + $sql = 'SELECT * + FROM ' . SOME_TABLE . ' + WHERE a != 2'; + +**Right:** + +.. code:: php + + $sql = 'SELECT * + FROM ' . SOME_TABLE . ' + WHERE a <> 2'; + +Common DBAL methods ++++++++++++++++++++ + +sql_escape() +^^^^^^^^^^^^ + +Always use ``$db->sql_escape()`` if you need to check for a string within an SQL statement (even if you are sure the variable cannot contain single quotes - never trust your input), for example: + +.. code:: php + + $sql = 'SELECT * + FROM ' . SOME_TABLE . " + WHERE username = '" . $db->sql_escape($username) . "'"; + +sql_query_limit() +^^^^^^^^^^^^^^^^^ + +We do not add limit statements to the sql query, but instead use ``$db->sql_query_limit()``. You basically pass the query, the total number of lines to retrieve and the offset. + +Note: Since Oracle handles limits differently and because of how we implemented this handling you need to take special care if you use ``sql_query_limit`` with an sql query retrieving data from more than one table. + +Make sure when using something like "SELECT x.\*, y.jars" that there is not a column named jars in x; make sure that there is no overlap between an implicit column and the explicit columns. + +sql_build_array() +^^^^^^^^^^^^^^^^^ + +If you need to UPDATE or INSERT data, make use of the ``$db->sql_build_array()`` function. This function already escapes strings and checks other types, so there is no need to do this here. The data to be inserted should go into an array - ``$sql_ary`` - or directly within the statement if one or two variables needs to be inserted/updated. An example of an insert statement would be: + +.. code:: php + + $sql_ary = [ + 'somedata' => $my_string, + 'otherdata' => $an_int, + 'moredata' => $another_int, + ]; + + $db->sql_query('INSERT INTO ' . SOME_TABLE . ' ' . $db->sql_build_array('INSERT', $sql_ary)); + +To complete the example, this is how an update statement would look like: + +.. code:: php + + $sql_ary = [ + 'somedata' => $my_string, + 'otherdata' => $an_int, + 'moredata' => $another_int, + ]; + + $sql = 'UPDATE ' . SOME_TABLE . ' + SET ' . $db->sql_build_array('UPDATE', $sql_ary) . ' + WHERE user_id = ' . (int) $user_id; + $db->sql_query($sql); + +The ``$db->sql_build_array()`` function supports the following modes: ``INSERT`` (example above), ``INSERT_SELECT`` (building query for ``INSERT INTO table (...) SELECT value, column ...`` statements), ``UPDATE`` (example above) and ``SELECT`` (for building WHERE statement [AND logic]). + +sql_multi_insert() +^^^^^^^^^^^^^^^^^^ + +If you want to insert multiple statements at once, please use the separate ``sql_multi_insert()`` method. An example: + +.. code:: php + + $sql_ary = []; + + $sql_ary[] = [ + 'somedata' => $my_string_1, + 'otherdata' => $an_int_1, + 'moredata' => $another_int_1, + ]; + + $sql_ary[] = [ + 'somedata' => $my_string_2, + 'otherdata' => $an_int_2, + 'moredata' => $another_int_2, + ]; + + $db->sql_multi_insert(SOME_TABLE, $sql_ary); + +sql_in_set() +^^^^^^^^^^^^ + +The ``$db->sql_in_set()`` function should be used for building ``IN ()`` and ``NOT IN ()`` constructs. Since (specifically) MySQL tend to be faster if for one value to be compared the ``=`` and ``<>`` operator is used, we let the DBAL decide what to do. A typical example of doing a positive match against a number of values would be: + +.. code:: php + + $sql = 'SELECT * + FROM ' . FORUMS_TABLE . ' + WHERE ' . $db->sql_in_set('forum_id', $forum_ids); + $db->sql_query($sql); + +Based on the number of values in $forum_ids, the query can look differently. + +**SQL Statement if $forum_ids = [1, 2, 3];** + +.. code:: php + + SELECT FROM phpbb_forums WHERE forum_id IN (1, 2, 3) + +**SQL Statement if $forum_ids = [1] or $forum_ids = 1** + +.. code:: php + + SELECT FROM phpbb_forums WHERE forum_id = 1 + +Of course the same is possible for doing a negative match against a number of values: + +.. code:: php + + $sql = 'SELECT * + FROM ' . FORUMS_TABLE . ' + WHERE ' . $db->sql_in_set('forum_id', $forum_ids, true); + $db->sql_query($sql); + +Based on the number of values in $forum_ids, the query can look differently here too. + +**SQL Statement if $forum_ids = [1, 2, 3];** + +.. code:: php + + SELECT FROM phpbb_forums WHERE forum_id NOT IN (1, 2, 3) + +**SQL Statement if $forum_ids = [1] or $forum_ids = 1** + +.. code:: php + + SELECT FROM phpbb_forums WHERE forum_id <> 1 + +If the given array is empty, an error will be produced. + +sql_build_query() +^^^^^^^^^^^^^^^^^ + +The ``$db->sql_build_query()`` function is responsible for building sql statements for SELECT and SELECT DISTINCT queries if you need to JOIN on more than one table or retrieve data from more than one table while doing a JOIN. This needs to be used to make sure the resulting statement is working on all supported db's. Instead of explaining every possible combination, I will give a short example: + +.. code:: php + + $sql_array = [ + 'SELECT' => 'f.*, ft.mark_time', + + 'FROM' => [ + FORUMS_WATCH_TABLE => 'fw', + FORUMS_TABLE => 'f', + ], + + 'LEFT_JOIN' => [ + [ + 'FROM' => [FORUMS_TRACK_TABLE => 'ft'], + 'ON' => 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id', + ], + ], + + 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' + AND f.forum_id = fw.forum_id', + + 'ORDER_BY' => 'left_id', + ]; + + $sql = $db->sql_build_query('SELECT', $sql_array); + +The possible first parameter for sql_build_query() is SELECT or SELECT_DISTINCT. As you can see, the logic is pretty self-explaining. For the LEFT_JOIN key, just add another array if you want to join on to tables for example. The added benefit of using this construct is that you are able to easily build the query statement based on conditions - for example the above LEFT_JOIN is only necessary if server side topic tracking is enabled; a slight adjustement would be: + +.. code:: php + + $sql_array = [ + 'SELECT' => 'f.*', + + 'FROM' => [ + FORUMS_WATCH_TABLE => 'fw', + FORUMS_TABLE => 'f', + ], + + 'WHERE' => 'fw.user_id = ' . $user->data['user_id'] . ' + AND f.forum_id = fw.forum_id', + + 'ORDER_BY' => 'left_id', + ]; + + if ($config['load_db_lastread']) + { + $sql_array['LEFT_JOIN'] = [ + [ + 'FROM' => [FORUMS_TRACK_TABLE => 'ft'], + 'ON' => 'ft.user_id = ' . $user->data['user_id'] . ' AND ft.forum_id = f.forum_id', + ], + ]; + + $sql_array['SELECT'] .= ', ft.mark_time '; + } + else + { + // Here we read the cookie data + } + + $sql = $db->sql_build_query('SELECT', $sql_array); + +3.iv. Optimizations +------------------- + +Operations in loop definition: +++++++++++++++++++++++++++++++ + +Always try to optimize your loops if operations are going on at the comparing part, since this part is executed every time the loop is parsed through. For assignments a descriptive name should be chosen. Example: + +**On every iteration the count function is called:** + +.. code:: php + + for ($i = 0; $i < count($post_data); $i++) + { + do_something(); + } + +**You are able to assign the (not changing) result within the loop itself:** + +.. code:: php + + for ($i = 0, $size = count($post_data); $i < $size; $i++) + { + do_something(); + } + +Use of in_array() +^^^^^^^^^^^^^^^^^ + +Try to avoid using ``in_array()`` on huge arrays, and try to not place them into loops if the array to check consist of more than 20 entries. ``in_array()`` can be very time consuming and uses a lot of cpu processing time. For little checks it is not noticeable, but if checked against a huge array within a loop those checks alone can take several seconds. If you need this functionality, try using ``isset()`` on the arrays keys instead, actually shifting the values into keys and vice versa. A call to ``isset($array[$var])`` is a lot faster than ``in_array($var, array_keys($array))`` for example. + +3.v. General Guidelines +----------------------- + +General things +++++++++++++++ + +Never trust user input (this also applies to server variables as well as cookies). + +Try to sanitize values returned from a function. + +Try to sanitize given function variables within your function. + +The auth class should be used for all authorisation checking. + +No attempt should be made to remove any copyright information (either contained within the source or displayed interactively when the source is run/compiled), neither should the copyright information be altered in any way (it may be added to). + +Variables ++++++++++ + +Make use of the ``\phpbb\request\request`` class for everything. + +The $request->variable() method determines the type to set from the second parameter (which determines the default value too). If you need to get a scalar variable type, you need to tell this the variable() method explicitly. Examples: + +**Old method, do not use it:** + +.. code:: php + + $start = (isset($HTTP_GET_VARS['start'])) ? intval($HTTP_GET_VARS['start']) : intval($HTTP_POST_VARS['start']); + $submit = (isset($HTTP_POST_VARS['submit'])) ? true : false; + +**Use request var and define a default variable (use the correct type):** + +.. code:: php + + $start = $request->variable('start', 0); + $submit = $request->is_set_post('submit'); + +**$start is an int, the following use of $request->variable() therefore is not allowed:** + +.. code:: php + + $start = $request->variable('start', '0'); + +**Getting an array, keys are integers, value defaults to 0:** + +.. code:: php + + $mark_array = $request->variable('mark', [0]); + +**Getting an array, keys are strings, value defaults to 0:** + +.. code:: php + + $action_ary = $request->variable('action', ['' => 0]); + +Login checks/redirection +++++++++++++++++++++++++ + +To show a forum login box use ``login_forum_box($forum_data)``, else use the ``login_box()`` function. + +``$forum_data`` should contain at least the ``forum_id`` and ``forum_password`` fields. If the field ``forum_name`` is available, then it is displayed on the forum login page. + +The ``login_box()`` function can have a redirect as the first parameter. As a thumb of rule, specify an empty string if you want to redirect to the users current location, else do not add the ``$SID`` to the redirect string (for example within the ucp/login we redirect to the board index because else the user would be redirected to the login screen). + +Sensitive Operations +++++++++++++++++++++ + +For sensitive operations always let the user confirm the action. For the confirmation screens, make use of the ``confirm_box()`` function. + +Altering Operations ++++++++++++++++++++ + +For operations altering the state of the database, for instance posting, always verify the form token, unless you are already using ``confirm_box()``. To do so, make use of the ``add_form_key()`` and ``check_form_key()`` functions. + +.. code:: php + + add_form_key('my_form'); + + if ($submit) + { + if (!check_form_key('my_form')) + { + trigger_error('FORM_INVALID'); + } + } + +The string passed to ``add_form_key()`` needs to match the string passed to ``check_form_key()``. Another requirement for this to work correctly is that all forms include the ``{S_FORM_TOKEN}`` template variable. + +Sessions +++++++++ + +Sessions should be initiated on each page, as near the top as possible using the following code: + +.. code:: php + + $user->session_begin(); + $auth->acl($user->data); + $user->setup(); + +The ``$user->setup()`` call can be used to pass on additional language definition and a custom style (used in viewforum). + +Errors and messages ++++++++++++++++++++ + +All messages/errors should be outputted by calling ``trigger_error()`` using the appropriate message type and language string. Example: + +.. code:: php + + trigger_error('NO_FORUM'); + +.. code:: php + + trigger_error($user->lang['NO_FORUM']); + +.. code:: php + + trigger_error('NO_MODE', E_USER_ERROR); + +Url formatting +++++++++++++++ + +All urls pointing to internal files need to be prepended by the ``$phpbb_root_path`` variable. +Within the administration control panel all urls pointing to internal files need to be prepended by the ``$phpbb_admin_path variable``. +This makes sure the path is always correct and users being able to just rename the admin folder and the acp still +working as intended (though some links will fail and the code need to be slightly adjusted). + +The ``append_sid()`` function from 2.0.x is available too, though it does not handle url alterations automatically. Please have a look at the code documentation if you want to get more details on how to use append_sid(). A sample call to append_sid() can look like this: + +.. code:: php + + append_sid("{$phpbb_root_path}memberlist.$phpEx", 'mode=group&g=' . $row['group_id']) + +General function usage +++++++++++++++++++++++ + +Some of these functions are only chosen over others because of personal preference and have no benefit other than maintaining consistency throughout the code. + +Use ``strpos`` instead of ``strstr`` + +Use ``else if`` instead of ``elseif`` + +Use ``false`` (lowercase) instead of ``FALSE`` + +Use ``true`` (lowercase) instead of ``TRUE`` + +Exiting ++++++++ + +Your page should either call ``page_footer()`` in the end to trigger output through the template engine and terminate the script, or alternatively at least call the ``exit_handler()``. That call is necessary because it provides a method for external applications embedding phpBB to be called at the end of the script. + +3.vi. Restrictions on the Use of PHP +------------------------------------ + +Dynamic code execution +++++++++++++++++++++++ + +Never execute dynamic PHP code (generated or in a constant string) using any of the following PHP functions: + +- eval +- create_function +- preg_replace with the **e** modifier in the pattern + +If absolutely necessary a file should be created, and a mechanism for creating this file prior to running phpBB should be provided as a setup process. + +The e modifier in **preg_replace** can be replaced by **preg_replace_callback** and objects to encapsulate state that is needed in the callback code. + +Other functions, operators, statements and keywords: +The following PHP statements should also not be used in phpBB: + +- goto diff --git a/development/development/php/templating.rst b/development/development/php/templating.rst new file mode 100644 index 00000000..fc617ed9 --- /dev/null +++ b/development/development/php/templating.rst @@ -0,0 +1,547 @@ +4. Templating +============= + +4.i. General Templating +----------------------- + +File naming ++++++++++++ + +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 **SHALL** be named appropriately using underscores for spaces (`snake_case`). + +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 **SHALL** use the twig syntax as follows: + +.. code-block:: html + + {% for item in loopname %} + markup, {{ item.X_YYYYY }}, etc. + {% endfor %} + +Further instructions on how to use loops will follow in section `Extended syntax for Blocks/Loops`_. + +.. warning:: + + 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 + + + markup, {loopname.X_YYYYY}, etc. + + +.. seealso:: + + - `for - Tags - Twig Documentation `_ + +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: + +.. code-block:: twig + + {% include 'filename' %} + +For example, to include the overall header or a custom menu bar: + +.. code-block:: twig + + {% include 'overall_header.html' %} + {% include 'simple_header.html' %} + +You can also include a template file using a variable: + +.. code-block:: twig + + {% include FILE_VAR %} + +Template-defined variables can be used as well: + +.. code-block:: twig + + {% set SOME_VAR = 'my_file.html' %} + {% include SOME_VAR %} + +.. seealso:: + + - `Twig for Template Designers - Including other templates `_ + +Conditionals/Control structures ++++++++++++++++++++++++++++++++ + +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. + +.. warning:: + + 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. + + .. code:: html + + + markup + + +Twig offers a clear and flexible way to handle logic in templates. The basic form of a conditional in Twig is: + +.. code-block:: twig + + {% if expr %} + markup + {% endif %} + +The `expr` can take many forms. For example, to check if the current loop iteration is even: + +.. code-block:: twig + + {% if loop.index is even %} + markup + {% endif %} + +This will output the markup if the current loop index is even. Twig supports a wide range of comparison and logical operators, including: + +.. code-block:: text + + ==, !=, ==, >, <, >=, <=, and, or, not, in, is, matches, starts with, ends with, contains, has some, has every + +You can also use parentheses to group expressions and enforce operator precedence. + +Twig provides special tests for common checks: + +.. code-block:: text + + even, odd, divisible by, defined, iterable, empty, null, same as + +For example: + +.. code-block:: twig + + {% if loop.index is divisible by(3) %} + markup + {% endif %} + +Twig also supports `if`/`elseif`/`else` chains: + +.. code-block:: twig + + {% if expr1 %} + markup + {% elseif expr2 %} + markup + {% else %} + markup + {% endif %} + +Each condition is checked in order, and the first matching block is rendered. + +Here are some practical examples: + +**Row coloration in a table:** + +.. code-block:: twig + + + {% for row in rows %} + {% if loop.index is even %} + + {% else %} + + {% endif %} + + + {% endfor %} +
HELLO!
+ +This will use `row1` for even rows and `row2` for odd rows. + +**Gradient effect based on row count:** + +.. code-block:: twig + + + {% for row in rows %} + {% if loop.index > 10 %} + + {% elseif loop.index > 5 %} + + {% elseif loop.index > 2 %} + + {% else %} + + {% endif %} + + + {% endfor %} +
hello!
+ +This will output different background colors depending on the row index. + +**Checking user login state:** + +.. code-block:: twig + + {% if S_USER_LOGGED_IN %} + markup + {% endif %} + +.. seealso:: + + - `Twig for Template Designers - Control Structures `_ + - `Twig for Template Designers - Operators `_ + +Extended syntax for Blocks/Loops +++++++++++++++++++++++++++++++++ + +Twig provides powerful features for working with loops, including setting start and end points, handling empty loops, and working with nested loops. + +**Setting start and end points of a loop:** + +You can use the `slice` filter to control which items are iterated over: + +.. code-block:: twig + + {# Start loop on the third entry (index 2) #} + {% for item in loopname|slice(2) %} + {{ item }} + {% endfor %} + + {# Start two entries from the end #} + {% for item in loopname|slice(-2) %} + {{ item }} + {% endfor %} + + {# Start at index 3 and end at index 4 (2 items) #} + {% for item in loopname|slice(3, 2) %} + {{ item }} + {% endfor %} + + {# Start at index 3 and end four from last #} + {% for item in loopname|slice(3, loopname|length - 3 - 4) %} + {{ item }} + {% endfor %} + +**Handling empty loops:** + +Twig provides the `else` block for loops: + +.. code-block:: twig + + {% for item in loop %} + {{ item }} + {% else %} + No items found. + {% endfor %} + +**Checking if a loop contains values:** + +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 %} + +Or simply use the `else` block as above. + +**Checking the number of items in a loop:** + +.. code-block:: twig + + {% if loop|length > 2 %} + {% for item in loop %} + {{ item }} + {% endfor %} + {% else %} + Not enough items. + {% endif %} + +**Nesting loops:** + +Twig supports nested loops naturally: + +.. code-block:: html + + {% for first in firstloop %} + {{ first.MY_VARIABLE_FROM_FIRSTLOOP }} + + {% for second in first.secondloop %} + {{ second.MY_VARIABLE_FROM_SECONDLOOP }} + {% endfor %} + {% endfor %} + +**Breaking out of nested loops and working with special variables:** + +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-block:: html + + {% 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 %} + {% endfor %} +
+ {% endif %} + +
    + {% 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 **SHALL** include the ``{{ S_FORM_TOKEN }}`` template variable. + +.. code:: html + +
    + +
    + + + {{ S_FORM_TOKEN }} +
    +
    + + +4.ii. Styles Tree +----------------- + +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. + +.. note:: + + 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 **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 +++++++++++++++++++++++++++++++++ + +- An event name must be all lowercase, with each word separated by an underscore. +- An event name must briefly describe the location and purpose of the event. +- An event name must end with one of the following suffixes: + - ``_prepend`` - This event adds an item to the beginning of a block of related items, or adds to the beginning of individual items in a block. + - ``_append`` - This event adds an item to the end of a block of related items, or adds to the end of individual items in a block. + - ``_before`` - This event adds content directly before the specified block + - ``_after`` - This event adds content directly after the specified block + +Template event documentation +++++++++++++++++++++++++++++ + +Events must be documented in ``phpBB/docs/events.md`` in alphabetical order based on the event name. The format is as follows: + +- An event found in only one template file: + +.. code:: php + + event_name + === + * Location: styles//template/filename.html + * Purpose: A brief description of what this event should be used for. + This may span multiple lines. + * Since: Version since when the event was added + +- An event found in multiple template files: + +.. code:: php + + event_name + === + * Locations: + + first/file/path.html + + second/file/path.html + * Purpose: Same as above. + * Since: 3.2.0-b1 + +- An event that is found multiple times in a file should have the number of instances in parenthesis next to the filename. + +.. code:: php + + event_name + === + * Locations: + + first/file/path.html (2) + + second/file/path.html + * Purpose: Same as above. + * Since: 3.2.0-b1 + +- An actual example event documentation: + +.. code:: php + + forumlist_body_last_post_title_prepend + ==== + * Locations: + + styles/prosilver/template/forumlist_body.html + + styles/subsilver2/template/forumlist_body.html + * Purpose: Add content before the post title of the latest post in a forum on the forum list. + * Since: 3.2.0-a1 diff --git a/development/development/phpstorm.rst b/development/development/phpstorm.rst index 968362dd..add425f3 100644 --- a/development/development/phpstorm.rst +++ b/development/development/phpstorm.rst @@ -53,7 +53,7 @@ The general rule here is that braces always go on new lines. CSS, JavaScript, HTML, Twig ########################### -Tabs should be used (not spaces). All tab and indent sizes should be set to 4 spaces. +Tabs should be used (not spaces). All tab and indent sizes should be set to 4 spaces. Also be sure "Keep indents on empty lines" is NOT checked. JSON & YAML @@ -72,6 +72,8 @@ The default inspection settings should work just fine. However there are a coupl * phpBB uses fully qualified namespaces, so you can turn off this inspection warning **PHP > Code Style > Unnecessary fully qualified name**. * You may enable additional JavaScript inspections. Under **JavaScript > Code quality tools**, you can enable JSCS, JSHint, JSlint and/or ESLint. phpBB comes with configuration files for JSHint and JSCS. With these inspections enabled, you can use the configuration files provided by phpBB instead of PhpStorm's default settings. To do so, point PhpStorm to the custom configuration files under **Language & Frameworks > JavaScript > Code Quality Tools**. Point JSHint to `.jshintrc` and point JSCS to `.jscsrc`. +.. warning:: Stylelint is not bundled with PhpStorm. The Stylelint tool is run through NodeJS. To use Stylelint, make sure the NodeJS framework is downloaded and installed on your computer. Then you can follow these `Instructions `_. + .. warning:: JSCS is not bundled with PhpStorm. The JSCS tool is run through NodeJS. To use JSCS, make sure the NodeJS framework is downloaded and installed on your computer. Then you can install JSCS via the npm package manager and configure the JSCS options in PhpStorm to use the JSCS package. For more information review `PhpStorm's documentation `_. .. note:: phpBB uses jQuery. The Javascript inspections need to be made aware of jQuery to avoid any false warnings/errors. To do this, simply go to **Languages & Frameworks > JavaScript > Libraries** and enable jQuery. If jQuery is not in the list, you can use the "Download" button to download a copy of jQuery to PhpStorm. diff --git a/development/development/upgrade.rst b/development/development/upgrade.rst new file mode 100644 index 00000000..5127080d --- /dev/null +++ b/development/development/upgrade.rst @@ -0,0 +1,16 @@ +============= +Upgrade Guide +============= + +This guide summarizes code-level changes introduced in various phpBB versions that may require updates to your custom PHP code, extensions, or styles during an upgrade. + +It is intended primarily for core developers, extension authors, and style creators. **It does not cover instructions for end users performing a board upgrade.** + +Unless otherwise noted, each upgrade entry documents changes relative to the immediately preceding major or minor release. + +Contents: + +.. toctree:: + :maxdepth: 3 + + upgrade/400 diff --git a/development/development/upgrade/400.rst b/development/development/upgrade/400.rst new file mode 100644 index 00000000..c3936efb --- /dev/null +++ b/development/development/upgrade/400.rst @@ -0,0 +1,493 @@ +================ +phpBB 3.3 to 4.0 +================ + +phpBB 4.0 is a major release that includes backward-incompatible changes and new deprecations. +This guide highlights the most important changes and resources to help extension and style developers adapt their code. + +.. contents:: Table of Contents + :depth: 2 + :local: + :backlinks: none + +Basics +====== + +PHP +--- +phpBB 4.0 requires PHP 8.2 or higher. Most PHP code compatible with phpBB 3.3 should work in phpBB 4.0 with minimal changes, +but you may need to make adjustments depending on deprecated or changed functionality. + +Symfony +------- +phpBB 4.0 uses Symfony 7.4, a significant upgrade from the version bundled with phpBB 3.3. As Symfony introduced breaking +changes across versions, we recommend reviewing the following Symfony upgrade guides when updating custom code or extensions: + +- `Upgrade Symfony from 3.x to 4.0 `_ +- `Upgrade Symfony from 4.4 to 5.0 `_ +- `Upgrade Symfony from 5.x to 6.0 `_ +- `Upgrade Symfony from 6.x to 7.0 `_ + +Additional guides are available in the `Symfony GitHub repository `_. + +Twig +---- +phpBB 4.0 uses Twig 3.14, which introduces deprecations that may impact extension and style development. +We recommend reviewing the official Twig deprecation guide when updating your custom templates or Twig-related code: + +- `Twig 3.x Deprecated Features `_ + +Major changes +============= + +Ban system +---------- +The ban system has been significantly refactored in phpBB 4.0. Key changes include: + +- `CIDR block `_ support for banning IP ranges. +- IPv6 banning is now supported. +- “Exclude” functionality has been removed due to ambiguity and inconsistent behavior. + +Removal of Jabber/XMPP +---------------------- +All Jabber/XMPP features have been removed in phpBB 4.0: + +- Jabber/XMPP settings in the ACP are gone. +- XMPP-based notifications have been discontinued. +- Users who previously used Jabber/XMPP will now receive notifications via email. + +This removal was driven by lack of browser support for XMPP and limited adoption within the phpBB community. + +Front Controller Changes +======================== + +In phpBB 4.0, the front controller used for Symfony routing has been changed +from ``app.php`` to ``index.php``. + +In phpBB 3.3.x, routes were accessed via ``app.php``:: + + /app.php/faq + +In phpBB 4.0, routes are now accessed via ``index.php``:: + + /index.php/faq + +Direct access via ``app.php`` is no longer supported. Extensions and external +integrations must use ``index.php``. + +Extensions using phpBB routing helpers (for example, +``controller_helper::route()``) do not require changes, as URLs will be +generated correctly. + +However, any hardcoded references to ``app.php`` must be updated. This includes: + +- Template files +- PHP code constructing URLs manually +- JavaScript referencing application routes + +Class and function changes +========================== +Several classes and functions have been changed or removed. If your extension or code uses phpBB internals, you’ll want to: + +- Review the updated `phpBB 4.0 API documentation `_ +- Audit your code for usages of deprecated or removed methods/classes + +The following table lists class and function changes that might affect custom PHP or Extension code. + +.. list-table:: + :widths: 15 15 10 10 50 + :header-rows: 1 + + * - Class or function + - Path + - Type of change + - Version + - Explanation + + * - ``\phpbb\avatar\driver\remote`` + - ``phpbb/avatar/driver/remote.php`` + - Removed + - ``4.0.0-a1`` + - Use alternative avatar like gravatar or upload avatar. + + * - ``\phpbb\ban\*`` + - ``phpbb/ban/*`` + - Added + - ``4.0.0-a1`` + - Added new refactored banning system. See the API docs for `\\phpbb\\ban `_ namespace. + + * - ``\phpbb\captcha\plugins\incomplete`` + - ``phpbb/captcha/plugins/incomplete.php`` + - Added + - ``4.0.0-a1`` + - Placeholder CAPTCHA that prevents e.g. registration until safer captcha like reCAPTCHA or QA is enabled. + + * - ``\phpbb\captcha\plugins\gd`` + - ``phpbb/captcha/plugins/gd.php`` + - Removed + - ``4.0.0-a1`` + - Use safer captcha like reCAPTCHA or QA. + + * - ``\phpbb\captcha\plugins\gd_wave`` + - ``phpbb/captcha/plugins/gd_wave.php`` + - Removed + - ``4.0.0-a1`` + - Use safer captcha like reCAPTCHA or QA. + + * - ``\phpbb\captcha\plugins\nogd`` + - ``phpbb/captcha/plugins/nogd.php`` + - Removed + - ``4.0.0-a1`` + - Use safer captcha like reCAPTCHA or QA. + + * - ``\phpbb\captcha\char_cube3d`` + - ``phpbb/captcha/char_cube3d.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + + * - ``\phpbb\captcha\colour_manager`` + - ``phpbb/captcha/colour_manager.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + + * - ``\phpbb\captcha\gd`` + - ``phpbb/captcha/gd.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + + * - ``\phpbb\captcha\gd_wave`` + - ``phpbb/captcha/gd_wave.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + + * - ``\phpbb\captcha\non_gd`` + - ``phpbb/captcha/non_gd.php`` + - Removed + - ``4.0.0-a1`` + - No longer used due to removal of gd & nogd CAPTCHAs. + + * - ``\phpbb\filesystem`` + - ``phpbb/filesystem.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\filesystem\filesystem`` instead. + + * - ``\phpbb\form\form_helper`` + - ``phpbb/form/form_helper.php`` + - Added + - ``4.0.0-a1`` + - Introduced form_helper for generating and checking form tokens. + + * - ``\phpbb\php\ini`` + - ``phpbb/php/ini.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\bantu\IniGetWrapper\IniGetWrapper`` instead. + + * - ``\phpbb\event\dispatcher::dispatch()`` + - ``phpbb/event/dispatcher.php`` + - Refactored + - ``4.0.0-a1`` + - Use ``\phpbb\event\dispatcher::trigger_event()`` instead. + + * - ``bbcode_second_pass_by_extension`` + - ``includes/bbcode.php`` + - Removed in ``4.0.0-a1``, deprecated in ``3.2.10`` + - ``4.0.0-a1`` + - Use s9e text_formatter instead. + + * - ``get_user_avatar`` + - ``includes/functions_compatibility.php`` + - Removed in ``4.0.0-a1``, deprecated in ``3.1.0-a1`` + - ``4.0.0-a1`` + - Use ``\phpbb\avatar\helper::get_user_avatar()`` instead. + + * - ``phpbb_get_user_avatar`` + - ``includes/functions.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\avatar\helper::get_user_avatar()`` instead. + + * - ``phpbb_get_group_avatar`` + - ``includes/functions.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\avatar\helper::get_user_avatar()`` instead. + + * - ``phpbb_get_avatar`` + - ``includes/functions.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\avatar\helper::get_user_avatar()`` instead. + + * - ``phpbb_check_hash`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\passwords\manager::check()`` instead. + + * - ``phpbb_clean_path`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\filesystem\helper::clean_path()`` instead. + + * - ``phpbb_hash`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\passwords\manager::hash()`` instead. + + * - ``tz_select`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``phpbb_timezone_select()`` from ``functions.php`` instead. + + * - ``cache_moderators`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``phpbb_cache_moderators()`` from ``functions_admin.php`` instead. + + * - ``update_foes`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``phpbb_update_foes()`` from ``functions_admin.php`` instead. + + * - ``get_user_rank`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``phpbb_get_user_rank()`` from ``functions_display.php`` instead. + + * - ``get_remote_file`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\file_downloader`` instead. + + * - ``add_log`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\log\log`` instead. + + * - ``set_config`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\config\config::increment()`` instead. + + * - ``set_config_count`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\config\config::set()`` instead. + + * - ``request_var`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\request\request::variable()`` instead. + + * - ``set_var`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\request\type_cast_helper::set_var()`` instead. + + * - ``phpbb_email_hash`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - No longer used. + + * - ``phpbb_http_login`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - No longer used. + + * - ``phpbb_load_extensions_autoloaders`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - No longer used. + + * - ``phpbb_build_hidden_fields_for_query_params`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - No longer used. + + * - ``phpbb_delete_user_pms`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``phpbb_delete_users_pms()`` instead. Expects an array of users ids instead of single user id. + + * - ``phpbb_to_numeric`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - No longer used. + + * - ``get_tables`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\db\tools\tools_interface`` classes instead. + + * - ``phpbb_chmod`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\filesystem\filesystem::phpbb_chmod()`` instead. + + * - ``phpbb_is_writable`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\filesystem\filesystem::is_writable()`` instead. + + * - ``phpbb_is_absolute`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\filesystem\helper::is_absolute_path()`` instead. + + * - ``phpbb_realpath`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\filesystem\helper::realpath()`` instead. + + * - ``phpbb_get_plural_form`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\language\language::get_plural_form()`` instead. + + * - ``phpbb_pcre_utf8_support`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Not used anymore. + + * - ``delete_attachments`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\attachment\manager::delete()`` instead. + + * - ``phpbb_unlink`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\attachment\manager::unlink()`` instead. + + * - ``upload_attachment`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\attachment\manager::upload()`` instead. + + * - ``display_reasons`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\report\report_reason_list_provider::display_reasons()`` instead. + + * - ``phpbb_check_and_display_sql_report`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use ``\phpbb\controller\helper::display_sql_report()`` instead. + + * - ``phpbb_checkdnsrr`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use PHP's ``checkdnsrr()`` instead. + + * - ``phpbb_inet_ntop`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use PHP's ``inet_ntop()`` instead. + + * - ``phpbb_inet_pton`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Use PHP's ``inet_pton()`` instead. + + * - ``wrap_img_in_html`` + - ``includes/functions_compatibility.php`` + - Removed + - ``4.0.0-a1`` + - Not used anymore. + + * - ``build_cfg_template`` + - ``includes/functions_acp.php`` + - Removed + - ``4.0.0-a1`` + - Use ``phpbb_build_cfg_template()`` instead. + + * - ``h_radio`` + - ``includes/functions_acp.php`` + - Removed + - ``4.0.0-a1`` + - Use ``phpbb_build_radio()`` instead. + + * - ``build_select`` + - ``includes/functions_acp.php`` + - Refactored + - ``4.0.0-a1`` + - Now ``build_select()`` returns an array of select options instead of a string of HTML. + + * - ``messenger`` + - ``includes/functions_messenger.php`` + - Refactored to new messenger system, removed jabber support + - ``4.0.0-a1`` + - Added new refactored messenger system. See the API docs for `\\phpbb\\messenger `_ namespace. + +**Explanation of columns:** + +* **Class or function:** The name of the class or function that was added, changed, deprecated, or removed in this version. +* **Path:** Path to file. +* **Type of change:** The type of change, e.g. added, changed, deprecated, or removed in this version. +* **Version:** Version in which this change was introduced. +* **Explanation:** The suggested approach to handle the change. This could involve using an alternative function, migrating code to a new approach, or providing additional information. + +Template function changes +========================= +The following table lists function changes that might affect custom Style or Extension code. + +.. list-table:: + :widths: 15 10 10 65 + :header-rows: 1 + + * - Function + - Type of change + - Version + - Explanation + * - ``Icon()`` + - Added + - ``4.0.0-a1`` + - Icons may be rendered using ``{{ Icon('font', 'bold') }}`` in Twig instead of manually writing HTML like ````. + + Arguments: + + - Icon type ('font' | 'png' | 'svg') + - Icon name (e.g.: 'bold') + - Icon title; optional, default: empty ``''`` + - Hide the icon title from view; optional, default: ``false`` + - Additional classes (e.g.: 'fa-fw'); optional, default: ``'fas'`` + - Additional attributes for the icon, where the key is the attribute, ``{'data-ajax': 'mark_forums'}`` results in ``data-ajax="mark_forums"``; optional, default: ``{}`` diff --git a/development/extensions/events_list.rst b/development/extensions/events_list.rst index f88661e6..e88f102e 100644 --- a/development/extensions/events_list.rst +++ b/development/extensions/events_list.rst @@ -15,9 +15,9 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.acp_attachments_config_edit_add | includes/acp/acp_attachments.php | display_vars, mode, submit | 3.1.11-RC1 | Event to add and/or modify acp_attachement configurations | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.acp_ban_after | includes/acp/acp_ban.php | ban, ban_exclude, ban_give_reason, ban_length, ban_length_other, ban_reason, mode | 3.1.0-RC5 | Use this event to perform actions after the ban has been performed | + | core.acp_ban_after | includes/acp/acp_ban.php | ban, ban_give_reason, ban_length, ban_length_other, ban_reason, mode | 3.1.0-RC5 | Use this event to perform actions after the ban has been performed | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.acp_ban_before | includes/acp/acp_ban.php | abort_ban, ban, ban_exclude, ban_give_reason, ban_length, ban_length_other, ban_reason, mode | 3.1.0-RC5 | Use this event to modify the ban details before the ban is performed | + | core.acp_ban_before | includes/acp/acp_ban.php | abort_ban, ban, ban_give_reason, ban_length, ban_length_other, ban_reason, mode | 3.1.0-RC5 | Use this event to modify the ban details before the ban is performed | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.acp_bbcodes_delete_after | includes/acp/acp_bbcodes.php | action, bbcode_id, bbcode_tag | 3.2.4-RC1 | Event after a BBCode has been deleted | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -99,6 +99,8 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.acp_ranks_save_modify_sql_ary | includes/acp/acp_ranks.php | rank_id, sql_ary | 3.1.0-RC3 | Modify the SQL array when saving a rank | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | core.acp_storage_load | includes/acp/acp_storage.php | | 3.3.0-a1 | Add language strings | + +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.acp_styles_action_before | includes/acp/acp_styles.php | action, id, mode | 3.1.7-RC1 | Run code before ACP styles action execution | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.acp_users_avatar_sql | includes/acp/acp_users.php | result, user_row | 3.2.4-RC1 | Modify users preferences data before assigning it to the template | @@ -155,9 +157,11 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.auth_oauth_login_after | phpbb/auth/provider/oauth/oauth.php | row | 3.1.11-RC1 | Event is triggered after user is successfully logged in via OAuth. | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.avatar_driver_upload_delete_before | phpbb/avatar/driver/upload.php | destination, error, prefix, row | 3.1.6-RC1 | Before deleting an existing avatar | + | core.avatar_driver_upload_delete_before | phpbb/avatar/driver/upload.php | error, prefix, row | 3.1.6-RC1 | Before deleting an existing avatar | + +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | core.avatar_driver_upload_move_file_before | phpbb/avatar/driver/upload.php | error, file, filedata, prefix, row | 3.1.6-RC1 | Before moving new file in place (and eventually overwriting the existing avatar with the newly uploaded avatar) | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.avatar_driver_upload_move_file_before | phpbb/avatar/driver/upload.php | destination, error, file, filedata, prefix, row | 3.1.6-RC1 | Before moving new file in place (and eventually overwriting the existing avatar with the newly uploaded avatar) | + | core.avatar_helper_get_avatar | phpbb/avatar/helper.php | data, ignore_config, lazy, row, title | 4.0.0 | Event to modify avatar data array | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.avatar_manager_avatar_delete_after | phpbb/avatar/manager.php | avatar_data, prefix, table, user | 3.2.4-RC1 | Event is triggered after user avatar has been deleted | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -263,7 +267,12 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.display_user_activity_modify_actives | includes/functions_display.php | active_f_row, active_t_row, show_user_activity, userdata | 3.1.0-RC3 | Alter list of forums and topics to display as active | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.download_file_send_to_browser_before | download/file.php | attach_id, attachment, display_cat, download_mode, extensions, mode, thumbnail | 3.1.6-RC1 | Event to modify data before sending file to browser | + | core.download_file_send_to_browser_before | phpbb/storage/controller/attachment.php | attach_id, attachment, extensions, redirect, thumbnail | 3.1.6-RC1 | Event to modify data before sending file to browser | + +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | core.exit_handler | includes/functions.php | exit_handler_override | 4.0.0-a1 | This event can either supplement or override the exit_handler() function | + | | | | | | + | | | | | To override this function, the event must set $exit_handler_override to | + | | | | | true to force it to exit directly after calling this event. | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.faq_mode_validation | phpbb/help/controller/help.php | ext_name, lang_file, mode, page_title, template_file | 3.1.4-RC1 | You can use this event display a custom help page | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -375,9 +384,9 @@ PHP Events | | | | | It is also possible to prevent the marking. For that, the $should_markread parameter | | | | | | should be set to FALSE. | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.mcp_ban_after | includes/mcp/mcp_ban.php | ban, ban_exclude, ban_give_reason, ban_length, ban_length_other, ban_reason, mode | 3.1.0-RC5 | Use this event to perform actions after the ban has been performed | + | core.mcp_ban_after | includes/mcp/mcp_ban.php | ban, ban_give_reason, ban_length, ban_length_other, ban_reason, mode | 3.1.0-RC5 | Use this event to perform actions after the ban has been performed | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.mcp_ban_before | includes/mcp/mcp_ban.php | abort_ban, ban, ban_exclude, ban_give_reason, ban_length, ban_length_other, ban_reason, mode | 3.1.0-RC5 | Use this event to modify the ban details before the ban is performed | + | core.mcp_ban_before | includes/mcp/mcp_ban.php | abort_ban, ban, ban_give_reason, ban_length, ban_length_other, ban_reason, mode | 3.1.0-RC5 | Use this event to modify the ban details before the ban is performed | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.mcp_ban_confirm | includes/mcp/mcp_ban.php | hidden_fields | 3.1.0-RC5 | Use this event to pass data from the ban form to the confirmation screen | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -522,7 +531,7 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.message_list_actions | includes/ucp/ucp_pm_compose.php | add_bcc, add_to, address_list, error, remove_g, remove_u | 3.2.4-RC1 | Event for additional message list actions | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.message_parser_check_message | includes/message_parser.php | allow_bbcode, allow_flash_bbcode, allow_img_bbcode, allow_magic_url, allow_quote_bbcode, allow_smilies, allow_url_bbcode, bbcode_bitfield, bbcode_uid, message, mode, return, update_this_message, warn_msg | 3.1.2-RC1 | This event can be used for additional message checks/cleanup before parsing | + | core.message_parser_check_message | includes/message_parser.php | allow_bbcode, allow_img_bbcode, allow_magic_url, allow_quote_bbcode, allow_smilies, allow_url_bbcode, bbcode_bitfield, bbcode_uid, message, mode, return, update_this_message, warn_msg | 3.1.2-RC1 | This event can be used for additional message checks/cleanup before parsing | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.modify_attachment_data_on_submit | includes/message_parser.php | attachment_data | 3.2.2-RC1 | Modify attachment data on submit | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -558,7 +567,7 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.modify_notification_template | includes/functions_messenger.php | break, method, subject, template | 3.2.4-RC1 | Event to modify the template before parsing | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.modify_pm_attach_download_auth | includes/functions_download.php | allowed, msg_id, user_id | 3.1.11-RC1 | Event to modify PM attachments download auth | + | core.modify_pm_attach_download_auth | phpbb/storage/controller/attachment.php | allowed, msg_id, user_id | 3.1.11-RC1 | Event to modify PM attachments download auth | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.modify_posting_auth | posting.php | draft_id, error, forum_id, is_authed, load, mode, post_data, post_id, preview, refresh, save, submit, topic_id | 3.1.3-RC1 | This event allows you to do extra auth checks and verify if the user | | | | | | has the required permissions | @@ -591,7 +600,7 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.modify_text_for_storage_after | includes/functions_content.php | bitfield, flags, message_parser, text, uid | 3.1.0-a1 | Use this event to modify the text after it is prepared for storage | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.modify_text_for_storage_before | includes/functions_content.php | allow_bbcode, allow_flash_bbcode, allow_img_bbcode, allow_quote_bbcode, allow_smilies, allow_url_bbcode, allow_urls, bitfield, flags, mode, text, uid | 3.1.0-a1 | Use this event to modify the text before it is prepared for storage | + | core.modify_text_for_storage_before | includes/functions_content.php | allow_bbcode, allow_img_bbcode, allow_quote_bbcode, allow_smilies, allow_url_bbcode, allow_urls, bitfield, flags, mode, text, uid | 3.1.0-a1 | Use this event to modify the text before it is prepared for storage | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.modify_uploaded_file | phpbb/attachment/upload.php | filedata, is_image | 3.1.0-RC3 | Event to modify uploaded file before submit to the post | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -674,7 +683,7 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.pm_modify_message_subject | includes/ucp/ucp_pm_compose.php | message_subject | 3.2.8-RC1 | This event allows you to modify the PM subject of the PM being quoted | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.posting_modify_bbcode_status | posting.php | bbcode_status, flash_status, img_status, quote_status, smilies_status, url_status | 3.3.3-RC1 | Event to override message BBCode status indications | + | core.posting_modify_bbcode_status | posting.php | bbcode_status, img_status, quote_status, smilies_status, url_status | 3.3.3-RC1 | Event to override message BBCode status indications | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.posting_modify_cannot_edit_conditions | posting.php | force_edit_allowed, post_data, s_cannot_edit, s_cannot_edit_locked, s_cannot_edit_time | 3.1.0-b4 | This event allows you to modify the conditions for the "cannot edit post" checks | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -731,55 +740,55 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.search_modify_url_parameters | search.php | ex_fid_ary, search_id, show_results, sql_where, total_match_count, u_search | 3.1.7-RC1 | Event to add or modify search URL parameters | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_mysql_author_query_before | phpbb/search/fulltext_mysql.php | author_ary, author_name, ex_fid_ary, firstpost_only, m_approve_fid_sql, result_count, sort_by_sql, sort_days, sort_dir, sort_key, sql_author, sql_firstpost, sql_fora, sql_sort, sql_sort_join, sql_sort_table, sql_time, sql_topic_id, start, topic_id, type | 3.1.5-RC1 | Allow changing the query used to search for posts by author in fulltext_mysql | + | core.search_mysql_author_query_before | phpbb/search/backend/fulltext_mysql.php | author_ary, author_name, ex_fid_ary, firstpost_only, m_approve_fid_sql, result_count, sort_by_sql, sort_days, sort_dir, sort_key, sql_author, sql_firstpost, sql_fora, sql_sort, sql_sort_join, sql_sort_table, sql_time, sql_topic_id, start, topic_id, type | 3.1.5-RC1 | Allow changing the query used to search for posts by author in fulltext_mysql | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_mysql_by_author_modify_search_key | phpbb/search/fulltext_mysql.php | author_ary, author_name, ex_fid_ary, firstpost_only, post_visibility, search_key_array, sort_days, sort_key, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | + | core.search_mysql_by_author_modify_search_key | phpbb/search/backend/fulltext_mysql.php | author_ary, author_name, ex_fid_ary, firstpost_only, post_visibility, search_key_array, sort_days, sort_key, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_mysql_by_keyword_modify_search_key | phpbb/search/fulltext_mysql.php | author_ary, ex_fid_ary, fields, post_visibility, search_key_array, sort_days, sort_key, terms, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | + | core.search_mysql_by_keyword_modify_search_key | phpbb/search/backend/fulltext_mysql.php | author_ary, ex_fid_ary, fields, post_visibility, search_key_array, sort_days, sort_key, terms, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_mysql_create_index_before | phpbb/search/fulltext_mysql.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the MySQL search index is created | + | core.search_mysql_create_index_before | phpbb/search/backend/fulltext_mysql.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the MySQL search index is created | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_mysql_delete_index_before | phpbb/search/fulltext_mysql.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the MySQL search index is deleted | + | core.search_mysql_delete_index_before | phpbb/search/backend/fulltext_mysql.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the MySQL search index is deleted | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_mysql_index_before | phpbb/search/fulltext_mysql.php | forum_id, message, mode, post_id, poster_id, split_text, split_title, subject, words | 3.2.3-RC1 | Event to modify method arguments and words before the MySQL search index is updated | + | core.search_mysql_index_before | phpbb/search/backend/fulltext_mysql.php | forum_id, message, mode, post_id, poster_id, split_text, split_title, subject, words | 3.2.3-RC1 | Event to modify method arguments and words before the MySQL search index is updated | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_mysql_keywords_main_query_before | phpbb/search/fulltext_mysql.php | author_ary, author_name, ex_fid_ary, join_topic, result_count, search_query, sort_by_sql, sort_days, sort_dir, sort_key, sql_match, sql_match_where, sql_sort, sql_sort_join, sql_sort_table, start, topic_id | 3.1.5-RC1 | Allow changing the query used to search for posts using fulltext_mysql | + | core.search_mysql_keywords_main_query_before | phpbb/search/backend/fulltext_mysql.php | author_ary, author_name, ex_fid_ary, join_topic, result_count, search_query, sort_by_sql, sort_days, sort_dir, sort_key, sql_match, sql_match_where, sql_sort, sql_sort_join, sql_sort_table, start, topic_id | 3.1.5-RC1 | Allow changing the query used to search for posts using fulltext_mysql | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_native_author_count_query_before | phpbb/search/fulltext_native.php | ex_fid_ary, firstpost_only, select, sort_by_sql, sort_days, sort_dir, sort_key, sql_author, sql_firstpost, sql_fora, sql_sort, sql_sort_join, sql_sort_table, sql_time, start, topic_id, total_results, type | 3.1.5-RC1 | Allow changing the query used to search for posts by author in fulltext_native | + | core.search_native_author_count_query_before | phpbb/search/backend/fulltext_native.php | ex_fid_ary, firstpost_only, select, sort_by_sql, sort_days, sort_dir, sort_key, sql_author, sql_firstpost, sql_fora, sql_sort, sql_sort_join, sql_sort_table, sql_time, start, topic_id, total_results, type | 3.1.5-RC1 | Allow changing the query used to search for posts by author in fulltext_native | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_native_by_author_modify_search_key | phpbb/search/fulltext_native.php | author_ary, author_name, ex_fid_ary, firstpost_only, post_visibility, search_key_array, sort_days, sort_key, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | + | core.search_native_by_author_modify_search_key | phpbb/search/backend/fulltext_native.php | author_ary, author_name, ex_fid_ary, firstpost_only, post_visibility, search_key_array, sort_days, sort_key, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_native_by_keyword_modify_search_key | phpbb/search/fulltext_native.php | author_ary, ex_fid_ary, fields, must_contain_ids, must_exclude_one_ids, must_not_contain_ids, post_visibility, search_key_array, sort_days, sort_key, terms, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | + | core.search_native_by_keyword_modify_search_key | phpbb/search/backend/fulltext_native.php | author_ary, ex_fid_ary, fields, must_contain_ids, must_exclude_one_ids, must_not_contain_ids, post_visibility, search_key_array, sort_days, sort_key, terms, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_native_delete_index_before | phpbb/search/fulltext_native.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the native search index is deleted | + | core.search_native_delete_index_before | phpbb/search/backend/fulltext_native.php | stats, truncate_tables | 3.2.3-RC1 | Event to modify SQL queries before the native search index is deleted | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_native_index_before | phpbb/search/fulltext_native.php | cur_words, forum_id, message, mode, post_id, poster_id, split_text, split_title, subject, words | 3.2.3-RC1 | Event to modify method arguments and words before the native search index is updated | + | core.search_native_index_before | phpbb/search/backend/fulltext_native.php | cur_words, forum_id, message, mode, post_id, poster_id, split_text, split_title, subject, words | 3.2.3-RC1 | Event to modify method arguments and words before the native search index is updated | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_native_keywords_count_query_before | phpbb/search/fulltext_native.php | author_ary, author_name, ex_fid_ary, group_by, left_join_topics, must_contain_ids, must_exclude_one_ids, must_not_contain_ids, search_query, sort_by_sql, sort_days, sort_dir, sort_key, sql_array, sql_match, sql_match_where, sql_sort, sql_sort_join, sql_sort_table, sql_where, start, topic_id, total_results | 3.1.5-RC1 | Allow changing the query used for counting for posts using fulltext_native | + | core.search_native_keywords_count_query_before | phpbb/search/backend/fulltext_native.php | author_ary, author_name, ex_fid_ary, group_by, left_join_topics, must_contain_ids, must_exclude_one_ids, must_not_contain_ids, search_query, sort_by_sql, sort_days, sort_dir, sort_key, sql_array, sql_match, sql_match_where, sql_sort, sql_sort_join, sql_sort_table, sql_where, start, topic_id, total_results | 3.1.5-RC1 | Allow changing the query used for counting for posts using fulltext_native | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_postgres_author_count_query_before | phpbb/search/fulltext_postgres.php | author_ary, author_name, ex_fid_ary, firstpost_only, m_approve_fid_sql, result_count, sort_by_sql, sort_days, sort_dir, sort_key, sql_author, sql_fora, sql_sort, sql_sort_join, sql_sort_table, sql_time, sql_topic_id, start, topic_id | 3.1.5-RC1 | Allow changing the query used to search for posts by author in fulltext_postgres | + | core.search_postgres_author_count_query_before | phpbb/search/backend/fulltext_postgres.php | author_ary, author_name, ex_fid_ary, firstpost_only, m_approve_fid_sql, result_count, sort_by_sql, sort_days, sort_dir, sort_key, sql_author, sql_fora, sql_sort, sql_sort_join, sql_sort_table, sql_time, sql_topic_id, start, topic_id | 3.1.5-RC1 | Allow changing the query used to search for posts by author in fulltext_postgres | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_postgres_by_author_modify_search_key | phpbb/search/fulltext_postgres.php | author_ary, author_name, ex_fid_ary, firstpost_only, post_visibility, search_key_array, sort_days, sort_key, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | + | core.search_postgres_by_author_modify_search_key | phpbb/search/backend/fulltext_postgres.php | author_ary, author_name, ex_fid_ary, firstpost_only, post_visibility, search_key_array, sort_days, sort_key, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_postgres_by_keyword_modify_search_key | phpbb/search/fulltext_postgres.php | author_ary, ex_fid_ary, fields, post_visibility, search_key_array, sort_days, sort_key, terms, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | + | core.search_postgres_by_keyword_modify_search_key | phpbb/search/backend/fulltext_postgres.php | author_ary, ex_fid_ary, fields, post_visibility, search_key_array, sort_days, sort_key, terms, topic_id, type | 3.1.7-RC1 | Allow changing the search_key for cached results | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_postgres_create_index_before | phpbb/search/fulltext_postgres.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the Postgres search index is created | + | core.search_postgres_create_index_before | phpbb/search/backend/fulltext_postgres.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the Postgres search index is created | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_postgres_delete_index_before | phpbb/search/fulltext_postgres.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the Postgres search index is created | + | core.search_postgres_delete_index_before | phpbb/search/backend/fulltext_postgres.php | sql_queries, stats | 3.2.3-RC1 | Event to modify SQL queries before the Postgres search index is created | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_postgres_index_before | phpbb/search/fulltext_postgres.php | forum_id, message, mode, post_id, poster_id, split_text, split_title, subject, words | 3.2.3-RC1 | Event to modify method arguments and words before the PostgreSQL search index is updated | + | core.search_postgres_index_before | phpbb/search/backend/fulltext_postgres.php | forum_id, message, mode, post_id, poster_id, split_text, split_title, subject, words | 3.2.3-RC1 | Event to modify method arguments and words before the PostgreSQL search index is updated | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_postgres_keywords_main_query_before | phpbb/search/fulltext_postgres.php | author_ary, author_name, ex_fid_ary, join_topic, result_count, sort_by_sql, sort_days, sort_dir, sort_key, sql_match, sql_match_where, sql_sort, sql_sort_join, sql_sort_table, start, topic_id, tsearch_query | 3.1.5-RC1 | Allow changing the query used to search for posts using fulltext_postgres | + | core.search_postgres_keywords_main_query_before | phpbb/search/backend/fulltext_postgres.php | author_ary, author_name, ex_fid_ary, join_topic, result_count, sort_by_sql, sort_days, sort_dir, sort_key, sql_match, sql_match_where, sql_sort, sql_sort_join, sql_sort_table, start, topic_id, tsearch_query | 3.1.5-RC1 | Allow changing the query used to search for posts using fulltext_postgres | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.search_results_modify_search_title | search.php | author_id, keywords, l_search_title, search_id, show_results, start, total_match_count | 3.1.0-RC4 | Modify the title and/or load data for the search results page | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_sphinx_index_before | phpbb/search/fulltext_sphinx.php | forum_id, message, mode, post_id, poster_id, subject | 3.2.3-RC1 | Event to modify method arguments before the Sphinx search index is updated | + | core.search_sphinx_index_before | phpbb/search/backend/fulltext_sphinx.php | forum_id, message, mode, post_id, poster_id, subject | 3.2.3-RC1 | Event to modify method arguments before the Sphinx search index is updated | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_sphinx_keywords_modify_options | phpbb/search/fulltext_sphinx.php | author_ary, author_name, ex_fid_ary, fields, post_visibility, sort_days, sort_key, sphinx, terms, topic_id, type | 3.1.7-RC1 | Allow modifying the Sphinx search options | + | core.search_sphinx_keywords_modify_options | phpbb/search/backend/fulltext_sphinx.php | author_ary, author_name, ex_fid_ary, fields, post_visibility, sort_days, sort_key, sphinx, terms, topic_id, type | 3.1.7-RC1 | Allow modifying the Sphinx search options | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.search_sphinx_modify_config_data | phpbb/search/fulltext_sphinx.php | config_data, delete, non_unique | 3.1.7-RC1 | Allow adding/changing the Sphinx configuration data | + | core.search_sphinx_modify_config_data | phpbb/search/backend/fulltext_sphinx.php | config_data, delete, non_unique | 3.1.7-RC1 | Allow adding/changing the Sphinx configuration data | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.send_file_to_browser_before | includes/functions_download.php | attachment, category, filename, size, upload_dir | 3.1.11-RC1 | Event to alter attachment before it is sent to browser. | + | core.send_file_to_browser_before | phpbb/storage/controller/attachment.php | attachment | 3.1.11-RC1 | Event to alter attachment before it is sent to browser. | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.session_create_after | phpbb/session.php | session_data | 3.1.6-RC1 | Event to send new session data to extension | | | | | | Read-only event | @@ -849,7 +858,7 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.text_formatter_s9e_render_after | phpbb/textformatter/s9e/renderer.php | html, renderer | 3.2.0-a1 | Modify a rendered text | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.text_formatter_s9e_render_before | phpbb/textformatter/s9e/renderer.php | renderer, xml | 3.2.0-a1 | Modify a parsed text before it is rendered | + | core.text_formatter_s9e_render_before | phpbb/textformatter/s9e/renderer.php | renderer, text | 3.2.0-a1 | Modify a parsed text before it is rendered | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.text_formatter_s9e_renderer_setup | phpbb/textformatter/s9e/renderer.php | renderer | 3.2.0-a1 | Configure the renderer service | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -903,7 +912,7 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.ucp_pm_compose_compose_pm_basic_info_query_before | includes/ucp/ucp_pm_compose.php | action, delete, msg_id, preview, reply_to_all, sql, submit, to_group_id, to_user_id | 3.1.0-RC5 | Alter sql query to get message for user to write the PM | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.ucp_pm_compose_modify_bbcode_status | includes/ucp/ucp_pm_compose.php | bbcode_status, flash_status, img_status, smilies_status, url_status | 3.3.3-RC1 | Event to override private message BBCode status indications | + | core.ucp_pm_compose_modify_bbcode_status | includes/ucp/ucp_pm_compose.php | bbcode_status, img_status, smilies_status, url_status | 3.3.3-RC1 | Event to override private message BBCode status indications | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.ucp_pm_compose_modify_data | includes/ucp/ucp_pm_compose.php | action, delete, msg_id, preview, reply_to_all, submit, to_group_id, to_user_id | 3.1.4-RC1 | Modify the default vars before composing a PM | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -953,9 +962,7 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.ucp_profile_autologin_keys_template_vars | includes/ucp/ucp_profile.php | sessions, template_vars | 3.3.2-RC1 | Event allows changing template variables | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.ucp_profile_avatar_sql | includes/ucp/ucp_profile.php | result | 3.1.11-RC1 | Trigger events on successfull avatar change | - +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.ucp_profile_avatar_upload_validation | phpbb/avatar/driver/remote.php | error, height, url, width | 3.2.9-RC1 | Event to make custom validation of avatar upload | + | core.ucp_profile_avatar_sql | includes/ucp/ucp_profile.php | result | 3.1.11-RC1 | Trigger events on successful avatar change | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.ucp_profile_info_modify_sql_ary | includes/ucp/ucp_profile.php | cp_data, data, sql_ary | 3.1.4-RC1 | Modify profile data in UCP before submitting to the database | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -973,10 +980,6 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.ucp_profile_validate_profile_info | includes/ucp/ucp_profile.php | data, error, submit | 3.1.4-RC1 | Validate user data on editing profile in UCP | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.ucp_register_agreement | includes/ucp/ucp_register.php | | 3.1.6-RC1 | Allows to modify the agreements. | - | | | | | | - | | | | | To assign data to the template, use $template->assign_vars() | - +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.ucp_register_agreement_modify_template_data | includes/ucp/ucp_register.php | lang_row, s_hidden_fields, template_vars, tpl_name | 3.2.2-RC1 | Allows to modify the agreements. | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.ucp_register_data_after | includes/ucp/ucp_register.php | cp_data, data, error, submit | 3.1.4-RC1 | Check UCP registration data after they are submitted | @@ -1044,8 +1047,6 @@ PHP Events +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.user_setup_after | phpbb/user.php | | 3.1.6-RC1 | Execute code at the end of user setup | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | core.user_unban | includes/functions_user.php | mode, user_ids_ary | 3.1.11-RC1 | Use this event to perform actions after the unban has been performed | - +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | core.validate_bbcode_by_extension | includes/message_parser.php | params_array, return | 3.1.5-RC1 | Event to validate bbcode with the custom validating methods | | | | | | provided by extensions | +-----------------------------------------------------------------------+-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 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 51cdb80f..c9b35d29 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." @@ -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 6ce81a7e..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, @@ -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 95329725..06a578c3 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 @@ -79,7 +79,7 @@ The following sample code shows how BBCodes can be toggled and manipulated using .. seealso:: - - `phpBB API Documentation `_ + - `phpBB API Documentation `_ - `Runtime configuration - s9e\\TextFormatter `_ @@ -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. @@ -300,7 +300,7 @@ set the value before each parsing. .. seealso:: - - `phpBB API Documentation `_ + - `phpBB API Documentation `_ - `Callback signature - s9e\\TextFormatter `_ - `Attribute filters - s9e\\TextFormatter `_ - `Tag filters - s9e\\TextFormatter `_ diff --git a/development/extensions/tutorial_controllers.rst b/development/extensions/tutorial_controllers.rst index cbce5228..263264d9 100644 --- a/development/extensions/tutorial_controllers.rst +++ b/development/extensions/tutorial_controllers.rst @@ -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 9ea6a471..a584800d 100644 --- a/development/extensions/tutorial_events.rst +++ b/development/extensions/tutorial_events.rst @@ -82,13 +82,55 @@ text ``DEMO_PAGE``. We will fix the link text in the next section. ``config.php`` file, which will force the template engine to always look for template listeners when a page is being rendered. -It's important to understand that when phpBB compiles the templates, -there is no current system for determining the priority in which template -listeners from different extensions subscribed to the same event are -compiled. In rare cases some extensions could cause a conflict, in which case -the recommendation is for the extension authors to work together on a solution for their -conflicting template listeners. +Prioritising template event listeners (optional) +------------------------------------------------ +In rare cases, conflicts may occur when multiple extensions subscribe to the same template +event using template listeners. To resolve such conflicts, phpBB allows you to control the +order in which template event listeners are compiled by assigning them priorities. + +This is done by subscribing a PHP event listener to the +``core.twig_event_tokenparser_constructor`` event and using the +``template_event_priority_array`` variable to define listener priorities. + +Example: + +.. code-block:: php + + 'set_template_event_priority', + ]; + } + + // Give your extension a high priority when rendering the navbar_header_quick_links_after template event. + public function set_template_event_priority($event) + { + $template_event_priority_array = $event['template_event_priority_array']; + $template_event_priority_array['acme_demo'] = [ + 'event/navbar_header_quick_links_after' => 100, + ]; + $event['template_event_priority_array'] = $template_event_priority_array; + } + } + +In this example, ``100`` is an integer implying the template event priority. Higher values +indicate greater importance, meaning the corresponding template event listener +will be compiled earlier than others listening to the same event. +For example, the content of template event listener which has a priority value of ``100`` +will be rendered above/before the same template event listener which has a priority value of ``99``. +If multiple listeners share the same priority value, they will be rendered in the order they were read +from their respective filesystem locations. If no priority value set, it defaults to ``0``. PHP Core Events & Listeners =========================== 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 fdb4928f..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` @@ -651,14 +651,10 @@ you will have to indicate that in the path, e.g.: ``@vendor_extension/subdirecto return '@vendor_extension/sample'; } -There is also a third notification method, Jabber, which uses the :class:`email/short` directory for its template files. -This notification method is closely tied to the email method, so it is important to also supply that template file, -even though the content might be identical to the email template. - -.. warning:: +.. note:: - Make sure to have both :class:`language/en/email/sample.txt` and :class:`language/en/email/short/sample.txt` - in your extension's language directory to prevent errors. + The previously existing Jabber notification method has been removed in phpBB 4.0. A separate :class:`email/short` directory + for this notification method is no longer used and therefore you no longer need to create a separate template file for it. get_email_template_variables ---------------------------- @@ -667,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()`` @@ -968,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_ @@ -1037,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``. @@ -1084,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``. @@ -1100,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``. @@ -1121,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/index.rst b/development/index.rst index be3faa9d..278201ab 100644 --- a/development/index.rst +++ b/development/index.rst @@ -4,11 +4,14 @@ phpBB Development Documentation Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 3 + start/install + start/getting_started + development/upgrade development/processes development/git - development/coding_guidelines + development/index cli/index auth/authentication db/dbal diff --git a/development/language/guidelines.rst b/development/language/guidelines.rst index e2877977..03bfe6b7 100644 --- a/development/language/guidelines.rst +++ b/development/language/guidelines.rst @@ -14,7 +14,7 @@ If your language pack is denied and then resubmitted, it is placed at the end of 2) Submissions have to be complete. Partial translations are not allowed and will be automatically denied. E-mails, text files and theme-images must also be fully translated. -3) Language packs can contain five additional files (one mandatory and four optionals) that are not present in the British English language pack: ``LICENSE`` (mandatory), ``README.md`` (optional), ``AUTHORS.md`` (optional), ``VERSION.md`` (optional) and ``CHANGELOG.md`` (optional). You are free to write whatever you want in the ``README.md`` file, you can list all the authors and contributors of your language pack in the ``AUTHORS.md`` file, you can put the version of your language pack in the ``VERSION.md`` file and you can list the entire version history in the ``CHANGELOG.md`` file. The ``LICENSE`` file is automatically added during the upload process so you do not have to manually add the file. Its purpose is to inform the user what license is used. Language packs inherit phpBB's license of `GNU General Public License 2.0`_ and no additional or alternative licenses are allowed. All of these additional files must be placed in the ``language/{iso}/`` directory, next to the ``iso.txt`` file. Any other additional file(s) will be detected and your submission will be denied. +3) Language packs can contain three additional files (one mandatory and four optionals) that are not present in the British English language pack: ``LICENSE`` (mandatory), ``README.md`` (optional) and ``CHANGELOG.md`` (optional). You are free to write whatever you want in the ``README.md`` file and you can list the entire version history in the ``CHANGELOG.md`` file. The ``LICENSE`` file is automatically added during the upload process so you do not have to manually add the file. Its purpose is to inform the user what license is used. Language packs inherit phpBB's license of `GNU General Public License 2.0`_ and no additional or alternative licenses are allowed. All of these additional files must be placed in the ``language/{iso}/`` directory, next to the ``composer.json`` file. Any other additional file(s) will be detected and your submission will be denied. 4) Submissions must have the following files and structure: @@ -51,24 +51,10 @@ If your language pack is denied and then resubmitted, it is placed at the end of profile.php prune.php search.php + storage.php styles.php users.php email/ - short/ - bookmark.txt - newtopic_notify.txt - post_approved.txt - post_disapproved.txt - post_in_queue.txt - privmsg_notify.txt - quote.txt - report_pm.txt - report_post.txt - topic_approved.txt - topic_disapproved.txt - topic_in_queue.txt - topic_notify.txt - admin_activate.txt admin_send_email.txt admin_welcome_activated.txt @@ -83,6 +69,7 @@ If your language pack is denied and then resubmitted, it is placed at the end of group_request.txt index.htm installed.txt + mention.txt newtopic_notify.txt pm_report_closed.txt pm_report_deleted.txt @@ -96,14 +83,16 @@ If your language pack is denied and then resubmitted, it is placed at the end of report_closed.txt report_deleted.txt report_pm.txt + report_pm_closed.txt report_post.txt + test.txt topic_approved.txt topic_disapproved.txt topic_in_queue.txt topic_notify.txt user_activate.txt user_activate_inactive.txt - user_activate_passwd.txt + user_forgot_password.txt user_reactivate_account.txt user_remind_inactive.txt user_resend_inactive.txt @@ -113,16 +102,16 @@ If your language pack is denied and then resubmitted, it is placed at the end of bbcode.php faq.php app.php - AUTHORS.md (optional) captcha_qa.php captcha_recaptcha.php + captcha_turnstile.php cli.php CHANGELOG.md (optional) common.php + composer.json groups.php index.htm install.php - iso.txt ( LICENSE mcp.php memberlist.php @@ -132,40 +121,37 @@ If your language pack is denied and then resubmitted, it is placed at the end of README.md (optional) search.php ucp.php - VERSION.md (optional) viewforum.php viewtopic.php styles/ prosilver/ theme/ {iso}/ - icon_user_online.gif - index.htm (optional) + index.htm stylesheet.css -5) Submissions should follow the recommendations in the `3.3 Translation (i18n/L10n) Guidelines`_ as closely as possible, especially the `3.3 Writing style`_. +5) Submissions should follow the recommendations in the `Coding Guidelines`_ as closely as possible. -6) All PHP and text files must be encoded in UTF-8 without BOM and a new line at the end of the file. Many modern text editors use this as a default setting, but we recommend checking it in your editor's settings. We recommend you use `Notepad++`_ or `PSPad`_, both lightweight and free. +6) All PHP and text files must be encoded in UTF-8 without BOM and have an empty new line at the end of the file. Many modern text editors use this as a default setting, but we recommend checking it in your editor's settings. We recommend you use `Notepad++`_ or `PSPad`_, both lightweight and free. -7) The translation is mostly your work and you have a right to hold a copyright on the translation and put your name or the names of those on your team in the ``AUTHORS.md`` file. +7) The translation is mostly your work and you have a right to hold a copyright on the translation and put your name or the names of those on your team in the ``composer.json`` file in the authors section. 8) A maximum of 3 links can be included as an author credit in the footer, customisable via the ``'TRANSLATION_INFO'`` key in ``common.php``. Please note that the Translations Manager has complete discretion on what is acceptable as an author credit link. -9) Submissions have to be submitted as a single zip file. The Customisations Database will automatically name your uploaded language pack using the format ``languagename_versionnumber.zip``. For example, if a Brazilian Portuguese language pack author uploads an archive named ``Brasileiro_1.0.5.zip``, it will be automatically changed to ``brazilian_portuguese_1_0_5.zip``. +9) Submissions have to be submitted as a single zip file. The Customisations Database will automatically name your uploaded language pack using the format ``languagename_versionnumber.zip``. For example, if a Brazilian Portuguese language pack author uploads an archive named ``Brasileiro_4.0.5.zip``, it will be automatically changed to ``brazilian_portuguese_4_0_5.zip``. 10) The contribution description for you language pack in the Customisations Database should be translated into English in addition to your local language. This will facilitate the download of your translation by administrators who do not speak the language. 11) The contribution screenshot in the Customisations Database should only be the flag of the country where the primary spoken language is that of the language pack. For example, the flag of France for the French language. -12) Revision name in the Customisations Database should be left blank, contain the phpBB package version, and/or package release name (e.g. "**3.3.10 / Bertie’s New Translation**" for 3.3.10). +12) Revision name in the Customisations Database should be left blank, contain the phpBB package version, and/or package release name (e.g. "**4.0.0 / Bertie’s Future Translation**" for 4.0.0). 13) The Demo URL in the Customisations Database must be empty, unless you want to put a link to an international community (`officially`_ listed or not) related to the language of the contribution. For example, https://www.phpbb.nl/ as Demo URL concerning the `Dutch language`_ is allowed. -.. _Customisations Database: https://www.phpbb.com/go/customise/language-packs/3.3 +.. _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 -.. _3.3 Translation (i18n/L10n) Guidelines: https://area51.phpbb.com/docs/33x/coding-guidelines.html#translation -.. _3.3 Writing style: https://area51.phpbb.com/docs/33x/coding-guidelines.html#writingstyle +.. _GNU General Public License 2.0: https://opensource.org/license/gpl-2-0 +.. _Coding Guidelines: https://area51.phpbb.com/docs/dev/master/development/index.html .. _Notepad++: https://notepad-plus-plus.org/ .. _PSPad: http://www.pspad.com/en/ .. _officially: https://www.phpbb.com/support/intl/ diff --git a/development/language/plurals.rst b/development/language/plurals.rst index 6b0173fa..54087003 100644 --- a/development/language/plurals.rst +++ b/development/language/plurals.rst @@ -216,8 +216,8 @@ unexpected results if any keys are missing or out of order. Credits ======= The system is based on -`Mozilla `_, which +`Unicode.org`_, which uses the "Plural Rules and Families" from -`GNU gettext documentation `_. +`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 8890d499..42e50bdd 100644 --- a/development/language/validation.rst +++ b/development/language/validation.rst @@ -35,38 +35,36 @@ Package ``_`` folder. The files from above should be placed in 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. + the phpBB package version and/or package release name (e.g. ``4.0.0`` / + ``Bertie's translation`` for 4.0.0) for more understanding. Package Validation ================== * Language packages must include all files that are included in the folders for - the English language. This includes the following folders: + the English language. This includes the following directories: + ``ext/phpbb/viglink/language/en/`` + ``language/en/`` + ``styles/prosilver/theme/en/`` -* Language packages must contain 1 additional files: +* Language packages must contain 1 additional file: + ``language/{iso}/LICENSE`` -* Language packages may contain 4 more additional files: +* Language packages may contain 2 more additional files: - + ``language/{iso}/AUTHORS.md`` + ``language/{iso}/CHANGELOG.md`` + ``language/{iso}/README.md`` - + ``language/{iso}/VERSION.md`` * No other additional files are allowed! -* All folders within the language-directories must contain an ``index.htm`` file (e.g. ``language/en/acp/index.htm``, ``language/en/index.htm``, ``styles/prosilver/theme/de/index.htm``, see the `Language Pack Submission Policy`_ for a complete list.). -* An exception from this rule are the the directories for the viglink-translation and the directories which belong the phpBB package (e.g. ``language/``, ``styles/``). +* The following folders within the language-directories must contain an ``index.htm`` file: ``language/en/acp/index.htm``, ``language/en/index.htm``, ``styles/prosilver/theme/en/index.htm``. +* No ``index.htm`` is need in the directories for the viglink-translation and the directories which belong the phpBB package: ``language/``, ``styles/``) File Validation =============== -* All files must be stored using ``LF`` (LineFeed / UNIX) line endings. +* All files must be saved with ``LF`` (LineFeed / UNIX) line endings. * All ``.php`` files must have a check for the ``IN_PHPBB`` constant: .. code-block:: php @@ -81,22 +79,99 @@ File Validation BOM*. * ``.php`` files must **not** produce any output. There should be no characters before ````, - but just end with a new line + but just end with an empty new line. -language/{iso}/iso.txt ----------------------- +language/{iso}/composer.json +---------------------------- +It is the main configuration file of your translation and language packages. -* The file must contain exactly 3 lines: +The ``composer.json`` from the default language `British English` looks like this: - #. English language name - #. Language name in the spoken language - #. Author(-group) information (Plaintext only, no links allowed) +.. code-block:: json + + { + "name": "phpbb/phpbb-language-en", + "description": "phpBB Forum Software default language", + "type": "phpbb-language", + "version": "4.0.0-RC1", + "homepage": "https://www.phpbb.com", + "license": "GPL-2.0-only", + "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/", + "wiki": "https://wiki.phpbb.com", + "irc": "irc://irc.freenode.org/phpbb" + }, + "extra": { + "language-iso": "en", + "english-name": "British English", + "local-name": "British English", + "phpbb-version": "4.0.0-RC1", + "direction": "ltr", + "user-lang": "en-gb", + "plural-rule": 1, + "recaptcha-lang": "en-GB", + "turnstile-lang": "en" + } + } + +Main block +^^^^^^^^^^ +The main block of a language's ``composer.json`` file requires these six fields of information: + +* ``"name":`` Must start with ``phpbb/phpbb-language-`` and be followed by the language iso code e.g.: ``phpbb/phpbb-language-de`` +* ``"description":`` Must contain a short description for your translation e.g.: ``phpBB Forum Software language package Dutch (Casual Honorifics)``. URLs are not allowed. +* ``"type":`` Must be: ``"phpbb-language",``. Do not change this! +* ``"version":`` Should be the version number of the language package. This can be different than the phpBB-version it is made for. +* ``"homepage":`` You may include a URL to your website, or leave this field empty using empty quotes ``""`` +* ``"license":`` Must be: ``"GPL-2.0-only",``. Do not change this! + +Authors +^^^^^^^ +Use this section to credit the authors and maintainers of this translation. You can add repeating blocks like this for each additional author. + +.. code-block:: json + + { + "name": "Person A", + "email": "mail@example.org", + "homepage": "https://www.example.org" + } + +Support +^^^^^^^ +Use this section to provide links to your websites, email, chat channels, etc. where you provide support for this translation. You should have at least one contact URL, e.g. the support section in the Customisation Database on www.phpBB.com. + +Extra +^^^^^ +The Extra block contains information required for the translation to function correctly within a phpBB installation. +Please do not omit any of these lines, and fill them out carefully. + +* ``"language-iso":`` This must be your ISO code. In British English it is ``en``. This is also the same as the directory name e.g. ``language/en/`` or ``language/de_x_sie/``. +* ``"english-name":`` The English name of your language package e.g.: ``"German (Casual Honorifics)"``. (Formerly, this was the first line of ``language/{iso}/iso.txt``.) +* ``"local-name":`` The local name of your language package e.g.: ``"Deutsch (Du)"``. (Formerly, this was the second line of ``language/{iso}/iso.txt``.) +* ``"phpbb-version":`` This must represent an existing phpBB release version e.g.: ``4.0.0``. Individual naming is not allowed here! +* ``"direction":`` Use ``"ltr""`` for "left-to-right" languages (e.g.: Italian, Dutch, German) and ``"rtl"`` for right-to-left language (e.g.: Arabic). +* ``"user-lang":`` Input the user language code, e.g.: "de". (Formerly defined in the ``language/{iso}/common.php`` e.g.: ``'USER_LANG' => 'de',`` or ``'USER_LANG' => 'de-x-sie',``.) +* ``"plural-rule":`` Input the plural rule number of your language. (Formerly defined in the ``language/{iso}/common.php`` e.g.: ``'PLURAL_RULE' => 1,``.) Check the `plurals`_ section for more details. +* ``"recaptcha-lang":`` Input the ReCaptcha-Language-Code here. (Formerly defined in the ``language/{iso}/captcha_recaptcha.php`` e.g.: ``'RECAPTCHA_LANG' => 'de',``.) Check `Google ReCaptcha`_ for further information which code to use. +* ``"turnstile-lang":`` Input the Turnstile-Language-Code here. Check `Cloudflare Turnstile`_ for further information which code to use. + +.. note:: + + The ``composer.json`` must be valid JSON code. You can validate it using ``composer.phar``, see: `composer.json validation`_. \*/index.htm ------------ -The ``index.htm`` files in all folders must either be completly empty, or -contains the default html body: +The ``index.htm`` files in all folders must be either completely empty or contain the default html body: .. code-block:: html @@ -234,9 +309,13 @@ 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/3.3 -.. _Language Pack Submission Policy: https://area51.phpbb.com/docs/dev/3.3.x/language/guidelines.html#language-pack-submission-policy +.. _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 .. _officially: https://www.phpbb.com/support/intl/ -.. _Dutch language: https://www.phpbb.com/customise/db/translation/dutch_casual_honorifics/ \ No newline at end of file +.. _Dutch language: https://www.phpbb.com/customise/db/translation/dutch_casual_honorifics/ +.. _Google ReCaptcha: https://developers.google.com/recaptcha/docs/language +.. _Cloudflare Turnstile: https://developers.cloudflare.com/turnstile/reference/supported-languages/ +.. _plurals: https://area51.phpbb.com/docs/dev/master/language/plurals.html +.. _composer.json validation: https://getcomposer.org/doc/03-cli.md#validate 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 3362b771..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 @@ -179,6 +174,76 @@ Example return $value + $limit; } +Passing parameters to custom functions +-------------------------------------- + +.. note:: + + This functionality is only available from 3.2.2 onwards + +.. code-block:: php + + array('custom', array( + array(/* Callable function */), array(/* Parameters to the function */), + )), + +.. rubric:: Example + +Call a function within the migrations file named some_function, passing it some parameters + +.. code-block:: php + + array('custom', array( + array($this, 'some_function'), array('first param', 2) + )), + +.. note:: + + The function called must accept the specified parameters + +.. rubric:: Example + +Fully compatible with multi step process + +.. code-block:: php + + public function update_data() + { + return array( + array('custom', array( + array($this, 'some_function'), array(500) // The param is the limit + )), + ); + } + + // $value is the value returned on the previous call, and is always the last parameter + public function some_function($limit, $value) + { + $i = 0; + + // Select all topics, starting at $value, limit $limit + while ($topic = fetchrow) + { + $i++; + + // Do something + } + + if ($i < $limit) + { + // There are no more topics, we are done + return; + } + + // There are still more topics to query, return the next start value + return $value + $limit; + } + +.. note:: + + To support the multi-step process, the function called must accept the explicit parameters, + plus an additional last parameter that will receive the return of the previous step. + Examples ======== 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 new file mode 100644 index 00000000..925982db --- /dev/null +++ b/development/start/getting_started.rst @@ -0,0 +1,198 @@ + +=============== +Getting Started +=============== + +1. Installing +============================ + +Installation, update and conversion instructions can be found in the INSTALL document in this directory. If you are intending on converting from a phpBB 2.0.x or 3.0.x installation we highly recommend that you backup any existing data before proceeding! + +Users of phpBB 3.0, 3.1 and 3.2 Beta versions cannot directly update. + +Please note that we don't support the following installation types: + +- Updates from phpBB Beta versions and lower to phpBB Release Candidates and higher +- Conversions from phpBB 2.0.x to phpBB 3.0 Beta, 3.1 Beta and 3.2 Beta versions +- phpBB 3.0 Beta, 3.1 Beta or 3.2 beta installations + +We give support for the following installation types: + +- Updates from phpBB 3.0 RC1, 3.1 RC1 and 3.2 RC1 to the latest version +- Note: if using the Automatic Update Package, updates are supported from phpBB 3.0.2 onward. To update a pre-3.0.2 installation, first - update to 3.0.2 and then update to the current version. +- Conversions from phpBB 2.0.x to the latest version +- New installations of phpBB 3.1.x - only the latest released version +- New installations of phpBB 3.2.x - only the latest released version + +2. Running +============================ + +Once installed, phpBB is easily managed via the Administration and Moderator Control Panels. If you need help or advice with phpBB, please see Section 3 below. + +.. _i-languages-internationalisation-i18n: + +2.i. Languages (Internationalisation - i18n) +-------------------------------------------- + +A number of language packs with included style localisations are available. You can find them listed in the `Language Packs`_ pages of our downloads section or from the `Language Packs`_ section of the `Customisation Database`_. + +For more information about language packs, please see: https://www.phpbb.com/languages/ + +This is the official location for all supported language sets. If you download a package from a 3rd party site you do so with the understanding that we cannot offer support. Please do not ask for support if you download a language pack from a 3rd party site. + +Installation of these packages is straightforward: simply download the required language pack, uncompress (unzip) it and via FTP transfer the included ``language`` and ``styles`` folders to the root of your board installation. The language can then be installed via the Administration Control Panel of your board: ``Customise tab -> Language management -> Language packs``. A more detailed description of the process is in the Knowledge Base article, `How to Install a Language Pack `_. + +If your language is not available, please visit our `[3.2.x] Translations `_ forum where you will find topics on translations in progress. Should you wish to volunteer to translate a language not currently available or assist in maintaining an existing language pack, you can `Apply to become a translator `_. + +2.ii. Styles +-------------------------------------------- + +Although we are rather proud of the included styles, we realise that they may not be to everyone's taste. Therefore, phpBB allows styles to be switched with relative ease. First, you need to locate and download a style you like. You can find them listed in the `Styles `_ section of our `Customisation Database`_. + +For more information about styles, please see: https://www.phpbb.com/styles/ + +**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. + +**Please note** that to improve efficiency, the software caches certain data. For this reason, if you create your own style or modify existing ones, please remember to purge the board cache by clicking the ``Run now`` button next to the ``Purge the cache`` option in the index page of the Administration Control Panel. You may also need to reload the page you have changed in your web browser to overcome browser caching. If the cache is not purged, you will not see your changes taking effect. + +2.iii. Extensions +-------------------------------------------- + +We are proud to have a thriving extensions community. These third party extensions to the standard phpBB software, extend its capabilities still further. You can browse through many of the extensions in the `Extensions `_ section of our `Customisation Database`_. + +For more information about extensions, please see: https://www.phpbb.com/extensions + +**Please remember** that any bugs or other issues that occur after you have added any extension should **NOT** be reported to the bug tracker (see below). First disable the extension and see if the problem is resolved. Any support for an extension should only be sought in the "Discussion/Support" forum for that extension. + +Also remember that any extensions which modify the database in any way, may render upgrading your forum to future versions more difficult. + +3. Getting Help +============================ + +phpBB can sometimes seem a little daunting to new users, particularly with regards to the permission system. The first thing you should do is check the FAQ, which covers a few basic getting started questions. If you need additional help there are several places you can find it. + +3.i. phpBB Documentation +-------------------------------------------- + +Comprehensive documentation is now available on the phpBB website: + +https://www.phpbb.com/support/docs/en/3.2/ug/ + +This covers everything from installation to setting permissions and managing users. + +3.ii. Knowledge Base +-------------------------------------------- + +The Knowledge Base consists of a number of detailed articles on some common issues phpBB users may encounter while using the product. The Knowledge Base can be found at: + +https://www.phpbb.com/kb/ + +3.iii. Community Forums +-------------------------------------------- + +The phpBB project maintains a thriving community where a number of people have generously decided to donate their time to help support users. This site can be found at: + +https://www.phpbb.com/community/ + +If you do seek help via our forums please be sure to do a search before posting; if someone has experienced the issue before, then you may find that your question has already been answered. Please remember that phpBB is entirely staffed by volunteers, no one receives any compensation for the time they give, including moderators as well as developers; please be respectful and mindful when awaiting responses and receiving support. + +3.iv Internet Relay Chat +-------------------------------------------- + +Another place you may find help is our IRC channel. This operates on the Freenode IRC network, `irc.freenode.net `_ + +The main phpBB IRC channel is ``#phpBB``, and it is for limited general phpBB support. +For coding discussion related to phpBB in general, to Extensions, Styles, or similar, visit ``#phpBB-Coding``. + +An IRC client such as mIRC, XChat, etc. is required to access the Freenode IRC network. Alternatively, the `freenode webchat `_ can be used to access phpBB's IRC channels. There are other IRC channels available, please see https://www.phpbb.com/support/irc/ for the complete list. Again, please do not abuse this service and be respectful of other users. + +Once you have the client up and running, type ``/server irc.freenode.net`` to connect to the freenode IRC network, and then ``/join #phpbb`` to join the phpBB IRC channel. Alternatively, try clicking the following links to start up your client and connect automatically. + +`#phpBB channel `_ +`#phpBB-Coding channel `_ + +3.v Discord +-------------------------------------------- + +phpBB is also running a Discord server for discussing phpBB core development and related topics like Extensions and Styles. Please note that only limited support can be offered. +To join the phpBB Discord server, follow this `invite link `_. + +The channels on Discord are bridged to IRC so users on IRC will see your messages posted by the phpbb-discord user while posts from IRC will be flagged with a Bot flag next to a user's name in Discord. + +4. Status of this version +============================ + +This is a stable release of phpBB. The 3.2.x line is feature frozen, with point releases principally including fixes for bugs and security issues. Feature alterations and minor feature additions may be done if deemed absolutely required. The next major release will be phpBB 3.3 which is currently under development. Please do not post questions asking when 3.3 will be available, no release date has been set. + +Those interested in the development of phpBB should keep an eye on the development forums to see how things are progressing: + +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. + +.. _5. Reporting Bugs: + +5. Reporting Bugs +============================ + +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). + +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: + +First, determine if your bug is reproduceable; how to determine this depends on the bug in question. Only if the bug is reproduceable is it likely to be a problem with phpBB (or in some way connected). If something cannot be reproduced it may turn out to have been your hosting provider working on something, a user doing something silly, etc. Bug reports for non-reproduceable events can slow down our attempts to fix real, reproduceable issues + +Next, please read or search through the existing bug reports to see if your bug (or one very similar to it) is already listed. If it is please add to that existing bug rather than creating a new duplicate entry (all this does is slow us down). + +Check the forums (use search!) to see if people have discussed anything that sounds similar to what you are seeing. However, as noted above please **DO NOT** post your particular bug to the forum unless it's non-reproduceable or you are sure it’s related to something you have done rather than phpBB + +If no existing bug exists then please feel free to add it +If you do post a new bug (i.e. one that isn't already listed in the bug tracker) first make sure that you have logged in (your username and password are the same as for the community forums) then please include the following details: + +Your server type/version, e.g. Apache 2.2.3, IIS 7, Sambar, etc. +PHP version and mode of operation, e.g. PHP 7.1.0 as a module, PHP 7.1.0 running as CGI, etc. +DB type/version, e.g. MySQL 5.0.77, PostgreSQL 9.0.6, MSSQL Server 2000 (via ODBC), etc. +The relevant database type/version is listed within the administration control panel. + +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: 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. + +5.i. Security related bugs +-------------------------------------------- + +If you find a potential security related vulnerability in phpBB please **DO NOT** post it to the bug tracker, public forums, etc.! Doing so may allow unscrupulous users to take advantage of it before we have time to put a fix in place. All security related bugs should be sent to our security tracker: + +https://www.phpbb.com/security/ + +6. Overview of current bug list +=============================== + +This list is not complete but does represent those bugs which may affect users on a wider scale. Other bugs listed in the tracker have typically been shown to be limited to certain setups or methods of installation, updating and/or conversions. + +Conversions may fail to complete on large boards under some hosts. +Updates may fail to complete on large update sets under some hosts. +Smilies placed directly after bbcode tags will not get parsed. Smilies always need to be separated by spaces. + +7. PHP compatibility issues +============================ + +phpBB 3.2.x takes advantage of new features added in PHP 7.1.0. We recommend that you upgrade to the latest stable release of PHP to run phpBB. The minimum version required is PHP 7.1.0 and the maximum supported version is the latest stable version of PHP. + +Please remember that running any application on a development (unstable, e.g. a beta release) version of PHP can lead to strange/unexpected results which may appear to be bugs in the application. Therefore, we recommend you upgrade to the newest stable version of PHP before running phpBB. If you are running a development version of PHP please check any bugs you find on a system running a stable release before submitting. + +This board has been developed and tested under Linux and Windows (amongst others) running Apache using MySQL 3.23, 4.x, 5.x, MariaDB 5.x, PostgreSQL 8.x, Oracle 8 and SQLite 3. Versions of PHP used range from 7.1.0 to 7.2.x and 7.3.x without issues. + +7.i. Notice on PHP security issues +-------------------------------------------- + +Currently there are no known issues regarding PHP security. + + +.. _Language Packs: https://www.phpbb.com/languages/ +.. _Customisation Database: https://www.phpbb.com/customise/db/ diff --git a/development/start/install.rst b/development/start/install.rst new file mode 100644 index 00000000..3cfab675 --- /dev/null +++ b/development/start/install.rst @@ -0,0 +1,295 @@ +============ +Installation +============ + +1. Quick install +================ + +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 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 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) +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 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**: +MySQL 3.23 or above (MySQLi supported) +MariaDB 5.1 or above +PostgreSQL 8.3+ +SQLite 3.6.15+ +MS SQL Server 2000 or above (via ODBC or the native adapter) +Oracle +PHP **7.1.0+** but less than PHP **7.3** with support for the database you intend to use. +The following PHP modules are required: +json +getimagesize() function must be enabled. +Presence of the following modules within PHP will provide access to additional features, but they are not required: +zlib Compression support +Remote FTP support +XML support +GD Support +If your server or hosting account does not meet the requirements above then you will be unable to install phpBB 3.2.x. + +3. New installation +=================== + +Installation of phpBB will vary according to your server and database. If you have shell access to your account (via telnet or ssh for example) you may want to upload the entire phpBB archive (in binary mode!) to a directory on your host and unarchive it there. + +If you do not have shell access or do not wish to use it, you will need to decompress the phpBB archive to a local directory on your system using your favourite compression program, e.g. winzip, rar, zip, etc. From there you must FTP **ALL** the files it contains (being sure to retain the directory structure and filenames) to your host. Please ensure that the cases of filenames are retained, do **NOT** force filenames to all lower or upper case as doing so will cause errors later. + +All .php, .sql, .cfg, .css, .js, .html, .htaccess and .txt files should be uploaded in **ASCII** mode, while all graphics should be uploaded in **BINARY** mode. If you are unfamiliar with what this means please refer to your FTP client documentation. In most cases this is all handled transparantly by your ftp client, but if you encounter problems later you should be sure the files were uploaded correctly as described here. + +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 ``/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 +------------------- + +The initial screen gives you a short introduction into phpBB. It allows you to read the license phpBB is released under (General Public License v2) and provides information about how you can receive support. To start the installation, use the **INSTALL** tab. + +3.ii. Requirements +------------------- + +The first page you will see after starting the installation is the Requirements list. phpBB automatically checks whether everything that it needs to run properly is installed on your server. You need to have at least the minimum PHP version installed, and at least one database available to continue the installation. Also important, is that all shown folders are available and have the correct permissions. Please see the description of each section to find out whether they are optional or required for phpBB to run. If everything is in order, you can continue the installation with Start Install. + +3.iii. Database settings +------------------------ + +You now have to decide which database to use. See the `2. Requirements`_ section for information on which databases are supported. If you do not know your database settings, please contact your host and ask for them. You will not be able to continue without them. You need: + +- The Database Type - the database you will be using. +- The Database server hostname or DSN - the address of the database server. +- The Database server port - the port of the database server (most of the time this is not needed). +- The Database name - the name of the database on the server. +- The Database username and Database password - the login data to access the database. + +.. note:: if you are installing using SQLite, you should enter the full path to your database file in the DSN field and leave the username and password fields blank. For security reasons, you should make sure that the database file is not stored in a location accessible from the web. + +You don't need to change the Prefix for tables in database setting, unless you plan on using multipe phpBB installations on one database. In this case, you can use a different prefix for each installation to make it work. + +After you entered your details, you can continue with the Proceed to next step button. Now phpBB will check whether the data you entered will lead to a successful database connection and whether tables with the same prefix already exist. + +A **Could not connect** to the database error means that you didn't enter the database data correctly and it is not possible for phpBB to connect. Make sure that everything you entered is in order and try again. Again, if you are unsure about your database settings, please contact your host. + +If you installed another version of phpBB before on the same database with the same prefix, phpBB will inform you and you just need to enter a different database prefix. + +If you see the **Successful Connection** message, you can continue to the next step. + +3.iv Administrator details +-------------------------- + +Now you have to create your administration user. This user will have full administration access and he/she will be the first user on your forum. All fields on this page are required. You can also set the default language of your forum on this page. In a vanilla phpBB installation, we only include British English. You can download further languages from https://www.phpbb.com/, and add them before installing or later. + +3.v Configuration file +---------------------- + +In this step, phpBB will try to write the configuration file automatically. The forum needs the configuration file in order to operate. It contains all the database settings, so without it, phpBB will not be able to access the database. + +Usually, writing the configuration file automatically works fine. If the file permissions are not set correctly, this process can fail. In this case, you need to upload the file manually. phpBB asks you to download the `config.php` file and tells you what to do with it. Please read the instructions carefully. After you have uploaded the file, use Done to get to the last step. If Done returns you to the same page as before, and does not return a success message, you did not upload the file correctly. + +3.vi Advanced settings +---------------------- + +The Advanced settings allow you to set additional parameters of the board configuration. They are optional and you can always change them later. So, even if you are not sure what these settings mean, you can still proceed to the final step and finish the installation. + +If the installation was successful, you can now use the **Login** button to visit the Administration Control Panel. Congratulations, you have installed phpBB successfully. But there is still work ahead! + +If you are unable to get phpBB installed even after reading this guide, please look at the support section of the installer's introduction page to find out where you can ask for further assistance. + +At this point if you are converting from phpBB 2.0.x, you should refer to `6. Conversion from phpBB 2.0.x to phpBB 3.2.x`_ for further information. If not, you should remove the install directory from your server as you will only be able to access the Administration Control Panel whilst it is present. + +4. Updating from stable releases of phpBB 3.2.x +================================================ + +If you are currently using a stable release of phpBB, updating to this version is straightforward. You would have downloaded one of four packages and your choice determines what you need to do. +.. note:: Before updating, we heavily recommend you do a full backup of your database and existing phpBB files! If you are unsure how to achieve this please ask your hosting provider for advice. + +**Please make sure you update your phpBB source files too, even if you just run the database updater.** If you have shell access to your server, you may wish to update via the command line interface. From your board's root, execute the following command: ``php bin/phpbbcli.php --safe-mode db:migrate``. + +4.i. Full package +----------------- + +Updating using the full package is the recommended update method for boards without modifications to core phpBB files. + +First, you should make a copy of your existing ``config.php`` file; keep it in a safe place! Next, delete all the existing phpBB files, you should leave your ``files/``, ``images/`` and ``ext/`` directories in place, otherwise you will lose your file attachments, uploaded images and get errors due to missing extension files. You can leave alternative styles in place too. With this complete, you can upload the new phpBB files (see `3. New installation`_ for details if necessary). Once complete, copy back your saved ``config.php``, replacing the new one. Another method is to just **replace** the existing files with the files from the full package - though make sure you do **not** overwrite your ``config.php`` file. + +You should now got to ``/install/app.php/update`` which will display a warning: **No valid update directory was found, please make sure you uploaded the relevant files.** Beneath that warning you will see a radio button **Update database only**, just click **Submit**. Depending on your previous version this will make a number of database changes. You may receive **FAILURES** during this procedure. They should not be a cause for concern unless you see an actual **ERROR**, in which case the script will stop (in this case you should seek help via our forums or bug tracker). If you have shell access to your server, you may wish to update via the command line interface. From your board's root, execute the following command: ``php bin/phpbbcli.php --safe-mode db:migrate``. + +Once ``/install/app.php/update`` has completed, it displays the success message: **The database update was successful.** You may proceed to the Administration Control Panel and then remove the install directory as advised. + +4.ii. Changed files +------------------- + +This package is meant for those wanting to only replace the files that were changed between a previous version and the latest version. + +This package contains a number of archives, each contains the files changed from a given release to the latest version. You should select the appropriate archive for your current version, e.g. if you currently have **3.2.0** you should select the appropriate ``phpBB-3.2.1-files.zip/tar.bz2`` file. + +The directory structure has been preserved, enabling you (if you wish) to simply upload the uncompressed contents of the archive to the appropriate location on your server, i.e. simply overwrite the existing files with the new versions. Do not forget that if you have installed any modifications (MODs) these files will overwrite the originals, possibly destroying them in the process. You will need to re-add MODs to any affected file before uploading. + +As for the other update procedures, you should go to ``/install/app.php/update``, select "Update database only" and submit the page after you have finished updating the files. This will update your database schema and increment the version number. If you have shell access to your server, you may wish to update via the command line interface. From your board's root, execute the following command: ``php bin/phpbbcli.php --safe-mode db:migrate``. + +4.iii. Patch file +----------------- + +The patch file package is for those wanting to update through the patch application, and should only be used by those who are comfortable with it. + +The patch file is one solution for those with changes in to the phpBB core files and do not want to re-add them back to all the changed files. To use this you will need command line access to a standard UNIX type **patch application**. If you do not have access to such an application, but still want to use this update approach, we strongly recommend the `4.iv. Automatic update package`_ explained below. It is also the recommended update method. + +A number of patch files are provided to allow you to update from previous stable releases. Select the correct patch, e.g. if your current version is **3.2.0**, you need the ``phpBB-3.2.1-patch.zip/tar.bz2`` file. Place the correct patch in the parent directory containing the phpBB core files (i.e. index.php, viewforum.php, etc.). With this done you should run the following command: ``patch -cl -d [PHPBB DIRECTORY] -p1 < [PATCH NAME]`` (where PHPBB DIRECTORY is the directory name your phpBB Installation resides in, for example phpBB, and where PATCH NAME is the relevant filename of the selected patch file). This should complete quickly, hopefully without any HUNK FAILED comments. + +If you do get failures, you should look at using the `4.ii. Changed files` package to replace the files which failed to patch. Please note that you will need to manually re-add any MODs to these particular files. Alternatively, if you know how, you can examine the ``.rej`` files to determine what failed where and make manual adjustments to the relevant source. + +You should, of course, delete the patch file (or files) after use. As for the other update procedures, you should navigate to ``/install/app.php/update``, select "Update database only" and submit the page after you have finished updating the files. This will update your database schema and data (if appropriate) and increment the version number. If you have shell access to your server, you may wish to update via the command line interface. From your board's root, execute the following command: ``php bin/phpbbcli.php --safe-mode db:migrate``. + +4.iv. Automatic update package +------------------------------ + +This update method is only recommended for installations with modifications to core phpBB files. This package detects changed files automatically and merges in changes if needed. + +The automatic update package will update the board from a given version to the latest version. A number of automatic update files are available, and you should choose the one that corresponds to the version of the board that you are currently running. For example, if your current version is **3.2.0**, you need the ``phpBB-3.2.0_to_3.2.1.zip/tar.bz2`` file. + +To perform the update, either follow the instructions from the **Administration Control Panel->System** Tab - this should point out that you are running an outdated version and will guide you through the update - or follow the instructions listed below. + +- 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/phpBB/install/`` +- Choose the "Update" Tab and follow the instructions + + +4.v. All package types +---------------------- + +If you have non-English language packs installed, you may want to see if a new version has been made available. A number of missing strings may have been added which, though not essential, may be beneficial to users. Please note that at this time not all language packs have been updated so you should be prepared to periodically check for updates. + +These update methods will only update the standard style ``prosilver``, any other styles you have installed for your board will usually also need to be updated. + +5. Updating from phpBB 3.0.x/3.1x to phpBB 3.2.x +================================================== + +Updating from phpBB 3.0.x or 3.1.x to 3.2.x is just the same as `4. Updating from stable releases of phpBB 3.2.x`_ + +However you can also start with a new set of phpBB 3.2.x files. + +Delete all files **EXCEPT** for the following: +The ``config.php`` file +The ``images/`` directory +The ``files/`` directory +The ``store/`` directory +(The ``ext/`` directory +Upload the contents of the 3.2.x Full Package into your forum's directory. Make sure the root level .htaccess file is included in the upload. +Browse to ``/install/app.php/`` update +Read the notice Update database only and press **Submit** +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 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 phpBB in a different location. + +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 phpBB database user account. + +6.ii. Converting +---------------- + +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 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 `_ + +Once completed, your board should be immediately available. If you encountered errors, you should report the problems to our bug tracker or seek help via our forums (see :ref:`5. Reporting Bugs` for details). + +6.iii. Things to do after conversion +------------------------------------ + +After a successful conversion, there may be a few items you need to do - apart from checking if the installation is accessible and everything displayed correctly. + +The first thing you may want to do is to go to the administration control panel and check every configuration item within the general tab. Thereafter, you may want to adjust the forum descriptions/names if you entered HTML there. You also may want to access the other administrative sections, e.g. adjusting permissions, smilies, icons, ranks, etc. + +During the conversion, the search index is not created or transferred. This means after conversion you are not able to find any matches if you want to search for something. We recommend you rebuild your search index within **Administration Control Panel -> Maintenance -> Database -> Search Index**. + +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 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 +-------------------------------- + +**Broken non-latin characters** The conversion script assumes that the database encoding in the source phpBB2 matches the encoding defined in the ``lang_main.php`` file of the default language pack of the source installation. Edit that file to match the database's encoding and re-start the conversion procedure. + +**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 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 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. + +**Smilies** During the conversion you might see warnings about image files where the copying failed. This can happen if the old board's smilies have the same file names as those on the new board. Copy those files manually after the conversion, if you want to continue using the old smilies. + +7. Important (security related) post-Install tasks for all installation methods +=============================================================================== + +Once you have successfully installed phpBB you **MUST** ensure you remove the entire ``install/`` directory. Leaving the install directory in place is a very serious potential security issue which may lead to deletion or alteration of files, etc. Please note that until this directory is removed, phpBB will not operate and a warning message will be displayed. Beyond this **essential** deletion, you may also wish to delete the docs/ directory if you wish. + +With these directories deleted, you should proceed to the administration panel. Depending on how the installation completed, you may have been directed there automatically. If not, login as the administrator you specified during install/conversion and click the **Administration Control Panel** link at the bottom of any page. Ensure that details specified on the **General** tab are correct! + +7.i. Uploadable avatars +----------------------- + +phpBB supports several methods for allowing users to select their own **avatar** (an avatar is a small image generally unique to a user and displayed just below their username in posts). + +Two of these options allow users to upload an avatar from their machine or a remote location (via a URL). If you wish to enable this function you should first ensure the correct path for uploadable avatars is set in **Administration Control Panel -> General -> Board Configuration -> Avatar** settings. By default this is ``images/avatars/upload``, but you can set it to whatever you like, just ensure the configuration setting is updated. You must also ensure this directory can be written to by the webserver. Usually this means you have to alter its permissions to allow anyone to read and write to it. Exactly how you should do this depends on your FTP client or server operating system. + +On UNIX systems, for example, you set the directory to ``a+rwx`` (or ``ugo+rwx`` or even ``777``). This can be done from a command line on your server using chmod or via your FTP client (using the **Change Permissions**, ``chmod`` or other Permissions dialog box, see your FTP client's documentation for help). Most FTP clients list permissions in the form of User (Read, Write, Execute), Group (Read, Write, Execute) and Other (Read, Write, Execute). You need to tick all of these boxes to set correct permissions. + +On Windows systems, you need to ensure the directory is not write-protected and that it has global write permissions (see your server's documentation or contact your hosting provider if you are unsure on how to achieve this). + +Please be aware that setting a directory's permissions to global write access is a potential security issue. While it is unlikely that anything nasty will occur (such as all the avatars being deleted) there are always people out there to cause trouble. Therefore you should monitor this directory and if possible make regular backups. + +7.ii. Webserver configuration +----------------------------- + +Depending on your web server, you may have to configure your server to deny web access to the ``cache/``, ``files/``, ``includes``, ``phpbb``, ``store/``, and vendor directories. This is to prevent users from accessing sensitive files. + +For **Apache** there are ``.htaccess`` files already in place to do this for the most sensitive files and folders. We do however recommend to completely deny all access to the aforementioned folders and their respective subfolders in your Apache configuration. +On **Apache 2.4**, denying access to the ``phpbb`` folder in a phpBB instance located at ``/var/www/html/`` would be accomplished by adding the following access rules to the Apache configuration file (typically ``apache.conf``): + +.. code-block:: text + + + Require all denied + + + Require all denied + + +The same settings can be applied to the other mentioned directories by replacing ``phpbb`` by the respective directory name. Please note that there are differences in syntax between Apache version `2.2 `_ and `2.4 `_. + +For **Windows** based servers using **IIS** there are ``web.config`` files already in place to do this for you. For other webservers, you will have to adjust the configuration yourself. Sample files for **nginx** and **lighttpd** to help you get started may be found in the ``docs/`` directory. + +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. 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 -------------------- diff --git a/documentation/content/en/chapters/admin_guide.xml b/documentation/content/en/chapters/admin_guide.xml index 345c35c2..f82e1868 100644 --- a/documentation/content/en/chapters/admin_guide.xml +++ b/documentation/content/en/chapters/admin_guide.xml @@ -10,7 +10,7 @@ Administration Guide - This chapter describes the phpBB 3.3 admin controls. + This chapter describes the phpBB admin controls.
    @@ -21,7 +21,7 @@ The Administration Control Panel - Even more so than its predecessor, phpBB 3.3 "Proteus" is highly configurable. You can tune, adjust, or turn off almost all features. To make this load of settings as accessible as possible, we redesigned the Administration Control Panel (ACP) completely. + Even more so than its predecessor, phpBB is highly configurable. You can tune, adjust, or turn off almost all features. To make this load of settings as accessible as possible, we redesigned the Administration Control Panel (ACP) completely. Click on the Administration Control Panel link on the bottom of the default forum style to visit the ACP. The ACP has seven different sections by default with each containing a number of subsections. We will discuss each section in this Admin Guide. @@ -146,7 +146,7 @@ Private Messaging Private Messages are a way for registered members to communicate privately through your board without the need to fall back to e-mail or instant messaging. You can disable this feature with the Private Messaging setting. This will keep the feature turned off for the whole board. You can disable private messages for selected users or groups with Permissions. Please see the Permissions section for more information. - Proteus allows users to create own personal folders to organise Private Messages. The Maximum private message folders setting defines the number of message folders they can create. The default value is 4. You can disable the feature with setting value to 0. + phpBB allows users to create own personal folders to organise Private Messages. The Maximum private message folders setting defines the number of message folders they can create. The default value is 4. You can disable the feature with setting value to 0. Max Private Messages Per Box sets the number of Private Messages each folder can contain. The default value is 50, Set it to 0 to allow unlimited messages per folder. If you limit the number of messages users can store in their folders, you need to define a default action that is taken once a folder is full. This can be changed in the "Full Folder Default Action" list. The oldest message gets deleted or the new message will be held back until the folder has place for it. Note that users will be able to choose this for themselves in their PM options and this setting only changes the default value they face. This will not override the action a user chosen. When sending a private message, it is still possible to edit the message until the recipient reads it. After a sent private message has been read, editing the message is no longer possible. To limit the time a message can be edited before the recipient reads it, you can set the Limit Editing Time. The default value is 0, which allows editing until the message is read. Note that you can disallow users or groups to edit Private Messages after sending through Permissions. If the permission to edit messages is denied, it will override this setting. @@ -330,30 +330,37 @@
    -
    +
    - MennoniteHobbit + Marc - Jabber settings - - phpBB3 also has the ability to communicate messages to users via Jabber, your board can be configured to board notifications via Jabber. Here, you can enable and control exactly how your board will use Jabber for communication. + Web Push settings - - Some Jabber servers include gateways or transports which allow you to contact users on other networks. Not all servers offer all transports and changes in protocols can prevent transports from operating. Note that it may take several seconds to update Jabber account details, so do not stop the script until it has finished! - + phpBB also has the ability to send notifications to users via Web Push. Your board can be configured to board notifications via Web Push. - Jabber settings - Enable Jabber: Set this to Enabled if you want to enable the use of Jabber for messaging and notifications. - Jabber server: The Jabber server that your board will use. For a list of public servers, see jabber.org's list of open, public servers. - Jabber port: The port that the Jabber server specified above is located on. Port 5222 is the most common port; if you are unsure about this, leave this value alone. - Jabber username or JID: The Jabber username or a complete Jabber ID (looks like an e-mail address) that your board will use when connecting to the specified Jabber server. You must specify an already registered account. - Jabber password: The password for the Jabber username specified above. If the Jabber username is unregistered, phpBB3 will attempt to register the above Jabber username, with this specified value as the password.This password will be stored as plain text in the database, visible to everybody who can access your database or who can view this configuration page. - Jabber package size: This is the number of messages that can be sent in one package. If this is set to "0", messages will be sent immediately and is will not be queued for later sending. + Web Push settings + + Enable Web Push: Set this to Yes if you want to enable the use of Web Push for notifications. + + + Server identification public key: The Voluntary Application Server Identification (VAPID) public key is shared to authenticate push messages from your site. You can set this manually or generate the key by clicking on the Generate Identification keys button. + Caution: Modifying the VAPID public key will automatically render all Web Push subscriptions invalid. + + + Server identification private key: The Voluntary Application Server Identification (VAPID) private key is used to generate authenticated push messages dispatched from your site. The VAPID private key must form a valid public-private key pair alongside the VAPID public key. You can set this manually or generate the key by clicking on the Generate Identification keys button. + Caution: Modifying the VAPID private key will automatically render all Web Push subscriptions invalid. + + + Enable all user-based web push notification options by default: When this setting is enabled, users who subscribe and allow browser notifications will start receiving them automatically. Users only need to visit the UCP Notification settings to disable any unwanted notifications. If this setting is disabled, users will not receive any notifications, even if they have subscribed, until they visit the UCP Notification settings to enable the specific notification options they wish to receive. + + + Show “Subscribe” button in notification dropdown: Display a “Subscribe” button in the Notification dropdown, allowing users to easily subscribe to push notifications from anywhere in the forum. +
    @@ -739,8 +746,7 @@ Subforums - One of the features in phpBB 3.3 is subforums. Especially bulletin boards with a high number of forums will benefit from this. In the simple flat category and forum approach in phpBB 2.0, all forums and categories were listed on the forum index. In Proteus you can now put as many forums, links, or categories as you like inside other forums. - + One of the features in phpBB is subforums. Especially bulletin boards with a high number of forums will benefit from this. In the simple flat category and forum approach in phpBB 2.0, all forums and categories were listed on the forum index. In phpBB you can now put as many forums, links, or categories as you like inside other forums. If you have a forum about pets for instance, you are able to put subforums for cats, dogs, or guinea pigs inside it without making the parent "Pets" forum a category. In this example, only the "Pets" forum will be listed on the index like a normal forum. Its subforums will appear as simple links below the forum description (unless you disabled this).
    @@ -1899,7 +1905,7 @@ Permissions - On your board, you will need to control what users can and cannot do, and what they can and cannot see. With the flexible and detailed system that Proteus provides, you have an extensive ability to manage permissions. There are five types of permissions in phpBB3: + On your board, you will need to control what users can and cannot do, and what they can and cannot see. With the flexible and detailed system that phpBB provides, you have an extensive ability to manage permissions. There are five types of permissions in phpBB: Global User permissions Global Moderator permissions diff --git a/documentation/content/en/chapters/glossary.xml b/documentation/content/en/chapters/glossary.xml index 6f4b64b2..c035859a 100644 --- a/documentation/content/en/chapters/glossary.xml +++ b/documentation/content/en/chapters/glossary.xml @@ -180,13 +180,6 @@ - - Jabber - - Jabber is the former name of Extensible Messaging and Presence Protocol (XMPP) an open-source protocol that can be used for instant messenging. For more information on XMPP's role in phpBB, see . - - - Listener @@ -330,6 +323,13 @@ Usergroups are a way of grouping users. This makes it easier to set permissions to many people at the same time (e.g. create a moderator group and give it moderating permissions to a certain forum instead of giving lots of individual people moderating permissions separately). A usergroup has a usergroup moderator (a leader, essentially), who has the ability to add or delete users from the group. Usergroups can be set to hidden, closed or open. If a usergroup is open, users can try requesting membership via the proper page within the group control panel. phpBB 3.3 has six pre-defined usergroups. + + + Web Push + + Web Push notifications are messages sent by a website to a user's browser, even when the user is not actively browsing the site. They deliver notifications to all subscribed devices in real-time. For more information on Web Push notifications in phpBB, see . + + diff --git a/documentation/content/en/chapters/quick_start_guide.xml b/documentation/content/en/chapters/quick_start_guide.xml index 32b3bc3f..851b3a22 100644 --- a/documentation/content/en/chapters/quick_start_guide.xml +++ b/documentation/content/en/chapters/quick_start_guide.xml @@ -98,7 +98,7 @@ Installation - phpBB 3.3 Proteus has an easy to use installation system that will guide you through the installation process. + phpBB has an easy to use installation system that will guide you through the installation process. After you have decompressed the phpBB3 archive and uploaded the files to the location where you want it to be installed, you need to enter the URL into your browser to open the installation screen. The first time you point your browser to the URL (http://www.example.com/phpBB3 for instance), phpBB will detect that it is not yet installed and automatically redirect you to the installation screen.
    Introduction @@ -302,7 +302,7 @@ Setting permissions - After you created your first forum, you have to decide who has access to it and what your users are allowed to do and what not. This is what Permissions are for. You can disallow guests to post or hand out moderating powers, for instance. Almost every aspect of user interaction with phpBB 3.3 Proteus can be adjusted with permissions. + After you created your first forum, you have to decide who has access to it and what your users are allowed to do and what not. This is what Permissions are for. You can disallow guests to post or hand out moderating powers, for instance. Almost every aspect of user interaction with phpBB can be adjusted with permissions.
    Permission types @@ -353,7 +353,7 @@
    The Forum Permissions page shows you two columns, one for users and one for groups to select (see ). The top lists on both columns labelled as Manage Users and Manage Groups show users and groups that already have permissions on at least one of your selected forums set. You can select them and change their permissions with the Edit Permissions button, or use Remove Permissions to remove them which leads to them not having permissions set, and therefore not being able to see the forum or have any access to it (unless they have access to it through another group). The bottom boxes allow you to add new users or groups, that do not currently have permissions set on at least one of your selected forums. To add permissions for groups, select one or more groups either in the Add Groups list (this works similar with users, but if you want to add new users, you have to type them in manually in the Add Users text box or use the Find a member function). Add Permissions will take you to the permission interface. Each forum you selected is listed, with the groups or users to change the permissions for below them. - There are two ways to assign permissions: You can set them manually or use predefined Permission Roles for a simpler but less powerful way. You can switch between both approaches any time you want. You can skip the manual permission introduction and jump directly into the section on "Permissions Roles", if you are eager to get everything running as quickly as possible. But remember that permission roles do only offer a small bit of what the permission system has to offer and we believe that to be a good Proteus administrator, you have to fully grasp permissions. + There are two ways to assign permissions: You can set them manually or use predefined Permission Roles for a simpler but less powerful way. You can switch between both approaches any time you want. You can skip the manual permission introduction and jump directly into the section on "Permissions Roles", if you are eager to get everything running as quickly as possible. But remember that permission roles do only offer a small bit of what the permission system has to offer and we believe that to be a good phpBB administrator, you have to fully grasp permissions. Both ways only differ in the way you set them. They both share the same interface.
    @@ -385,7 +385,7 @@
    Permissions roles - phpBB 3.3 Proteus ships with a number of default permission roles, that offer you a wide variety of options for setting permissions. Instead of having to check each radio button manually, you can select a predefined role in the Rolepull down list. Each role has a detailed description, that will pop up when you hover your mouse over it. Submit your changes with Apply Permissions or Apply All Permissions when you are satisfied with them. That will set the permissions and you are done. + phpBB ships with a number of default permission roles, that offer you a wide variety of options for setting permissions. Instead of having to check each radio button manually, you can select a predefined role in the Rolepull down list. Each role has a detailed description, that will pop up when you hover your mouse over it. Submit your changes with Apply Permissions or Apply All Permissions when you are satisfied with them. That will set the permissions and you are done.
    Permission roles diff --git a/documentation/content/en/chapters/upgrade_guide.xml b/documentation/content/en/chapters/upgrade_guide.xml index 54807b32..19a33846 100644 --- a/documentation/content/en/chapters/upgrade_guide.xml +++ b/documentation/content/en/chapters/upgrade_guide.xml @@ -36,15 +36,15 @@ - Upgrading from 3.0 to 3.3 + Upgrading from 3.0 to 4.0 - Upgrading to phpBB 3.3 will render previously installed MODifications and styles unusable. If you have a custom logo, it will need to be redone after the upgrade. See Knowledge Base: How to Change your Board Logo. + Upgrading to phpBB 4.0 will render previously installed MODifications and styles unusable. If you have a custom logo, it will need to be redone after the upgrade. See Knowledge Base: How to Change your Board Logo. - phpBB 3.3 is not compatible with 3.0 and most of the previous files will need to be removed prior to upgrading. + phpBB 4.0 is not compatible with 3.0 and most of the previous files will need to be removed prior to upgrading. To upgrade, perform the following steps: - Ensure that your server meets the requirements for running phpBB 3.3: + Ensure that your server meets the requirements for running phpBB 4.0: Make a backup of the original files Make a backup of the database Deactivate all styles except for prosilver diff --git a/documentation/content/en/chapters/user_guide.xml b/documentation/content/en/chapters/user_guide.xml index b71b9ec7..c7d8d8cb 100644 --- a/documentation/content/en/chapters/user_guide.xml +++ b/documentation/content/en/chapters/user_guide.xml @@ -146,11 +146,6 @@ Personal settings Personal settings control the information that is displayed when a user views your profile. - ICQ Number: Your account number associated with ICQ system. - AOL Instant Messenger: Your screen name associated with AOL Instant Messenger system. - Windows Live Messenger: Your email address associated with the Windows Live service. - Yahoo Messenger: Your username associated with the Yahoo Messenger service. - Jabber Address: Your username associated with the Jabber service. Facebook: Your unique username/page name associated with the Facebook service. Twitter: Your username associated with the Twitter service. Skype: Your username associated with the Skype service. diff --git a/documentation/create_docs.sh b/documentation/create_docs.sh index 53c7b394..f82439ab 100755 --- a/documentation/create_docs.sh +++ b/documentation/create_docs.sh @@ -1,13 +1,13 @@ #!/bin/bash # set this to the correct path -path=${1:-'/var/www/phpbb.com/htdocs/support/documentation/3.3'} +path=${1:-'/var/www/phpbb.com/htdocs/support/documentation/4.0'} echo "Removing build directory" rm -rf build echo "Creating docs" -xsltproc --xinclude xsl/proteus_php.xsl proteus_doc.xml +xsltproc --xinclude xsl/triton_php.xsl triton_doc.xml exit_code=$? # Capture the exit code if [ "$exit_code" == "0" ]; then diff --git a/documentation/create_pdf.bat b/documentation/create_pdf.bat index 36c6d6eb..08b7f200 100644 --- a/documentation/create_pdf.bat +++ b/documentation/create_pdf.bat @@ -4,9 +4,9 @@ set fop_path=C:\fop echo Removing previous PDF -del proteus_doc.pdf +del triton_doc.pdf echo Creating new PDF -%fop_path%\fop -xml proteus_doc.xml -xsl xsl\proteus_pdf.xsl -pdf proteus_doc.pdf +%fop_path%\fop -xml triton_doc.xml -xsl xsl\triton_pdf.xsl -pdf triton_doc.pdf echo Done diff --git a/documentation/create_pdf.sh b/documentation/create_pdf.sh index 46439462..fec72acc 100755 --- a/documentation/create_pdf.sh +++ b/documentation/create_pdf.sh @@ -1,11 +1,11 @@ #!/bin/bash echo "Removing previous PDF" -if [ -f proteus_doc.pdf ]; then - rm proteus_doc.pdf +if [ -f triton_doc.pdf ]; then + rm triton_doc.pdf fi echo "Creating new PDF" -fop -xml proteus_doc.xml -xsl xsl/proteus_pdf.xsl -pdf proteus_doc.pdf +fop -xml triton_doc.xml -xsl xsl/triton_pdf.xsl -pdf triton_doc.pdf echo "Done" diff --git a/documentation/proteus_doc.xml b/documentation/triton_doc.xml similarity index 86% rename from documentation/proteus_doc.xml rename to documentation/triton_doc.xml index b7cbc825..66c5984d 100644 --- a/documentation/proteus_doc.xml +++ b/documentation/triton_doc.xml @@ -1,9 +1,9 @@ - phpBB 3.3 <emphasis>Proteus</emphasis> Documentation + phpBB 4.0 <emphasis>Triton</emphasis> Documentation - The detailed documentation for phpBB 3.3 Proteus. + The detailed documentation for phpBB 4.0 Triton. @@ -16,7 +16,7 @@ - 2005 + 2025 phpBB Group phpBB Group diff --git a/documentation/xsl/proteus_pdf.xsl b/documentation/xsl/triton_pdf.xsl similarity index 100% rename from documentation/xsl/proteus_pdf.xsl rename to documentation/xsl/triton_pdf.xsl diff --git a/documentation/xsl/proteus_php.xsl b/documentation/xsl/triton_php.xsl similarity index 99% rename from documentation/xsl/proteus_php.xsl rename to documentation/xsl/triton_php.xsl index 54deef8a..6cb55daf 100644 --- a/documentation/xsl/proteus_php.xsl +++ b/documentation/xsl/triton_php.xsl @@ -15,7 +15,7 @@ - + @@ -37,7 +37,7 @@ - + diff --git a/documentation/xsl/proteus_php_subsection.xsl b/documentation/xsl/triton_php_subsection.xsl similarity index 99% rename from documentation/xsl/proteus_php_subsection.xsl rename to documentation/xsl/triton_php_subsection.xsl index 7d94c199..3e342902 100644 --- a/documentation/xsl/proteus_php_subsection.xsl +++ b/documentation/xsl/triton_php_subsection.xsl @@ -15,7 +15,7 @@ - + @@ -40,7 +40,7 @@ - + diff --git a/documentation/xsl/proteus_phpbb_dot_com.xsl b/documentation/xsl/triton_phpbb_dot_com.xsl similarity index 99% rename from documentation/xsl/proteus_phpbb_dot_com.xsl rename to documentation/xsl/triton_phpbb_dot_com.xsl index 8b3fd7f7..36fb988e 100644 --- a/documentation/xsl/proteus_phpbb_dot_com.xsl +++ b/documentation/xsl/triton_phpbb_dot_com.xsl @@ -14,7 +14,7 @@ - + @@ -39,7 +39,7 @@ - + diff --git a/documentation/xsl/proteus_xhtml.xsl b/documentation/xsl/triton_xhtml.xsl similarity index 98% rename from documentation/xsl/proteus_xhtml.xsl rename to documentation/xsl/triton_xhtml.xsl index cff14f91..c91af245 100644 --- a/documentation/xsl/proteus_xhtml.xsl +++ b/documentation/xsl/triton_xhtml.xsl @@ -12,7 +12,7 @@ - +