Quick links: Content - sections - sub sections
EN FR

Before using jAcl2 API and its "db" driver (or the "dbcache" driver), you have to setup a database and fill it with elements composing rights.

Installation

jAcl2.db driver (or jAcl2.dbcache) requires a database to work. You have to create it with the needed tables and setup a connection profile.

Connection configuration

See the documentation about jDb setup.

If jAcl2 tables are not located in your default db profile, you should setup a profile called jacl2_profile, or an alias jacl2_profile to an existing profile. An example profiles.ini.php:


[jdb:default]
driver="mysql"
database="jelix"
host= "localhost"
user= "jelix"
password= "jelix"
persistent= on
force_encoding=true

[jdb:jacl2_profile]
driver="mysql"
database="rights"
host= "localhost"
user= "jelix"
password= "xilej"
persistent= on
force_encoding=true

jAcl2.db tables

To create and initialise tables needed by the driver, you should install the module jacl2db.


# launch the configuration
php dev.php module:configure jacl2db

If you want to initialize rights for a first user/group named "admin":


php dev.php module:configure -p defaultuser jacl2db

Then launch php install/installer.php.

Once created, you can start configuring rights.

Rights configuration

Now you configure jacl2db with its dedicated commands. They are prefixed by acl2:, acl2group: or acl2user:.

In the following examples, with take "myapp" as the name of the application. Change it of course by the name of your application.

Note that you have a module, jacl2db_admin, which allow you to do everything described below with an interface, except the creation of roles.

Roles creation

In jAcl2 rights, you define a role or a possible action on some data.

Imagine a CMS where you want to define rights about articles. You could define roles for some actions like reading, listing, creating, deleting, updating.

Concretely, you would define these roles:

  • "cms.articles.read",
  • "cms.articles.list",
  • "cms.articles.create",
  • "cms.articles.delete",
  • "cms.articles.update"

Note that all roles names here begin with a prefix, allowing to identify precisely what about it is. Using only "read" is not really explicit and may cause conflicts with roles defined for some modules. So in the role name, always add some words indicating what it is about precisely. Your code is then more readable.

Let's start by listing already existing roles:


php console.php acl2:roles-list

You should have an empty list:


+-------------------+-------+--------------------------------------+
| Role Group        | id    | label key                            |
+-------------------+-------+--------------------------------------+

A role record is a pair of an identifier and a label key. Label keys should be existing locale key identifiers.

Let's create our roles:


php console.php acl2:role-create "cms.articles.create" "cms~acl2.articles.create"
php console.php acl2:role-create "cms.articles.update" "cms~acl2.articles.update"
php console.php acl2:role-create "cms.articles.delete" "cms~acl2.articles.delete"
php console.php acl2:role-create "cms.articles.list" "cms~acl2.articles.list"
php console.php acl2:role-create "cms.articles.read" "cms~acl2.articles.read"

If you don't use a module allowing to manage rights with jAcl2 (like jacl2db_admin) then the locale key selector is not required. Just put any string of yours.

If the command fails, you have an error message, else the output is empty.

Now list again the roles:


$ php console.php acl2:roles-list
+---------------+---------------------+--------------------------+
| Role Group    | id                  | label key                |
+---------------+---------------------+--------------------------+
|               | cms.articles.create | cms~acl2.articles.create |
|               | cms.articles.delete | cms~acl2.articles.delete |
|               | cms.articles.list   | cms~acl2.articles.list   |
|               | cms.articles.read   | cms~acl2.articles.read   |
|               | cms.articles.update | cms~acl2.articles.update |
+---------------+---------------------+--------------------------+

You can delete a role with the following command:


$ php console.php acl2:role-delete  <role name>

User group creation

A jAcl2.db right is a combination of a role and a user group. So you have to create user groups. Use the acl2group: commmands type.

Let's create a writers group for our users. You should indicate an key and optionally a label.


$ php console.php acl2group:create "writers" "Writers"

Let's create a second group and make it the default one with --default. A default group is a group where every new user will be added to.


$ php console.php acl2group:create --default  "readers" "Readers"

You can now list your groups with acl2group:list:


