Skip to content

Commit d933849

Browse files
marc1706marc1706
committed
Merge pull request #255 from phpbb/add/tutorials
Add tutorial for parsing text from wiki
2 parents dca960c + c98f7d5 commit d933849

7 files changed

Lines changed: 843 additions & 1 deletion

File tree

‎development/extensions/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@ Welcome to phpBB's extension development tutorial and documentation.
1616
tutorial_notifications
1717
tutorial_permissions
1818
tutorial_authentication
19+
tutorial_parsing_text
1920
tutorial_bbcodes
21+
tutorial_templates
2022
tutorial_advanced
2123
tutorial_testing
2224
*

‎development/extensions/permission_system.rst‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
=================
2+
Permission system
3+
=================
4+
5+
Introduction
6+
============
7+
The permission system is the system that allows board administrator decide what users are allowed do on the board.
8+
Information on how to you use permission system can be found on :doc:`Tutorial: Permissions <tutorial_permissions>`.
9+
10+
An administrator with the correct permissions has access to the administration control panel (ACP) which contains the
11+
administrative side of the permissions system. The administrator then setups the permissions to allow users to have the
12+
rights to do certain things, tasks or see certain features. At the end of the day each permission is what is called
13+
a permission option and users obtain the rights to these options either directly, from a group or from a role that is
14+
assigned to them or a group they are in.
15+
16+
Permission options
17+
==================
18+
Permission options are the individual options that allow or deny you access to features. Examples are ``f_post``, ``m_delete``,
19+
``a_ban`` and ``u_sendpm``. Permission options are group into permissions of the same type.
20+
21+
Examples of that are the ``f_``, ``m_``, ``a_`` and ``u_`` prefixes:
22+
23+
- ``f_`` - Forum permissions
24+
- ``m_`` - Moderator permissions
25+
- ``a_`` - Administrator permissions
26+
- ``u_`` - User permissions
27+
28+
User permissions
29+
================
30+
Individual user permissions are stored in the phpbb_users table in the ``user_permissions`` column.
31+
In addition to that, users that have the ``a_switchperm`` permission may assume the permissions of another user.
32+
When this is done, the user id of the user one is assuming the permissions of are stored in the column ``user_perm_form``.
33+
34+
Permission options
35+
==================
36+
Permission options are stored in the table phpbb_acl_options. The fields of this table are defined as follows:
37+
38+
- ``auth_option_id`` - Unique ID of option ``auth_option``
39+
- ``auth_option`` - Name of permission option
40+
- ``is_global`` - Set to 1 if a global option else set to 0
41+
- ``is_local`` - Set to 1 if a local option else set to 0
42+
- ``founder_only`` - Set to 1 if a founder only option else set to 0
43+
44+
A local permission option is a option that can be granted to a user on a forum by forum basis.
45+
This allows one to grant users options to perform a task in one forum but not another. They are also called
46+
forum based permissions. In contrast to that, a global permission option is an option that is valid board wide.
47+
48+
Permission options can also be both global and local. An example is 'm_edit', the moderator permission to edit a topic.
49+
Some users can be granted this permission on a single forum while other users might be granted this permission board wide.
50+
In order to support this, the option is set to both local and global.
51+
52+
Founders
53+
========
54+
A founder is a special type of user. It should only be granted to the most trusted of administrators.
55+
Founders can access the permission system to correct their permissions even if another administrator has removed their permissions.
56+
Only a founder can remove the founder status of another founder. Therefore, a founder only permission is a type of
57+
permission that is limited to this special type of user. By default, no permission is set to founder only.
58+
59+
Roles
60+
=====
61+
Roles are a predefined setup of permission options that can be applied to users or groups.
62+
If the permission options of a role are changed, the users or groups assigned that role get updated automatically.
63+
64+
Roles are stored in the ``phpbb_acl_roles`` table which is comprised of the following columns:
65+
66+
- ``role_id`` - Unique ID of role
67+
- ``role_name`` - Role name normally as a lang key
68+
- ``role_description`` - Role description normally as a lang key
69+
- ``role_type`` - ``a_``, ``u_``, ``m_`` or ``f_`` depending on what type of role it is
70+
- ``role_order`` - Number indicating display order in the ACP
71+
72+
The permission options for a role are stored in the ``phpbb_acl_roles_data`` table which is comprised of the
73+
following columns:
74+
75+
- ``role_id`` - Role id from phpbb_acl_roles
76+
- ``auth_option_id`` - Option id from ``phpbb_acl_options``
77+
- ``auth_setting`` - Stores either ``ACL_YES`` (1), ``ACL_NO`` (-1) or ``ACL_NEVER`` (0)
78+
79+
Your effective permission for any option is built up from a combination of details such as which groups you are
80+
a member of, which role you have assigned and whether you have been assigned directly that permission.
81+
As such you might have opposing permissions.
82+
83+
The ``YES``, ``NO`` and ``NEVER`` system works to allow phpBB to combine these different "answers" for an option and
84+
give you the effective permission.
85+
If at any point one gets a ``NEVER``, that will be the effective permission for that option since a ``NEVER`` can not be
86+
overridden by a ``YES``. It will force the permission to be ``NO`` in the end, no matter what other roles, groups permissions,
87+
etc. might say ``YES``. A ``NO`` will however be overridden by a ``YES``.
88+
89+
When checking permissions, it's also important to keep in mind whether the global or local permissions should be checked.
90+
If ``acl_get`` is called without a forum id, the global permissions will be used. Instead, passing a forum id will also
91+
check the local permissions which can then potentially override a ``NO`` with a ``YES``.
92+
After checking all user, group, forum, and global permissions, the return permission is always either ``YES`` or ``NO``,
93+
``NEVER`` is only used to enforce a ``NO``.
94+
95+
Roles specific to users are stored in the ``phpbb_acl_users`` table:
96+
97+
- ``user_id`` - User id from ``phpbb_users``
98+
- ``forum_id`` - Forum id from ``phpbb_forums`` if a local option, else 0
99+
- ``auth_option_id`` - Option id from ``phpbb_acl_options``
100+
- ``auth_role_id`` - Role id from ``phpbb_acl_roles`` if obtained from a role, else 0
101+
- ``auth_setting`` - Stores either ``ACL_YES`` (1), ``ACL_NO`` (-1) or ``ACL_NEVER`` (0)
102+
103+
Roles specific to groups are stored in the ``phpbb_acl_groups`` table:
104+
105+
- ``group_id`` - Group id from ``phpbb_groups``
106+
- ``forum_id`` - Forum id from ``phpbb_forums`` if a local option, else 0
107+
- ``auth_option_id`` - Option id from ``phpbb_acl_options``
108+
- ``auth_role_id`` - Role id from ``phpbb_acl_roles`` if obtained from a role, else 0
109+
- ``auth_setting`` - Stores either ``ACL_YES`` (1), ``ACL_NO`` (-1) or ``ACL_NEVER`` (0)
110+
111+
Checking permissions
112+
====================
113+
114+
A user's permission can be checked by calling ``$auth->acl_get('u_garage_browse');``. The argument is the option
115+
you want to check for. If it is specific to a forum (i.e local) then you call it as ``$auth->acl_get('u_garage_browse', 3);``
116+
where ``3`` is the forum id.
117+
118+
For forums one can use the forum specific call ``$auth->acl_getf('f_your_permission');``.
119+
120+
It is also possible to check for more than one option:
121+
122+
.. code-block:: php
123+
124+
$auth->acl_gets(option1[, option2, ..., optionN, $forumId]);

