module-acl-assert.xml #1

<!DOCTYPE section
[
    <!ENTITY % xinclude SYSTEM "../../en/xinclude.mod">
    %xinclude;

    <!-- Add translated specific definitions and snippets -->
    <!ENTITY % language-snippets SYSTEM "../standalone/language-snippets.xml">
    %language-snippets;

    <!-- Fallback to English definitions and snippets (in case of missing translation) -->
    <!ENTITY % language-snippets.default SYSTEM "../../en/standalone/language-snippets.xml">
    %language-snippets.default;
]>
<section id="modules.acl-assert">
    <title>Controlling Access with ACLs and Asserts</title>

    <para>
        <emphasis>Access Control Lists</emphasis> (<acronym>ACL</acronym>s) define
        <emphasis>resources</emphasis>, which are objects for which access is controlled, and
        <emphasis>privileges</emphasis>, which are actions that can be taken on a given resource.
        Once these are defined, <emphasis>roles</emphasis> are assigned privileges to control
        access. To determine whether a role has permission to access a resource/privilege, you query
        the <acronym>ACL</acronym>. <acronym>ACL</acronym>s are almost always defined by the
        <link linkend="modules.config.acl">module.ini configuration file</link>.
    </para>

    <section id="modules.acl-assert.asserts">
        <title>Asserts</title>

        <para>
            An <emphasis>assert</emphasis> helps with querying an <acronym>ACL</acronym> when the
            permission required to access a resource depends on additional factors, such as a
            resource that is only accessible during certain hours of the day. Asserts are rarely
            required. To define an assert, create a class that is named according to the privilege
            being checked. For asserts that validate a privilege to perform an action, precede the
            name with "Can", for example CanEdit or CanDelete. For asserts that test the current
            state, precede the name with "Is", for example <emphasis>IsOwner</emphasis> or
            <emphasis>IsThursday</emphasis>.
        </para>

        <para>
            Assert classes must be located in the module folder, using the following structure:
        </para>

<programlisting language="text">
acls/
   asserts/
</programlisting>

        <para>
            Here is the skeleton of an assert <emphasis>CanFoo</emphasis> for the
            <classname>Bar</classname> module:
        </para>

<programlisting language="php">
&lt;?php
/**
 * Assert description
 *
 * @copyright   copyright info.
 * @license     license info.
 * @version     version info.
 */
class Bar_Acl_Assert_CanFoo implements Zend_Acl_Assert_Interface
{
    /**
     * Checks if the active user can 'foo' the given content resource.
     *
     * @param  Zend_Acl                    $acl         the acl instance
     * @param  Zend_Acl_Role_Interface     $role        the role to check access for
     * @param  Zend_Acl_Resource_Interface $resource    the resource
     * @param  string                      $privilege   the privilege
     * @return boolean  true if the given role can 'foo' the given resource,
     *                  false if not allowed
     */
    public function assert(
        Zend_Acl $acl,
        Zend_Acl_Role_Interface $role = null,
        Zend_Acl_Resource_Interface $resource = null,
        $privilege = null)
    {
    }
}
</programlisting>

        <para>
            For details, refer to the <ulink url="http://framework.zend.com/manual/1.11/en/zend.acl.advanced.html">Zend
            Framework documentation</ulink>.
        </para>
    </section>
</section>
<!--
vim:se ts=4 sw=4 et:
-->