I wrote a little Developerguide for the use of the ACL-API. Its not professional and open for change. As allways, I'm glad for any feedback.
Developerguide for the use of the ACL-APITable of Content1. What are ACLs
1.1 ACLs
1.2 ACOs
1.3 AROs
1.4 AXOs
1.5 ACLs
1.6 Sections
1.7 Groups
2. ACL-Check
3. Managing Sections and Groups
3.1 Managing Sections
3.1.1 Add
3.1.2 Edit
3.1.3 Delete
3.1.4 Get information
3.2 Managing Groups
3.2.1 Add
3.2.2 Edit
3.2.3 Delete
3.2.4 Get information
4. Managing ACLs
4.1 Add
4.2 Edit
4.3 Delete
4.4 Get
5. Manage Objects
5.1 Add
5.2 Edit
5.3 Delete
5.4 Manage objects and their groups
5.4.1 Add
5.4.2 Delete
5.5 Get
6. Guidelines for naming Objects
7. Porting Add-Ons to the new ACL-system
1. What are ACLs?In short term: ACLs are the restrictions you can place on a user. You can tell if a user can do a special action, like editing or deleting stuff and you can do this very effectively by grouping users and assigning rules to the groups instead of the users. A good explanation of ACLs can be found at the homepage of phpGACL, which is the real API thats behind the Joomla!-ACLs. You can find it on the site and in the downloadable API-package here:
http://phpgacl.sourceforge.net/1.1 ACLsThe ACL is the actual rule. It connects the ARO with the ACO and optionally with the AXO and defines if that combination should be allowed or denied.
1.2 ACOsThe ACO is the
Access
Controlling
Object, which is an action you can assign to an ACL and by that allow this action to be executed by a user.
1.3 AROsThe AROs are
Access
Requesting
Objects, which would be the user in our case. It would be possible to put an Add-On as ARO in here to regulate its rights. If this is necessary I'm not sure...
1.4 AXOsThe AXOs are
Access e
Xtension
Objects, the single content-items in Joomla! These are optional, but allow to create control rules down to a level where you define it for every single content-item.
1.5 SectionsAll 4 groups of objects can be grouped into sections for structuring purposes. Sections can not be a child of another section, they are just to group the objects of the respective object into more administrable parts.
1.7 GroupsTo have as little as possible rules and to not creating a single rule for every user and every action, it is possible to put AROs and AXOs into groups and assign rules to this group. Groups can form a tree and inherit the rules from their parents. When a rule conflicts with a rule of a parentgroup, the rule of the child is the dominant one.
2. ACL-CheckCode:
$acl->acl_check($aco_section_value, $aco_value, $aro_section_value, $aro_value, $axo_section_value=NULL, $axo_value=NULL, $root_aro_group=NULL, $root_axo_group=NULL)
To include the ACL-check into your Add-On, you just have to include the above code and replace the corresponding variables with your data. You wont need $root_aro_group and $root_axo_group and $axo_section_value and $axo_value are optional, too. Normally you would replace $aro_section_value with 'users' and $aro_value with $my->id, which would mean, the current user is the requesting object. When you create another kind of requesting object, like an Add-On, you have to replace 'users' by its respective sectionvalue and $my->id by the corresponding objectvalue.
3. Managing Sections and Groups3.1 Managing Sections3.1.1 AddTo add a section, put this into your code:
Code:
$acl->add_object_section($name, $value, 0, 0, $object_type)
Replace $name with the name for the section. This will be displayed in the ACL-admin-interface. Replace $value with the internal name of the section. This will be the string you have to use as a parameter. Replace $object_type with the kind of object you would like to add (ACL, ACO, ARO, AXO).
3.1.2 EditTo edit a section, put this into your code:
Code:
$acl->edit_object_section($object_section_id, $name, $value, 0, 0, $object_type)
Replace $object_section_id with the nummerical ID of the section you want to edit. Replace the other variables to the new values you want them to have. Be sure to set the $object_type correct (ACL, ACO, ARO, AXO).
3.1.3 DeleteTo delete a section, put this into your code:
Code:
$acl->del_object_section($object_section_id, $object_type, $erase)
Replace $object_section_id with the ID of the section you want to delete. Set the $object_type (ACL, ACO, ARO, AXO). If you want all the objects in the section to be deletet, set $erase to TRUE. ATTENTION: You're not just deleting there logical connection, but the whole ACL-rule!!
3.1.4 Get informationTo get the ID of a section, put this into your code:
Code:
$acl->get_object_section_section_id($name, $value, $object_type)
Put a value in either $name, $value or both and set the object-type. Returnvalue will be the ID or FALSE.
3.2 Managing Groups3.2.1 AddTo add a group, put this into your code:
Code:
$acl->add_group($value, $name, $parent_id, $group_type)
Replace $value with the internal name of the group. Replace $name with the name of the group. This will be shown in the admin-interface. To structure the groups you can build a tree with them. To place the group inside another, you have to set $parent_id to its parent group-ID. Be sure to set the group-type (ARO, AXO).
3.2.2 EditTo edit a group, put this into your code:
Code:
$acl->edit_group($group_id, $value, $name, $parent_id, $group_type)
Replace $group_id with the nummerical ID of the group you want to edit. Replace the other variables to the new values you want them to have. Be sure to set the $group_type correct (ARO, AXO).
3.2.3 DeleteTo delete a group, put this into your code:
Code:
$acl->del_group($group_id, $reparent_children, $group_type)
Replace $group_id with the ID of the group you want to delete. Set the $group_type (ARO, AXO). If you want all the child-groups in the group to be signed over to the parent of the group to be deletet, set $reparent_children to TRUE.
3.2.4 Get informationTo get the children of a group, put this in your code:
Code:
$acl->get_group_children($group_id, $group_type, $recurse)
Replace $group_id with the ID of the group whos children you want. Set the $group_type (ARO, AXO). If you want to get all groups below your parent, set $recurse to 'RECURSE'. Returns an array of child IDs.
To get the ID of a group, put this into your code:
Code:
$acl->get_group_id($value, $name, $group_type)
Put a value in either $name, $value or both and set the object-type (ARO, AXO). Returnvalue will be the ID or FALSE.
To get the ID of the parent of your group, put this into your code:
Code:
$acl->get_group_parent_id($id, $group_type)
Replace $id with the childs ID and set the object-type (ARO, AXO).
To get the data of a group, put this into your code:
Code:
$acl->get_group_data($group_id, $group_type)
Replace $group_id with the ID and set the $group_type (ARO, AXO).
4. Managing ACLs4.1 AddTo add an ACL, put this into your code:
Code:
$acl->add_acl($aco_array, $aro_array, $aro_group_ids, $axo_array, $axo_group_ids, $allow, $enabled, $return_value, $note, $section_value)
The $aco_array, $aro_array and $axo_array are associative arrays of the objects the ACL-rule applies to. Structure:
item={Section Value}, key={Array of Object Values}
i.e. ("
" => ("", "", ""), ...)
The $aro_group_ids and $axo_group_ids are arrays of the groups the ACL-rule applies to.
With $allow you can set, if the rule allows or denys the AROs the access to the AROs and AXOS. With $enabled you can set, if the rule is active or not. Both switches are on when set to 1. With $return_value you can define a special returnvalue. With $note you can add a description to the ACL. Setting $section_value, you can assign the ACL to a section. This is optional and will be set to 'system' if not set.
4.2 Edit
To edit an existing ACL, put this into your code:
Code:
$acl->edit_acl($acl_id, $aco_array, $aro_array, $aro_group_ids, $axo_array, $axo_group_ids, $allow, $enabled, $return_value, $note, $section_value)
For an explanation of the parameters read "4.1 Add". The parameters are named equally. Notice that you have to set $acl_id to the ACL to be edited.
To add objects to an ACL, put this into your code:
Code:
$acl->append_acl($acl_id, $aro_array, $aro_group_ids, $axo_array, $axo_group_ids, $aco_array)
For an explanation of the parameters read "4.1 Add". The parameters are named equally. Notice that you have to set $acl_id to the ACL to be edited.
To delete objects from an ACL, put this into your code:
Code:
$acl->shift_acl($acl_id, $aro_array, $aro_group_ids, $axo_array, $axo_group_ids, $aco_array)
For an explanation of the parameters read "4.1 Add". The parameters are named equally. Notice that you have to set $acl_id to the ACL to be edited.
To check if the ACL is conflicting with an older rule, put this into your code:
Code:
$acl->is_conflicting_acl($aco_array, $aro_array, $aro_group_ids, $axo_array, $axo_group_ids, $ignore_acl_ids)
The $aco_array, $aro_array and $axo_array are associative arrays of the objects the ACL-rule applies to. Structure:
item={Section Value}, key={Array of Object Values}
i.e. ["" => ["", "", ""], ...]
The $aro_group_ids and $axo_group_ids are arrays of the groups the ACL-rule applies to.
With $ignore_acl_ids you can define a number of ACLs to be ignored in the search process. The array consists of the ACLs IDs.
4.3 Delete
To delete an ACL, put this into your code:
Code:
$acl->del_acl($acl_id)
Replace $acl_id with the ID of the ACL to be deleted.
4.4 Get
To get the data of an ACL, put this into your code:
Code:
$acl->get_acl($acl_id)
Replace $acl_id with the ID of the ACL who's data you want.
The returnvalue is an associative array with the following items:
- 'aco' => Associative array, item={Section Value}, key={Array of Object Values} i.e. ["" => ["", "", ""], ...]
- 'aro' => Associative array, item={Section Value}, key={Array of Object Values} i.e. ["" => ["", "", ""], ...]
- 'axo' => Associative array, item={Section Value}, key={Array of Object Values} i.e. ["" => ["", "", ""], ...]
- 'aro_groups' => Array of Group IDs
- 'axo_groups' => Array of Group IDs
- 'acl_id' => int ACL ID #
- 'allow' => int Allow flag
- 'enabled' => int Enabled flag
- 'return_value' => string Return Value
- 'note' => string Note
To find one or more ACLs with specific values, put this into your code:
Code:
$acl->search_acl($aco_section_value, $aco_value, $aro_section_value, $aro_value, $aro_group_name, $axo_section_value, $axo_value, $axo_group_name, $return_value)
The returnvalue is an array of ACL-group IDs.
5. Manage Objects
5.1 Add
To add an object, put this into your code:
Code:
$acl->add_object($section_value, $name, $value, 0, 0, $object_type)
Fill in the values for the different parameters. Be sure to set the object-type (ARO, ACO, AXO). $section_value is the section the new object will be attached to. Returnvalue is the new object-ID.
5.2 Edit
To edit an object, put this into your code:
Code:
$acl->edit_object($object_id, $section_value, $name, $value, $order, $hidden, $object_type)
Fill in the values for the different parameters. Be sure to set the object-type (ARO, ACO, AXO). $section_value is the new section the object will be attached to.
5.3 Delete
To delete an object, put this into your code:
Code:
$acl->del_object($object_id, $object_type, $erase)
Replace $object_id with the objects ID and set the object-type (ARO, ACO, AXO). By setting $erase to 'TRUE', all referencing objects get erased, too. Leaves them alone otherwise.
5.4 Manage objects and their groups
5.4.1 Add
To add an object to a group, put this into your code:
Code:
$acl->add_group_object($group_id, $object_section_value, $object_value, $group_type)
Replace the parameters with your values. Notice that only AROs and AXOs can be put into groups.
5.4.2 Delete
To delete an object, put this into your code:
Code:
$acl->del_group_object($group_id, $object_section_value, $object_value, $group_type)
Fill in your values for the parameters. Returnvalue is True when successfull.
5.5 Get
To get the data of all objects, put this into your code:
Code:
$acl->get_object($section_value, 1, $object_type)
You can narrow your search down by selecting a section. The return is an ADORecordSet with object ID only selected. Be sure to set the object_type (ARO, ACO, AXO).
To get all objects not assigned to a group, put this into your code:
Code:
$acl->get_ungrouped_objects(1, $object_type)
Object-type can be ARO and AXO. Returnvalue is an array of group-IDs
To get the data of all objects, put this into your code:
Code:
$acl->get_objects($section_value, 1, $object_type)
You can narrow your search down by selecting a section. The return is an associative array with the following structure:
- i.e. Associative array, item={Section Value}, key={Array of Object Values} i.e. ["" => ["", "", ""], ...]
This array is suitable for $acl->add_acl and $acl->is_conflicting_acl. You can narrow your search down by selecting a section. Be sure to set the object-type (ARO, ACO, AXO).
To get the data of a single object, put this into your code:
Code:
$acl->get_object_data($object_id, $object_type)
The return is a 2-dimensional array of rows with columns ( section_value, value, order_value, name, hidden).
To get the ID of an object, put this into your code:
Code:
$acl->get_object_id($section_value, $value, $object_type)
Be sure to set the object-type (ARO, ACO, AXO).
To get the section-value the object is in, put this into your code:
Code:
$acl->get_object_section_value($object_id, $object_type)
Be sure to set the object-type (ARO, ACO, AXO).
To get all groups the object is part of, put this into your code:
Code:
$acl->get_object_groups($object_id, $object_type, $option)
Be sure to set the object-type (ARO, AXO). If $option is set to 'RECURSE' it will get all ancestor groups. Default is only parent. Return is an array of group-IDs.
6. Guidelines for naming Objects
To preserve a good structure in the ACL-tree and make it readable for human beings, a few rules should be followed regarding naming the different objects.
ACO-sections should have as a value a three character identifier of their kind of Add-On i.e. 'com_*' or 'mod_*' and as name a describing word. See in the admin-interface for an example.
ACO-objects can have any kind of name and value you like, just remind, that later the user probably wants to administer the rights and has to understand what this ACO represents.
ARO-sections are something special. In the section 'users' only users are supposed to be enlisted. If you want an Add-On such as a mambot or component to be registered as an ARO, put them in their respective section ('mambot', 'component').
AROs can have any kind of name and value you like, just remind, that later the user probably wants to administer the rights and has to understand what this ARO represents.
If you need to create a new group for your components, you either create it inside of 'Public Backend' or 'Public Frontend' or create a new group outside of 'USERS'
AXO-sections should represent their content. If you have content, that's created by your Add-On, create a section with a value like 'content_add_on' and a name like 'Content - add_on'.
AXOs can have any kind of name and value you like, just remind, that later the user probably wants to administer the rights and has to understand what this AXO represents.
AXO-groups should represent the section/categorie-structure of Joomla. However, you can create a group, thats outside of 'Content'.
7. Porting Add-Ons to the new ACL-system
Porting existing Add-Ons to the new ACL-system is fairly easy. When your Add-On till now had to add its ACL-rules every time it was triggered, you now have to make this only once in the installation. How this will be done, if the XML-scheme for installation-files for Joomla will be extended, is at the moment undecided.
when your Add-On calls the function $acl->acl_check, you have to notice only one thing thats changed to the old system. In the old system the rights of a user were defined by his user-group, now you call this function directly for this user with his ID. Normally replacing the '$my->usertype' by '$my->id' will do the trick.
Login
Register
Rules
FAQ
The team
). So I think that #__users table doesn't need a change.
, but which is site-admin editable 
in the backend independently for each ACL definition (just provide a simple way for 3PD and core components to define those SEPARATELY from other settings (so these definitions themselves can be protected by ACL for access by security-officer-admins only 
).