‎development/extensions/tutorial_parsing_text.rst‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
======================
2+
Tutorial: Parsing text
3+
======================
4+
5+
Database fields
6+
===============
7+
phpBB uses the following database fields where BBCode is allowed (forum description, forum rules, post content, ...):
8+
9+
- **foo** - Text itself
10+
- **foo_bbcode_uid** - a randomly generated unique identifier to mark the BBCodes and used for quicker parsing
11+
- **foo_bbcode_bitfield** - a `bit field <https://en.wikipedia.org/wiki/Bit_field>`_ containing the information which bbcode is used in the text so only the relevant ones need to be loaded from the database. **NOTE: No longer used in posts generated in phpBB 3.2+**
12+
- **foo_options** - a bit field containing the information whether bbcode, smilies and magic urls are enabled (OPTION_FLAG_BBCODE, OPTION_FLAG_SMILIES and OPTION_FLAG_LINKS). Sometimes you will find this separated into enable_bbcode, enable_smilies and enable_magic_url
13+
14+
Column names will vary, replace ``foo`` with the respective column name (e.g. ``text``, ``text_bbcode_uid``, ...).
15+
16+
Parsing text with BBCodes & smilies
17+
===================================
18+
19+
Inserting text into DB
20+
----------------------
21+
22+
.. code-block:: php
23+
24+
$text = $this->request->variable('text', '', true);
25+
$uid = $bitfield = $options = ''; // will be modified by generate_text_for_storage
26+
$allow_bbcode = $allow_urls = $allow_smilies = true;
27+
generate_text_for_storage($text, $uid, $bitfield, $options, $allow_bbcode, $allow_urls, $allow_smilies);
28+
29+
$sql_ary = array(
30+
'text' => $text,
31+
'bbcode_uid' => $uid,
32+
'bbcode_bitfield' => $bitfield,
33+
'bbcode_options' => $options,
34+
);
35+
36+
$sql = 'INSERT INTO ' . YOUR_TABLE . ' ' . $this->db->sql_build_array('INSERT', $sql_ary);
37+
$this->db->sql_query($sql);
38+
39+
The above method uses the bbcode options database field which is used in many places instead of enable_smiles,
40+
enable_bbcode and enable_magic_url. Here is how to insert it into the database using the enable_smilies, enable_bbcode
41+
and enable_magic_url tables.
42+
43+
.. code-block:: php
44+
45+
$text = $this->request->variable('text', '', true);
46+
$uid = $bitfield = $options = ''; // will be modified by generate_text_for_storage
47+
$allow_bbcode = $allow_urls = $allow_smilies = true;
48+
generate_text_for_storage($text, $uid, $bitfield, $options, $allow_bbcode, $allow_urls, $allow_smilies);
49+
50+
$sql_ary = array(
51+
'text' => $text,
52+
'bbcode_uid' => $uid,
53+
'bbcode_bitfield' => $bitfield,
54+
'enable_bbcode' => $allow_bbcode,
55+
'enable_magic_url' => $allow_urls,
56+
'enable_smilies' => $allow_smilies,
57+
);
58+
59+
$sql = 'INSERT INTO ' . YOUR_TABLE . ' ' . $this->db->sql_build_array('INSERT', $sql_ary);
60+
$this->db->sql_query($sql);
61+
62+
Displaying text from DB
63+
-----------------------
64+
65+
This example uses the bbcode_options field which is used in forums and groups description parsing:
66+
67+
.. code-block:: php
68+
69+
$sql = 'SELECT text, bbcode_uid, bbcode_bitfield, bbcode_options
70+
FROM ' . YOUR_TABLE;
71+
$result = $this->db->sql_query($sql);
72+
$row = $this->db->sql_fetchrow($result);
73+
$this->db->sql_freeresult($result);
74+
75+
$text = generate_text_for_display($row['text'], $row['bbcode_uid'], $row['bbcode_bitfield'], $row['bbcode_options']);
76+
77+
$this->template->assign_vars([
78+
'TEXT' => $text,
79+
]);
80+
81+
The next one uses the enable_bbcode, enable_smilies and enable_magic_url flags which can be used instead of the above method and is used in parsing posts:
82+
83+
.. code-block:: php
84+
85+
$sql = 'SELECT text, bbcode_uid, bbcode_bitfield, enable_bbcode, enable_smilies, enable_magic_url
86+
FROM ' . YOUR_TABLE;
87+
$result = $this->db->sql_query($sql);
88+
$row = $this->db->sql_fetchrow($result);
89+
$this->db->sql_freeresult($result);
90+
91+
$row['bbcode_options'] = (($row['enable_bbcode']) ? OPTION_FLAG_BBCODE : 0) +
92+
(($row['enable_smilies']) ? OPTION_FLAG_SMILIES : 0) +
93+
(($row['enable_magic_url']) ? OPTION_FLAG_LINKS : 0);
94+
$text = generate_text_for_display($row['text'], $row['bbcode_uid'], $row['bbcode_bitfield'], $row['bbcode_options']);
95+
96+
$this->template->assign_vars([
97+
'TEXT' => $text,
98+
]);
99+
100+
Generating text for editing
101+
---------------------------
102+
103+
.. code-block:: php
104+
105+
$sql = 'SELECT text, bbcode_uid, bbcode_options
106+
FROM ' . YOUR_TABLE;
107+
$result = $this->db->sql_query_limit($sql, 1);
108+
$row = $this->db->sql_fetchrow($result);
109+
$this->db->sql_freeresult($result);
110+
111+
$post_data = generate_text_for_edit($row['text'], $row['bbcode_uid'], $row['bbcode_options']);
112+
113+
$this->template->assign_vars([
114+
'POST_TEXT' => $post_data['text'],
115+
'S_ALLOW_BBCODES' => $post_data['allow_bbcode'],
116+
'S_ALLOW_SMILIES' => $post_data['allow_smilies'],
117+
'S_ALLOW_URLS' => $post_data['allow_urls'],
118+
]);
119+
120+
Database fields for BBCode
121+
--------------------------
122+
123+
The following column definitions are expected for BBCodes:
124+
125+
.. code-block::
126+
127+
"text": [
128+
"MTEXT_UNI",
129+
"" // Default empty string
130+
],
131+
"bbcode_uid": [
132+
"VCHAR:8",
133+
"" // Default empty string
134+
],
135+
"bbcode_bitfield": [
136+
"VCHAR:255",
137+
"" // Default empty string
138+
],
139+
"bbcode_options": [
140+
"UINT:11",
141+
7 // Default all enabled
142+
],

0 commit comments

Comments
 (0)