By adding this module into the 'isa' configuration key for your SPOPS class, you implement a mostly transparent per-object security system. This security system relies on a few things being implemented:

A SPOPS class implementing users

A SPOPS class implementing groups

A SPOPS class implementing security objects

Easy, eh? Fortunately, SPOPS comes with all three, although you are free to modify them as you see fit. (As of version 0.42, see the 'eg/My' directory in the source distribution for the sample classes.)

Most people interested in security should not be reading the docs for this class. Instead, look at SPOPS::Manual::Security which offers a broad view of security as well as how to use, implement and extend it.

The methods that this class implements can be used by any SPOPS class. The variable $item below refers to the fact that you can either do an object method call or a class method call. If you do a class method call, you must pass in the ID of the object for which you want to get or set security.

However, you may also implement security on the class level as well. For instance, if your application uses classes to implement modules within an application, you might wish to restrict the module by security very similar to the security implemented for individual objects. In this case, you would have a class name and no object ID ($object_id) value. (See SPOPS::Manual::Security for more information.)

The method check_security() returns a code corresponding to the LEVEL constants exported from this package. This code tells you what permissions the logged in (or passed in) user has. You can pass user and group parameters to check security for other items as well.

Note that you can check security for multiple groups but only one user at a time. Passing an arrayref of user objects for the 'user' parameter will result in the first user object being checked and the remainder discarded. This is probably not what you want.

Examples:

# Find the permission for the currently logged-in user for $item
$item->check_security();
# Get the security for this $item for a particuar
# user; note that this *does* find the groups this
# user belongs to and checks those as well
$item->check_security({ user => $user });
# Find the security for this item for either of the
# groups specified
$item->check_security({ group => [ $group, $group ] });

Returns a hashref of security information about the particular class or object. The keys of the hashref are the constants, SEC_SCOPE_WORLD, SEC_SCOPE_GROUP and SEC_SCOPE_USER. The value corresponding to the SEC_SCOPE_WORLD key is simply the WORLD permission for the object or class. Similarly, the value of SEC_SCOPE_USER is the permission for the user specified. The SEC_SCOPE_GROUP key has as its value a hashref with the IDs of the group as keys. (Examples below)

Note that if the user specified does not have permissions for the class/object, then its entry is blank.

The parameters correspond to check_security. The default is to retrieve the security for the currently logged-in user and groups (plus WORLD), but you can restrict the output if necessary.

Note that the WORLD key is always set, no matter how much you restrict the user/groups.

Finally: this will not be on the test, since you will probably not need to use this very often unless you are subclassing this class to create your own custom security checks. The check_security() and set_security() methods are likely the only interfaces you need with security whether it be object or class-based. The get_security() method is used primarily for internal purposes, but you might also need it if you are writing security administration tools.

This module exports nothing by default. You can import specific tags that refer to the scope and level, or you can import groups of them.

Note that you should always use these tags. They may seem unwieldly, but they make your program easier to read and allow us to modify the values for these behind the scenes without you modifying any of your code. If you use the values directly, you will get what is coming to you.