documentation/manual/en/module_specs/Zend_Acl-Refining.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.acl.refining">
   4     <title>Refining Access Controls</title>
   5
   6     <sect2 id="zend.acl.refining.precise">
   7         <title>Precise Access Controls</title>
   8
   9         <para>
  10             The basic <acronym>ACL</acronym> as defined in the
  11             <link linkend="zend.acl.introduction">previous section</link> shows how various
  12             privileges may be allowed upon the entire <acronym>ACL</acronym> (all resources). In
  13             practice, however, access controls tend to have exceptions and varying degrees of
  14             complexity. <classname>Zend_Acl</classname> allows to you accomplish these refinements
  15             in a straightforward and flexible manner.
  16         </para>
  17
  18         <para>
  19             For the example <acronym>CMS</acronym>, it has been determined that whilst the 'staff'
  20             group covers the needs of the vast majority of users, there is a need for a new
  21             'marketing' group that requires access to the newsletter and latest news in the
  22             <acronym>CMS</acronym>. The group is fairly self-sufficient and will have the ability
  23             to publish and archive both newsletters and the latest news.
  24         </para>
  25
  26         <para>
  27             In addition, it has also been requested that the 'staff' group be allowed to view news
  28             stories but not to revise the latest news. Finally, it should be impossible for anyone
  29             (administrators included) to archive any 'announcement' news stories since they only
  30             have a lifespan of 1-2 days.
  31         </para>
  32
  33         <para>
  34             First we revise the role registry to reflect these changes. We have determined that the
  35             'marketing' group has the same basic permissions as 'staff', so we define 'marketing'
  36             in such a way that it inherits permissions from 'staff':
  37         </para>
  38
  39         <programlisting language="php"><![CDATA[
  40 // The new marketing group inherits permissions from staff
  41 $acl->addRole(new Zend_Acl_Role('marketing'), 'staff');
  42 ]]></programlisting>
  43
  44         <para>
  45             Next, note that the above access controls refer to specific resources (e.g.,
  46             "newsletter", "latest news", "announcement news"). Now we add these resources:
  47         </para>
  48
  49         <programlisting language="php"><![CDATA[
  50 // Create Resources for the rules
  51
  52 // newsletter
  53 $acl->addResource(new Zend_Acl_Resource('newsletter'));
  54
  55 // news
  56 $acl->addResource(new Zend_Acl_Resource('news'));
  57
  58 // latest news
  59 $acl->addResource(new Zend_Acl_Resource('latest'), 'news');
  60
  61 // announcement news
  62 $acl->addResource(new Zend_Acl_Resource('announcement'), 'news');
  63 ]]></programlisting>
  64
  65         <para>
  66             Then it is simply a matter of defining these more specific rules on the target areas of
  67             the <acronym>ACL</acronym>:
  68         </para>
  69
  70         <programlisting language="php"><![CDATA[
  71 // Marketing must be able to publish and archive newsletters and the
  72 // latest news
  73 $acl->allow('marketing',
  74             array('newsletter', 'latest'),
  75             array('publish', 'archive'));
  76
  77 // Staff (and marketing, by inheritance), are denied permission to
  78 // revise the latest news
  79 $acl->deny('staff', 'latest', 'revise');
  80
  81 // Everyone (including administrators) are denied permission to
  82 // archive news announcements
  83 $acl->deny(null, 'announcement', 'archive');
  84 ]]></programlisting>
  85
  86         <para>
  87             We can now query the <acronym>ACL</acronym> with respect to the latest changes:
  88         </para>
  89
  90         <programlisting language="php"><![CDATA[
  91 echo $acl->isAllowed('staff', 'newsletter', 'publish') ?
  92      "allowed" : "denied";
  93 // denied
  94
  95 echo $acl->isAllowed('marketing', 'newsletter', 'publish') ?
  96      "allowed" : "denied";
  97 // allowed
  98
  99 echo $acl->isAllowed('staff', 'latest', 'publish') ?
 100      "allowed" : "denied";
 101 // denied
 102
 103 echo $acl->isAllowed('marketing', 'latest', 'publish') ?
 104      "allowed" : "denied";
 105 // allowed
 106
 107 echo $acl->isAllowed('marketing', 'latest', 'archive') ?
 108      "allowed" : "denied";
 109 // allowed
 110
 111 echo $acl->isAllowed('marketing', 'latest', 'revise') ?
 112      "allowed" : "denied";
 113 // denied
 114
 115 echo $acl->isAllowed('editor', 'announcement', 'archive') ?
 116      "allowed" : "denied";
 117 // denied
 118
 119 echo $acl->isAllowed('administrator', 'announcement', 'archive') ?
 120      "allowed" : "denied";
 121 // denied
 122 ]]></programlisting>
 123     </sect2>
 124
 125     <sect2 id="zend.acl.refining.removing">
 126         <title>Removing Access Controls</title>
 127
 128         <para>
 129             To remove one or more access rules from the <acronym>ACL</acronym>, simply use the
 130             available <methodname>removeAllow()</methodname> or
 131             <methodname>removeDeny()</methodname> methods. As with <methodname>allow()</methodname>
 132             and <methodname>deny()</methodname>, you may provide a <constant>NULL</constant> value
 133             to indicate application to all roles, resources, and/or privileges:
 134         </para>
 135
 136         <programlisting language="php"><![CDATA[
 137 // Remove the denial of revising latest news to staff (and marketing,
 138 // by inheritance)
 139 $acl->removeDeny('staff', 'latest', 'revise');
 140
 141 echo $acl->isAllowed('marketing', 'latest', 'revise') ?
 142      "allowed" : "denied";
 143 // allowed
 144
 145 // Remove the allowance of publishing and archiving newsletters to
 146 // marketing
 147 $acl->removeAllow('marketing',
 148                   'newsletter',
 149                   array('publish', 'archive'));
 150
 151 echo $acl->isAllowed('marketing', 'newsletter', 'publish') ?
 152      "allowed" : "denied";
 153 // denied
 154
 155 echo $acl->isAllowed('marketing', 'newsletter', 'archive') ?
 156      "allowed" : "denied";
 157 // denied
 158 ]]></programlisting>
 159
 160         <para>
 161             Privileges may be modified incrementally as indicated above, but a
 162             <constant>NULL</constant> value for the privileges overrides such incremental changes:
 163         </para>
 164
 165         <programlisting language="php"><![CDATA[
 166 // Allow marketing all permissions upon the latest news
 167 $acl->allow('marketing', 'latest');
 168
 169 echo $acl->isAllowed('marketing', 'latest', 'publish') ?
 170      "allowed" : "denied";
 171 // allowed
 172
 173 echo $acl->isAllowed('marketing', 'latest', 'archive') ?
 174      "allowed" : "denied";
 175 // allowed
 176
 177 echo $acl->isAllowed('marketing', 'latest', 'anything') ?
 178      "allowed" : "denied";
 179 // allowed
 180 ]]></programlisting>
 181     </sect2>
 182 </sect1>
 183 <!--
 184 vim:se ts=4 sw=4 et:
 185 -->