$ php console.php acl2group:list
+---------+---------+---------+
| Id      | label   | default |
+---------+---------+---------+
| readers | Readers | yes     |
| writers | Writers |         |
+---------+---------+---------+

You can switch the "default" group with the acl2group:default command:


$ php console.php acl2group:default readers
# or
$ php console.php acl2group:default --no-default readers

You can change a group name with acl2group:name:


$ php console.php acl2group:name writers "Authors"

Or delete a group with acl2group:delete (it doesn't delete users):


$ php console.php acl2group:delete writers

Managing users into groups

In groups, you should add users. To add a user, you should declare him:


$ php console.php acl2user:register  laurent

Note that it doesn't create the user into jAuth, just in jAcl2. A private group is created.

Then you can add him to a group. You should use the command acl2user:addgroup bye indicating the group name and the user.


$ php console.php acl2user:addgroup readers laurent

To remove a user from a group:


$ php console.php acl2user:removegroup laurent readers

To see the list of users of a group:


$ php console.php acl2user:list readers

To see the list of all users:


$ php console.php acl2user:list

Rights creation

You have every needed elements to create a right. Let's go and execute some acl2: commands.

You want to add readers the right to read and list articles. Let's associate roles cms.articles.list and cms.articles.read to the readers group:


$ php console.php acl2:add readers "cms.articles.list"
$ php console.php acl2:add readers "cms.articles.read"

Check rights list with cl2:list command:


$ php console.php acl2:list
+----------+------------+-------------------+----------+
| Group id | Group name | Role              | Resource |
+----------+------------+-------------------+----------+
| readers  | Readers    | cms.articles.list | -        |
| readers  | Readers    | cms.articles.read | -        |
+----------+------------+-------------------+----------+

The value - for a resource means "no resource". So the indicated right is a right that is applied on any resource.

Now, you want to deal with writers and give them all rights on cms.articles.


$ php console.php acl2:add writers "cms.articles.list"
$ php console.php acl2:add writers "cms.articles.read"
$ php console.php acl2:add writers "cms.articles.create"
$ php console.php acl2:add writers "cms.articles.delete"
$ php console.php acl2:add writers "cms.articles.update"

Again, let's list all rights:


$ php console.php acl2:list
+----------+------------+---------------------+----------+
| Group id | Group name | Role                | Resource |
+----------+------------+---------------------+----------+
| readers  | Readers    | cms.articles.list   | -        |
| readers  | Readers    | cms.articles.read   | -        |
| writers  | Writers    | cms.articles.create | -        |
| writers  | Writers    | cms.articles.delete | -        |
| writers  | Writers    | cms.articles.list   | -        |
| writers  | Writers    | cms.articles.read   | -        |
| writers  | Writers    | cms.articles.update | -        |
+----------+------------+---------------------+----------+

However in your CMS you have an "advices" article which you want your readers to edit. You should add the right to update this specific article to readers group. Let's create a right on the resource "advices" with acl2:add command:


$ php console.php acl2:add readers "cms.articles.update" "advices"

checking of rights list:


$ php console.php acl2:list
+----------+------------+---------------------+----------+
| Group id | Group name | Role                | Resource |
+----------+------------+---------------------+----------+
| readers  | Readers    | cms.articles.list   | -        |
| readers  | Readers    | cms.articles.read   | -        |
| readers  | Readers    | cms.articles.update | advices  |
| writers  | Writers    | cms.articles.create | -        |
| writers  | Writers    | cms.articles.delete | -        |
| writers  | Writers    | cms.articles.list   | -        |
| writers  | Writers    | cms.articles.read   | -        |
| writers  | Writers    | cms.articles.update | -        |
+----------+------------+---------------------+----------+

You can also remove a right with acl2:remove, by passing a user group and a role similarly to acl2:add (and optionally a resource if one is involved).

Say you change your mind about the "advices" article, because there is too much crap ;-):


$ php console.php acl2:remove readers "cms.articles.update" "advices"

Once all rights are injected, your application is able to work following your rights rules.

You can change rights with a user interface like the one provided by the jacl2db_admin module.