Use sessions and delegate classes to define permissions at the record and field level.
Xataface 0.6 adds a new, fine-grained permissions model and support for user authentication using your own database tables. This section includes a brief overview of the permissions framework and a small example of how you might use permissions in the FacultyOfWidgetry application.
Roles and Permissions
Before we jump into an example it is important to understand a couple of definitions and concepts about Xataface's permissions model. Every possible action in Xataface has an associated permission to indicate whether the current user has permission to perform the action. Some examples of permissions include:
Before allowing the user to perform an action, Xataface checks the permissions to see if the user has the appropriate permissions. You can override the default permissions by defining a method called 'getPermissions()' in your delegate classes (more on that below).
There could be 50 or more permissions associated with an application, so it quickly becomes unfeasible to have configure each user's access on a permission-by-permission basis. Roles provide a means of grouping permissions together into logical sets so that each user can be assigned a role, which has a set of permissions already associated with it.
The concept of a Role is not new by any means. We use roles on a daily basis to simplify things. Consider the example of a sports car. There are a number of functions that can be performed on a sports car:
We would probably have permissions 'drive','ride','wash', and 'fix' associated with our sports car, then. The roles, in this example, might be:
The owner role should be able to do everything except for fix the car. The mechanic role should be able to fix the car, but not drive the car. The friend role should be able to ride in the car and wash the car, but not drive or fix it. And the thief should not be permitted to perform any of the functions.
In the internet world, we might use roles such as "Administrator", "Anonymous", or "Member", where the administrator would have all permissions, the "Member" would be able to leave comments, and the "Anonymous" user would have no access. Later, we'll find out how to create your own roles and permissions, but Xataface includes some built-in roles to handle the most frequently-used cases. Some of Xataface's roles are as follows:
The following diagram shows the relationship between Xataface's built-in roles and permissions (as of June 29, 2006 - subject to change):
Learning by example
Now consider the familiar example of the Faculty of Widgetry site. Suppose we add the following requirements:
Now that we have defined our requirements, let's look at how to implement this using PHP and Xataface. We will be performing the following modifications to our system:
Adding the Users table:
The Users table doesn't need to store very much. Only the user names, passwords, and user role. The user role is optional but it will allow us to limit actions on a per-user basis. In our system we will use the following roles:
. This is just one way to implement permissions. There are many ways that you can do it.
The SQL to create this table would be as follows:
CREATE TABLE `Users` (
The reason we have a UserID field in addition to a UserName field is so that we can change the UserName without destroying relationships. (It is important to note that you can use any table to store your user information, as long as it has a field for the user name and password used to log in).
Setting up authentication
Now that we have a table to store our users, we can turn on authentication for our application. Setting up authentication is a two-step process:
Testing our application
In order to test our application, we will add a couple of users to the Users table with the available roles. The SQL for these additions is as follows (though you can use your favorite SQL tool:
INSERT INTO `Users` (`UserName`,`Password`,`Role`)
Now we load up the application in a web browser:
When we log in as 'readOnlyUser' we see:
Now it looks basically the same as before we added authentication, except there is now a "logout" link in the upper right corner, and a link to view/edit the profile of the currently logged-in user (by way of the "My Profile" link in the upper right). Notice, that the "New record", and "Delete record" options are no longer available in the "actions" menu. Only "show all" remains. This is because the current user (readOnlyUser) only has READ ONLY permissions which does not include creating new records or deleting records. This limitation becomes even more evident when we click on the "details" tab to see record details:
Notice that the "Edit" tab is no longer visible - only the "View" tab.
If we log out and then log back in as 'adminUser', the edit tab re-appears along with options to create new records and delete records.
Source files download
(Note: These PHP sources are out of date, and include deprecated code such as short open tags. You will need to change all PHP open tags from "<?" to "<?php" in order for these samples to work in most modern PHP installations).
And from here...