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

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.

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

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

Concretely, you would define these rights:

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

Note that all right 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 rights defined for some modules. So in the right name, always add some words indicating what it is about precisely. Your code is then more readable.

Let's start by listing already existing rights:

php console.php acl2:rights-list

You should have an empty list:

+-------------------+----------+--------------------------------------+
| Rights Group      | Right id | label key                            |
+-------------------+----------+--------------------------------------+

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

Let's create our rights:

php console.php acl2:right-create "cms.articles.create" "cms~acl2.articles.create"
php console.php acl2:right-create "cms.articles.update" "cms~acl2.articles.update"
php console.php acl2:right-create "cms.articles.delete" "cms~acl2.articles.delete"
php console.php acl2:right-create "cms.articles.list" "cms~acl2.articles.list"
php console.php acl2:right-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 rights:

$ php console.php acl2:rights-list
+---------------+---------------------+--------------------------+
| Rights Group  | Right 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 right with the following command:

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

A jAcl2.db right is a combination of a right name 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

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

You have every needed elements to assign 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 rights 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 | Right              | 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 | Right               | 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 | Right               | 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 right name 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.