'+X[Y]+"
";F.childNodes[0].style.height="0";F.childNodes[0].style.overflow=
+"hidden";F.style.width=B[Y]},ha);I&&Z(function(F,Y){F.innerHTML=''+lb[Y]+"
";F.childNodes[0].style.height="0";F.childNodes[0].style.overflow="hidden";F.style.width=ba[Y]},ka);r.outerWidth()
+
+ Other Versions
+ v: {{ current_version.name }}
+
+
+
+{%- endif %}
diff --git a/development/auth/authentication.rst b/development/auth/authentication.rst
new file mode 100644
index 00000000..1b60844f
--- /dev/null
+++ b/development/auth/authentication.rst
@@ -0,0 +1,163 @@
+Auth API
+========
+
+This is an explanation of how to use the phpBB auth/acl API.
+
+.. contents::
+ :local:
+ :depth: 2
+
+1. Introduction
+---------------
+
+What is it?
+^^^^^^^^^^^
+
+The ``auth`` class contains methods related to authorisation of users to access various board functions, e.g., posting, viewing, replying, logging in (and out), etc. If you need to check whether a user can carry out a task or handle user login/logouts, this class is required.
+
+Initialisation
+^^^^^^^^^^^^^^
+
+To use any methods contained within the ``auth`` class, it first needs to be instantiated. This is best achieved early in the execution of the script in the following manner:
+
+.. code-block:: php
+
+ $auth = new phpbb\auth\auth();
+
+Once an instance of the class has been created you are free to call the various methods it contains. Note: if you wish to use the ``auth_admin`` methods you will need to instantiate this separately in the same way.
+
+2. Methods
+----------
+
+Following are the methods you are able to use.
+
+2.i. acl
+^^^^^^^^
+
+The ``acl`` method is the initialisation routine for all the ACL functions. It must be called before any ACL method. It takes one parameter: an associative array containing user information.
+
+.. code-block:: php
+
+ $auth->acl($userdata);
+
+Where ``$userdata`` includes at least: ``user_id``, ``user_permissions``, and ``user_type``.
+
+2.ii. acl_get
+^^^^^^^^^^^^^
+
+This method determines if a user can perform an action either globally or in a specific forum.
+
+.. code-block:: php
+
+ $result = $auth->acl_get('option'[, forum]);
+
+- ``option``: e.g., 'f_list', 'm_edit', 'a_adduser', etc. Use ``!option`` to negate.
+- ``forum`` (optional): integer ``forum_id``.
+
+Returns a positive integer if allowed, zero if denied.
+
+2.iii. acl_gets
+^^^^^^^^^^^^^^^
+
+This method checks multiple permissions at once.
+
+.. code-block:: php
+
+ $result = $auth->acl_gets('option1'[, 'option2', ..., forum]);
+
+Returns a positive integer if *any* of the permissions is granted.
+
+2.iv. acl_getf
+^^^^^^^^^^^^^^
+
+This method checks in which forums a user has a certain permission.
+
+.. code-block:: php
+
+ $result = $auth->acl_getf('option'[, clean]);
+
+- ``option``: permission string (negation with ``!`` allowed)
+- ``clean``: boolean. If true, only forums where permission is granted are returned.
+
+Returns an associative array:
+
+.. code-block:: php
+
+ array(forum_id1 => array(option => integer), forum_id2 => ...)
+
+2.v. acl_getf_global
+^^^^^^^^^^^^^^^^^^^^
+
+Checks if a user has a permission globally or in at least one forum.
+
+.. code-block:: php
+
+ $result = $auth->acl_getf_global('option');
+
+Returns a positive integer or zero.
+
+2.vi. acl_cache
+^^^^^^^^^^^^^^^
+
+**Private method.** Automatically called when needed. Generates user_permissions data.
+
+2.vii. acl_clear_prefetch
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Clears the ``user_permissions`` column in the users table.
+
+.. code-block:: php
+
+ $user_id = 2;
+ $auth->acl_clear_prefetch($user_id);
+
+Use ``$user_id = 0`` to clear cache for all users. Returns null.
+
+2.viii. acl_get_list
+^^^^^^^^^^^^^^^^^^^^
+
+Returns an array describing which users have which permissions in which forums.
+
+.. code-block:: php
+
+ $user_id = array(2, 53);
+ $permissions = array('f_list', 'f_read');
+ $forum_id = array(1, 2, 3);
+ $result = $auth->acl_get_list($user_id, $permissions, $forum_id);
+
+Parameter types:
+- ``$user_id``: ``false``, int, or array of int
+- ``$permissions``: ``false``, string, or array of string
+- ``$forum_id``: ``false``, int, or array of int
+
+2.ix. Miscellaneous
+^^^^^^^^^^^^^^^^^^^
+
+Additional methods for pulling raw permission data:
+
+.. code-block:: php
+
+ function acl_group_raw_data($group_id = false, $opts = false, $forum_id = false)
+ function acl_user_raw_data($user_id = false, $opts = false, $forum_id = false)
+ function acl_raw_data_single_user($user_id)
+ function acl_raw_data($user_id = false, $opts = false, $forum_id = false)
+ function acl_role_data($user_type, $role_type, $ug_id = false, $forum_id = false)
+
+Use ``acl_raw_data`` for general queries; others are optimized for specific data.
+
+3. Admin Related Functions
+--------------------------
+
+Additional methods are available within the ``auth_admin`` class for managing permissions, options, and user cache. It is found in:
+
+::
+
+ includes/acp/auth.php
+
+Instantiate separately:
+
+.. code-block:: php
+
+ $auth_admin = new auth_admin();
+
+This gives access to both ``auth_admin`` and ``auth`` methods.
diff --git a/development/cli/getting_started.rst b/development/cli/getting_started.rst
index 8da62f67..871b3995 100644
--- a/development/cli/getting_started.rst
+++ b/development/cli/getting_started.rst
@@ -64,11 +64,95 @@ Common options that can be used with any of phpBB's CLI commands.
:header: "Option", "Usage"
:delim: |
- --help (-h) | Display a help message
- --quiet (-q) | Do not output any message
- --verbose (-v,-vv,-vvv) | Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
- --version (-V) | Display this application version
- --ansi | Force ANSI (colors) output
- --no-ansi | Disable ANSI (colors) output
- --no-interaction (-n) | Do not ask any interactive question
- --safe-mode | Run in Safe Mode (without extensions)
+ ``--help, -h`` | Display a help message
+ ``--quiet, -q`` | Do not output any message
+ ``--verbose, -v, -vv, -vvv`` | Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
+ ``--version, -V`` | Display this application version
+ ``--ansi`` | Force ANSI (colors) output
+ ``--no-ansi`` | Disable ANSI (colors) output
+ ``--no-interaction, -n`` | Do not ask any interactive question
+ ``--safe-mode`` | Run in Safe Mode (without extensions)
+
+Install phpBB using the CLI
+===========================
+
+The phpBB CLI installer uses a YAML file populated with the data needed to configure a database for a new phpBB installation. You can find a sample configuration file in ``docs/install-config.sample.yml``. Copy this file to ``install/install-config.yml``. Adjust the sample parameters to your needs. For example, a MySQL database using the ``mysqli`` interface hosted on a ``localhost`` server with the root user ``bertie`` and password ``bertiepasswd`` and named ``bertiedb`` would look like:
+
+.. code-block:: console
+
+ installer:
+ admin:
+ name: admin
+ password: mypassword
+ email: admin@example.org
+
+ board:
+ lang: en
+ name: My Board
+ description: My amazing new phpBB board
+
+ database:
+ dbms: mysqli
+ dbhost: ~
+ dbport: ~
+ dbuser: bertie
+ dbpasswd: bertiepasswd
+ dbname: bertiedb
+ table_prefix: phpbb_
+
+ email:
+ enabled: false
+ smtp_delivery : ~
+ smtp_host: ~
+ smtp_port: ~
+ smtp_auth: ~
+ smtp_user: ~
+ smtp_pass: ~
+
+ server:
+ cookie_secure: false
+ server_protocol: http://
+ force_server_vars: false
+ server_name: localhost
+ server_port: 80
+ script_path: /
+
+ extensions: ['phpbb/viglink']
+
+You can adjust additional settings like the admin's username, email address and the board info. Make sure the file is readable by the CLI.
+
+To install the board, run the following command:
+
+.. code-block:: console
+
+ $ php install/phpbbcli.php install install-config.yml
+
+The installer will start now and show its progress during the installation.
+
+Update phpBB using the CLI
+==========================
+
+Much like installing from the CLI, phpBB can also be updated from the CLI using a YAML file with update instructions. You can find a sample update configuration file in ``docs/update-config.sample.yml``. Copy this file to ``install/update-config.yml``.
+
+.. code-block:: console
+
+ updater:
+ type: all
+ extensions: ['phpbb/viglink']
+
+In this state, the updater will update your phpBB database and it will also replace all phpBB files with the updated files, giving you a complete upgrade.
+
+However, if you have already replaced the files via the filesystem or FTP, you can choose to update the database only by changing the ``type`` from ``all` to ``db_only``:
+
+.. code-block:: console
+
+ updater:
+ type: db_only
+
+To update the board, run the following command:
+
+.. code-block:: console
+
+ $ php install/phpbbcli.php update update-config.yml
+
+The updater will start and show its progress.
\ No newline at end of file
diff --git a/development/conf.py b/development/conf.py
index bfa74170..45d49f30 100644
--- a/development/conf.py
+++ b/development/conf.py
@@ -33,7 +33,9 @@
'sensio.sphinx.configurationblock',
'sensio.sphinx.phpcode',
'sensio.sphinx.bestpractice',
- 'sphinxcontrib.phpdomain'
+ 'sphinxcontrib.phpdomain',
+ 'sphinx_multiversion',
+ 'sphinx_rtd_theme'
]
# Add any paths that contain templates here, relative to this directory.
@@ -50,16 +52,16 @@
# General information about the project.
project = u'phpBB'
-copyright = u'2015, phpBB Limited'
+copyright = u'2015 - 2021, phpBB Limited'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
-version = '3.1'
+version = '3.3'
# The full version, including alpha/beta/rc tags.
-release = '3.1.x'
+release = '3.3.x'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@@ -91,7 +93,7 @@
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'monokai'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
@@ -99,6 +101,10 @@
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
+# Options for sphinx_multiversion
+smv_tag_whitelist = 'None'
+smv_branch_whitelist = r'^(3.2.x|3.3.x|master)$'
+smv_latest_version = r"master"
# -- Options for HTML output ----------------------------------------------
import sphinx_rtd_theme
@@ -117,13 +123,25 @@
display_github=True,
github_repo='documentation',
github_user='phpbb',
- github_version=version + ".x",
+ github_version=release,
source_suffix='.rst',
)
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# Additional CSS files to include
+html_css_files = [
+ 'css/phpbb.css',
+ 'css/jquery.dataTables.min.css',
+]
+
+# Additional JS files to include
+html_js_files = [
+ 'js/jquery.dataTables.min.js',
+ 'js/main.js'
+]
+
# The name for this set of Sphinx documents. If None, it defaults to
# "
+ {%- if versions.tags %}
+
+-
+
- Tags + {%- for item in versions.tags %} +
- {{ item.name }} + {%- endfor %} +
-
+
- Branches + {%- for item in versions.branches %} +
- {{ item.name }} + {%- endfor %} +
diff --git a/development/db/structured_conditionals.rst b/development/db/structured_conditionals.rst new file mode 100644 index 00000000..8c5323fa --- /dev/null +++ b/development/db/structured_conditionals.rst @@ -0,0 +1,524 @@ +============================ +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/coding_guidelines.rst b/development/development/coding_guidelines.rst index 23eb5695..9a7a0c10 100644 --- a/development/development/coding_guidelines.rst +++ b/development/development/coding_guidelines.rst @@ -7,6 +7,8 @@ latest versions on area51: * Rules for `Olympus (3.0.x) code