Source for file Permission.php

Documentation is available at Permission.php

1: <?php
2:
3: /**
4: * Nette Framework
5: *
6: * Copyright (c) 2004, 2009 David Grudl (http://davidgrudl.com)
7: *
8: * This source file is subject to the "Nette license" that is bundled
9: * with this package in the file license.txt.
10: *
11: * For more information please see https://nette.org
12: *
13: * @copyright Copyright (c) 2004, 2009 David Grudl
14: * @license https://nette.org/license Nette license
15: * @link https://nette.org
16: * @category Nette
17: * @package Nette\Security
18: * @version $Id$
19: */
20:
21:
22:
23: require_once dirname(__FILE__) . '/../Security/IAuthorizator.php';
24:
25: require_once dirname(__FILE__) . '/../Object.php';
26:
27:
28:
29: /**
30: * Access control list (ACL) functionality and privileges management.
31: *
32: * This solution is mostly based on Zend_Acl (c) Zend Technologies USA Inc. (http://www.zend.com), new BSD license
33: *
34: * @author David Grudl
35: * @copyright Copyright (c) 2005, 2007 Zend Technologies USA Inc.
36: * @copyright Copyright (c) 2004, 2009 David Grudl
37: * @package Nette\Security
38: */
39: class Permission extends Object implements IAuthorizator
40: {
41: /** @var array Role storage */
42: private $roles = array();
43:
44: /** @var array Resource storage */
45: private $resources = array();
46:
47: /** @var array Access Control List rules; whitelist (deny everything to all) by default */
48: private $rules = array(
49: 'allResources' => array(
50: 'allRoles' => array(
51: 'allPrivileges' => array(
52: 'type' => self::DENY,
53: 'assert' => NULL,
54: ),
55: 'byPrivilege' => array(),
56: ),
57: 'byRole' => array(),
58: ),
59: 'byResource' => array(),
60: );
61:
62: /** @var mixed */
63: private $queriedRole, $queriedResource;
64:
65:
66:
67: /********************* roles ****************d*g**/
68:
69:
70: /**
71: * Adds a Role to the list.
72: *
73: * The $parents parameter may be a Role identifier (or array of identifiers)
74: * to indicate the Roles from which the newly added Role will directly inherit.
75: *
76: * In order to resolve potential ambiguities with conflicting rules inherited
77: * from different parents, the most recently added parent takes precedence over
78: * parents that were previously added. In other words, the first parent added
79: * will have the least priority, and the last parent added will have the
80: * highest priority.
81: *
82: * @param string
83: * @param string|array
84: * @throws InvalidArgumentException
85: * @throws InvalidStateException
86: * @return Permission provides a fluent interface
87: */
88: public function addRole($role, $parents = NULL)
89: {
90: $this->checkRole($role, FALSE);
91:
92: if (isset($this->roles[$role])) {
93: throw new InvalidStateException("Role '$role' already exists in the list.");
94: }
95:
96: $roleParents = array();
97:
98: if ($parents !== NULL) {
99: if (!is_array($parents)) {
100: $parents = array($parents);
101: }
102:
103: foreach ($parents as $parent) {
104: $this->checkRole($parent);
105: $roleParents[$parent] = TRUE;
106: $this->roles[$parent]['children'][$role] = TRUE;
107: }
108: }
109:
110: $this->roles[$role] = array(
111: 'parents' => $roleParents,
112: 'children' => array(),
113: );
114:
115: return $this;
116: }
117:
118:
119:
120: /**
121: * Returns TRUE if the Role exists in the list.
122: * @param string
123: * @return bool
124: */
125: public function hasRole($role)
126: {
127: $this->checkRole($role, FALSE);
128: return isset($this->roles[$role]);
129: }
130:
131:
132:
133: /**
134: * Checks whether Role is valid and exists in the list.
135: * @param string
136: * @param bool
137: * @throws InvalidStateException
138: * @return void
139: */
140: private function checkRole($role, $need = TRUE)
141: {
142: if (!is_string($role) || $role === '') {
143: throw new InvalidArgumentException("Role must be a non-empty string.");
144:
145: } elseif ($need && !isset($this->roles[$role])) {
146: throw new InvalidStateException("Role '$role' does not exist.");
147: }
148: }
149:
150:
151:
152: /**
153: * Returns an array of an existing Role's parents.
154: *
155: * The parent Roles are ordered in this array by ascending priority.
156: * The highest priority parent Role, last in the array, corresponds with
157: * the parent Role most recently added.
158: *
159: * If the Role does not have any parents, then an empty array is returned.
160: *
161: * @param string
162: * @return array
163: */
164: public function getRoleParents($role)
165: {
166: $this->checkRole($role);
167: return array_keys($this->roles[$role]['parents']);
168: }
169:
170:
171:
172: /**
173: * Returns TRUE if $role inherits from $inherit.
174: *
175: * If $onlyParents is TRUE, then $role must inherit directly from
176: * $inherit in order to return TRUE. By default, this method looks
177: * through the entire inheritance DAG to determine whether $role
178: * inherits from $inherit through its ancestor Roles.
179: *
180: * @param string
181: * @param string
182: * @param boolean
183: * @throws InvalidStateException
184: * @return bool
185: */
186: public function roleInheritsFrom($role, $inherit, $onlyParents = FALSE)
187: {
188: $this->checkRole($role);
189: $this->checkRole($inherit);
190:
191: $inherits = isset($this->roles[$role]['parents'][$inherit]);
192:
193: if ($inherits || $onlyParents) {
194: return $inherits;
195: }
196:
197: foreach ($this->roles[$role]['parents'] as $parent => $foo) {
198: if ($this->roleInheritsFrom($parent, $inherit)) {
199: return TRUE;
200: }
201: }
202:
203: return FALSE;
204: }
205:
206:
207:
208: /**
209: * Removes the Role from the list.
210: *
211: * @param string
212: * @throws InvalidStateException
213: * @return Permission provides a fluent interface
214: */
215: public function removeRole($role)
216: {
217: $this->checkRole($role);
218:
219: foreach ($this->roles[$role]['children'] as $child => $foo)
220: unset($this->roles[$child]['parents'][$role]);
221:
222: foreach ($this->roles[$role]['parents'] as $parent => $foo)
223: unset($this->roles[$parent]['children'][$role]);
224:
225: unset($this->roles[$role]);
226:
227: foreach ($this->rules['allResources']['byRole'] as $roleCurrent => $rules) {
228: if ($role === $roleCurrent) {
229: unset($this->rules['allResources']['byRole'][$roleCurrent]);
230: }
231: }
232:
233: foreach ($this->rules['byResource'] as $resourceCurrent => $visitor) {
234: foreach ($visitor['byRole'] as $roleCurrent => $rules) {
235: if ($role === $roleCurrent) {
236: unset($this->rules['byResource'][$resourceCurrent]['byRole'][$roleCurrent]);
237: }
238: }
239: }
240:
241: return $this;
242: }
243:
244:
245:
246: /**
247: * Removes all Roles from the list.
248: *
249: * @return Permission provides a fluent interface
250: */
251: public function removeAllRoles()
252: {
253: $this->roles = array();
254:
255: foreach ($this->rules['allResources']['byRole'] as $roleCurrent => $rules)
256: unset($this->rules['allResources']['byRole'][$roleCurrent]);
257:
258: foreach ($this->rules['byResource'] as $resourceCurrent => $visitor) {
259: foreach ($visitor['byRole'] as $roleCurrent => $rules) {
260: unset($this->rules['byResource'][$resourceCurrent]['byRole'][$roleCurrent]);
261: }
262: }
263:
264: return $this;
265: }
266:
267:
268:
269: /********************* resources ****************d*g**/
270:
271:
272:
273: /**
274: * Adds a Resource having an identifier unique to the list.
275: *
276: * @param string
277: * @param string
278: * @throws InvalidArgumentException
279: * @throws InvalidStateException
280: * @return Permission provides a fluent interface
281: */
282: public function addResource($resource, $parent = NULL)
283: {
284: $this->checkResource($resource, FALSE);
285:
286: if (isset($this->resources[$resource])) {
287: throw new InvalidStateException("Resource '$resource' already exists in the list.");
288: }
289:
290: if ($parent !== NULL) {
291: $this->checkResource($parent);
292: $this->resources[$parent]['children'][$resource] = TRUE;
293: }
294:
295: $this->resources[$resource] = array(
296: 'parent' => $parent,
297: 'children' => array()
298: );
299:
300: return $this;
301: }
302:
303:
304:
305: /**
306: * Returns TRUE if the Resource exists in the list.
307: * @param string
308: * @return bool
309: */
310: public function hasResource($resource)
311: {
312: $this->checkResource($resource, FALSE);
313: return isset($this->resources[$resource]);
314: }
315:
316:
317:
318: /**
319: * Checks whether Resource is valid and exists in the list.
320: * @param string
321: * @param bool
322: * @throws InvalidStateException
323: * @return void
324: */
325: private function checkResource($resource, $need = TRUE)
326: {
327: if (!is_string($resource) || $resource === '') {
328: throw new InvalidArgumentException("Resource must be a non-empty string.");
329:
330: } elseif ($need && !isset($this->resources[$resource])) {
331: throw new InvalidStateException("Resource '$resource' does not exist.");
332: }
333: }
334:
335:
336:
337: /**
338: * Returns TRUE if $resource inherits from $inherit.
339: *
340: * If $onlyParents is TRUE, then $resource must inherit directly from
341: * $inherit in order to return TRUE. By default, this method looks
342: * through the entire inheritance tree to determine whether $resource
343: * inherits from $inherit through its ancestor Resources.
344: *
345: * @param string
346: * @param string
347: * @param boolean
348: * @throws InvalidStateException
349: * @return bool
350: */
351: public function resourceInheritsFrom($resource, $inherit, $onlyParent = FALSE)
352: {
353: $this->checkResource($resource);
354: $this->checkResource($inherit);
355:
356: if ($this->resources[$resource]['parent'] === NULL) {
357: return FALSE;
358: }
359:
360: $parent = $this->resources[$resource]['parent'];
361: if ($inherit === $parent) {
362: return TRUE;
363:
364: } elseif ($onlyParent) {
365: return FALSE;
366: }
367:
368: while ($this->resources[$parent]['parent'] !== NULL) {
369: $parent = $this->resources[$parent]['parent'];
370: if ($inherit === $parent) {
371: return TRUE;
372: }
373: }
374:
375: return FALSE;
376: }
377:
378:
379:
380: /**
381: * Removes a Resource and all of its children.
382: *
383: * @param string
384: * @throws InvalidStateException
385: * @return Permission provides a fluent interface
386: */
387: public function removeResource($resource)
388: {
389: $this->checkResource($resource);
390:
391: $parent = $this->resources[$resource]['parent'];
392: if ($parent !== NULL) {
393: unset($this->resources[$parent]['children'][$resource]);
394: }
395:
396: $removed = array($resource);
397: foreach ($this->resources[$resource]['children'] as $child => $foo) {
398: $this->removeResource($child);
399: $removed[] = $child;
400: }
401:
402: foreach ($removed as $resourceRemoved) {
403: foreach ($this->rules['byResource'] as $resourceCurrent => $rules) {
404: if ($resourceRemoved === $resourceCurrent) {
405: unset($this->rules['byResource'][$resourceCurrent]);
406: }
407: }
408: }
409:
410: unset($this->resources[$resource]);
411:
412: return $this;
413: }
414:
415:
416:
417: /**
418: * Removes all Resources.
419: *
420: * @return Permission provides a fluent interface
421: */
422: public function removeAllResources()
423: {
424: foreach ($this->resources as $resource => $foo) {
425: foreach ($this->rules['byResource'] as $resourceCurrent => $rules) {
426: if ($resource === $resourceCurrent) {
427: unset($this->rules['byResource'][$resourceCurrent]);
428: }
429: }
430: }
431:
432: $this->resources = array();
433: return $this;
434: }
435:
436:
437:
438: /********************* defining rules ****************d*g**/
439:
440:
441:
442: /**
443: * Adds an "allow" rule to the list. A rule is added that would allow one
444: * or more Roles access to [certain $privileges upon] the specified Resource(s).
445: *
446: * If either $roles or $resources is Permission::ALL, then the rule applies to all Roles or all Resources,
447: * respectively. Both may be Permission::ALL in order to work with the default rule of the ACL.
448: *
449: * The $privileges parameter may be used to further specify that the rule applies only
450: * to certain privileges upon the Resource(s) in question. This may be specified to be a single
451: * privilege with a string, and multiple privileges may be specified as an array of strings.
452: *
453: * If $assertion is provided, then its assert() method must return TRUE in order for
454: * the rule to apply. If $assertion is provided with $roles, $resources, and $privileges all
455: * equal to NULL, then a rule will imply a type of DENY when the rule's assertion fails.
456: *
457: * @param string|array|Permission::ALL roles
458: * @param string|array|Permission::ALL resources
459: * @param string|array|Permission::ALL privileges
460: * @param IPermissionAssertion assertion
461: * @return Permission provides a fluent interface
462: */
463: public function allow($roles = self::ALL, $resources = self::ALL, $privileges = self::ALL, IPermissionAssertion $assertion = NULL)
464: {
465: $this->setRule(TRUE, self::ALLOW, $roles, $resources, $privileges, $assertion);
466: return $this;
467: }
468:
469:
470:
471: /**
472: * Adds a "deny" rule to the list. A rule is added that would deny one
473: * or more Roles access to [certain $privileges upon] the specified Resource(s).
474: *
475: * If either $roles or $resources is Permission::ALL, then the rule applies to all Roles or all Resources,
476: * respectively. Both may be Permission::ALL in order to work with the default rule of the ACL.
477: *
478: * The $privileges parameter may be used to further specify that the rule applies only
479: * to certain privileges upon the Resource(s) in question. This may be specified to be a single
480: * privilege with a string, and multiple privileges may be specified as an array of strings.
481: *
482: * If $assertion is provided, then its assert() method must return TRUE in order for
483: * the rule to apply. If $assertion is provided with $roles, $resources, and $privileges all
484: * equal to NULL, then a rule will imply a type of ALLOW when the rule's assertion fails.
485: *
486: * @param string|array|Permission::ALL roles
487: * @param string|array|Permission::ALL resources
488: * @param string|array|Permission::ALL privileges
489: * @param IPermissionAssertion assertion
490: * @return Permission provides a fluent interface
491: */
492: public function deny($roles = self::ALL, $resources = self::ALL, $privileges = self::ALL, IPermissionAssertion $assertion = NULL)
493: {
494: $this->setRule(TRUE, self::DENY, $roles, $resources, $privileges, $assertion);
495: return $this;
496: }
497:
498:
499:
500: /**
501: * Removes "allow" permissions from the list. The rule is removed only in the context
502: * of the given Roles, Resources, and privileges. Existing rules to which the remove
503: * operation does not apply would remain in the
504: *
505: * @param string|array|Permission::ALL roles
506: * @param string|array|Permission::ALL resources
507: * @param string|array|Permission::ALL privileges
508: * @return Permission provides a fluent interface
509: */
510: public function removeAllow($roles = self::ALL, $resources = self::ALL, $privileges = self::ALL)
511: {
512: $this->setRule(FALSE, self::ALLOW, $roles, $resources, $privileges);
513: return $this;
514: }
515:
516:
517:
518: /**
519: * Removes "deny" restrictions from the list. The rule is removed only in the context
520: * of the given Roles, Resources, and privileges. Existing rules to which the remove
521: * operation does not apply would remain in the
522: *
523: * @param string|array|Permission::ALL roles
524: * @param string|array|Permission::ALL resources
525: * @param string|array|Permission::ALL privileges
526: * @return Permission provides a fluent interface
527: */
528: public function removeDeny($roles = self::ALL, $resources = self::ALL, $privileges = self::ALL)
529: {
530: $this->setRule(FALSE, self::DENY, $roles, $resources, $privileges);
531: return $this;
532: }
533:
534:
535:
536: /**
537: * Performs operations on Access Control List rules.
538: *
539: * @param bool operation add?
540: * @param bool type
541: * @param string|array|Permission::ALL roles
542: * @param string|array|Permission::ALL resources
543: * @param string|array|Permission::ALL privileges
544: * @param IPermissionAssertion assertion
545: * @throws InvalidStateException
546: * @return void
547: */
548: protected function setRule($toAdd, $type, $roles, $resources, $privileges, IPermissionAssertion $assertion = NULL)
549: {
550: // ensure that all specified Roles exist; normalize input to array of Roles or NULL
551: if ($roles === self::ALL) {
552: $roles = array(self::ALL);
553:
554: } else {
555: if (!is_array($roles)) {
556: $roles = array($roles);
557: }
558:
559: foreach ($roles as $role) {
560: $this->checkRole($role);
561: }
562: }
563:
564: // ensure that all specified Resources exist; normalize input to array of Resources or NULL
565: if ($resources === self::ALL) {
566: $resources = array(self::ALL);
567:
568: } else {
569: if (!is_array($resources)) {
570: $resources = array($resources);
571: }
572:
573: foreach ($resources as $resource) {
574: $this->checkResource($resource);
575: }
576: }
577:
578: // normalize privileges to array
579: if ($privileges === self::ALL) {
580: $privileges = array();
581:
582: } elseif (!is_array($privileges)) {
583: $privileges = array($privileges);
584: }
585:
586:
587: if ($toAdd) { // add to the rules
588: foreach ($resources as $resource) {
589: foreach ($roles as $role) {
590: $rules = & $this->getRules($resource, $role, TRUE);
591: if (count($privileges) === 0) {
592: $rules['allPrivileges']['type'] = $type;
593: $rules['allPrivileges']['assert'] = $assertion;
594: if (!isset($rules['byPrivilege'])) {
595: $rules['byPrivilege'] = array();
596: }
597: } else {
598: foreach ($privileges as $privilege) {
599: $rules['byPrivilege'][$privilege]['type'] = $type;
600: $rules['byPrivilege'][$privilege]['assert'] = $assertion;
601: }
602: }
603: }
604: }
605:
606: } else { // remove from the rules
607: foreach ($resources as $resource) {
608: foreach ($roles as $role) {
609: $rules = & $this->getRules($resource, $role);
610: if ($rules === NULL) {
611: continue;
612: }
613: if (count($privileges) === 0) {
614: if ($resource === self::ALL && $role === self::ALL) {
615: if ($type === $rules['allPrivileges']['type']) {
616: $rules = array(
617: 'allPrivileges' => array(
618: 'type' => self::DENY,
619: 'assert' => NULL
620: ),
621: 'byPrivilege' => array()
622: );
623: }
624: continue;
625: }
626: if ($type === $rules['allPrivileges']['type']) {
627: unset($rules['allPrivileges']);
628: }
629: } else {
630: foreach ($privileges as $privilege) {
631: if (isset($rules['byPrivilege'][$privilege]) &&
632: $type === $rules['byPrivilege'][$privilege]['type']) {
633: unset($rules['byPrivilege'][$privilege]);
634: }
635: }
636: }
637: }
638: }
639: }
640: }
641:
642:
643:
644: /********************* querying the ACL ****************d*g**/
645:
646:
647:
648: /**
649: * Returns TRUE if and only if the Role has access to the Resource.
650: *
651: * If either $role or $resource is Permission::ALL, then the query applies to all Roles or all Resources,
652: * respectively. Both may be Permission::ALL to query whether the ACL has a "blacklist" rule
653: * (allow everything to all). By default, Permission creates a "whitelist" rule (deny
654: * everything to all), and this method would return FALSE unless this default has
655: * been overridden (i.e., by executing $acl->allow()).
656: *
657: * If a $privilege is not provided, then this method returns FALSE if and only if the
658: * Role is denied access to at least one privilege upon the Resource. In other words, this
659: * method returns TRUE if and only if the Role is allowed all privileges on the Resource.
660: *
661: * This method checks Role inheritance using a depth-first traversal of the Role list.
662: * The highest priority parent (i.e., the parent most recently added) is checked first,
663: * and its respective parents are checked similarly before the lower-priority parents of
664: * the Role are checked.
665: *
666: * @param string|Permission::ALL|IRole role
667: * @param string|Permission::ALL|IResource resource
668: * @param string|Permission::ALL privilege
669: * @throws InvalidStateException
670: * @return bool
671: */
672: public function isAllowed($role = self::ALL, $resource = self::ALL, $privilege = self::ALL)
673: {
674: $this->queriedRole = $role;
675: if ($role !== self::ALL) {
676: if ($role instanceof IRole) {
677: $role = $role->getRoleId();
678: }
679: $this->checkRole($role);
680: }
681:
682: $this->queriedResource = $resource;
683: if ($resource !== self::ALL) {
684: if ($resource instanceof IResource) {
685: $resource = $resource->getResourceId();
686: }
687: $this->checkResource($resource);
688: }
689:
690: if ($privilege === self::ALL) {
691: // query on all privileges
692: do {
693: // depth-first search on $role if it is not 'allRoles' pseudo-parent
694: if ($role !== NULL && NULL !== ($result = $this->roleDFSAllPrivileges($role, $resource))) {
695: break;
696: }
697:
698: // look for rule on 'allRoles' psuedo-parent
699: if (NULL !== ($rules = $this->getRules($resource, self::ALL))) {
700: foreach ($rules['byPrivilege'] as $privilege => $rule) {
701: if (self::DENY === ($ruleTypeOnePrivilege = $this->getRuleType($resource, NULL, $privilege))) {
702: $result = self::DENY;
703: break 2;
704: }
705: }
706: if (NULL !== ($ruleTypeAllPrivileges = $this->getRuleType($resource, NULL, NULL))) {
707: $result = self::ALLOW === $ruleTypeAllPrivileges;
708: break;
709: }
710: }
711:
712: // try next Resource
713: $resource = $this->resources[$resource]['parent'];
714:
715: } while (TRUE); // loop terminates at 'allResources' pseudo-parent
716:
717: } else {
718: // query on one privilege
719: do {
720: // depth-first search on $role if it is not 'allRoles' pseudo-parent
721: if ($role !== NULL && NULL !== ($result = $this->roleDFSOnePrivilege($role, $resource, $privilege))) {
722: break;
723: }
724:
725: // look for rule on 'allRoles' pseudo-parent
726: if (NULL !== ($ruleType = $this->getRuleType($resource, NULL, $privilege))) {
727: $result = self::ALLOW === $ruleType;
728: break;
729:
730: } elseif (NULL !== ($ruleTypeAllPrivileges = $this->getRuleType($resource, NULL, NULL))) {
731: $result = self::ALLOW === $ruleTypeAllPrivileges;
732: break;
733: }
734:
735: // try next Resource
736: $resource = $this->resources[$resource]['parent'];
737:
738: } while (TRUE); // loop terminates at 'allResources' pseudo-parent
739: }
740:
741: $this->queriedRole = $this->queriedResource = NULL;
742: return $result;
743: }
744:
745:
746:
747: /**
748: * Returns real currently queried Role. Use by {@link IPermissionAssertion::asert()}.
749: * @return mixed
750: */
751: public function getQueriedRole()
752: {
753: return $this->queriedRole;
754: }
755:
756:
757:
758: /**
759: * Returns real currently queried Resource. Use by {@link IPermissionAssertion::asert()}.
760: * @return mixed
761: */
762: public function getQueriedResource()
763: {
764: return $this->queriedResource;
765: }
766:
767:
768:
769: /********************* internals ****************d*g**/
770:
771:
772:
773: /**
774: * Performs a depth-first search of the Role DAG, starting at $role, in order to find a rule.
775: * allowing/denying $role access to all privileges upon $resource
776: *
777: * This method returns TRUE if a rule is found and allows access. If a rule exists and denies access,
778: * then this method returns FALSE. If no applicable rule is found, then this method returns NULL.
779: *
780: * @param string role
781: * @param string resource
782: * @return bool|NULL
783: */
784: private function roleDFSAllPrivileges($role, $resource)
785: {
786: $dfs = array(
787: 'visited' => array(),
788: 'stack' => array($role),
789: );
790:
791: while (NULL !== ($role = array_pop($dfs['stack']))) {
792: if (!isset($dfs['visited'][$role])) {
793: if (NULL !== ($result = $this->roleDFSVisitAllPrivileges($role, $resource, $dfs))) {
794: return $result;
795: }
796: }
797: }
798:
799: return NULL;
800: }
801:
802:
803:
804: /**
805: * Visits a $role in order to look for a rule allowing/denying $role access to all privileges upon $resource.
806: *
807: * This method returns TRUE if a rule is found and allows access. If a rule exists and denies access,
808: * then this method returns FALSE. If no applicable rule is found, then this method returns NULL.
809: *
810: * This method is used by the internal depth-first search algorithm and may modify the DFS data structure.
811: *
812: * @param string role
813: * @param string resource
814: * @param array dfs
815: * @return bool|NULL
816: */
817: private function roleDFSVisitAllPrivileges($role, $resource, &$dfs)
818: {
819: if (NULL !== ($rules = $this->getRules($resource, $role))) {
820: foreach ($rules['byPrivilege'] as $privilege => $rule) {
821: if (self::DENY === $this->getRuleType($resource, $role, $privilege)) {
822: return self::DENY;
823: }
824: }
825: if (NULL !== ($type = $this->getRuleType($resource, $role, NULL))) {
826: return self::ALLOW === $type;
827: }
828: }
829:
830: $dfs['visited'][$role] = TRUE;
831: foreach ($this->roles[$role]['parents'] as $roleParent => $foo) {
832: $dfs['stack'][] = $roleParent;
833: }
834:
835: return NULL;
836: }
837:
838:
839:
840: /**
841: * Performs a depth-first search of the Role DAG, starting at $role, in order to find a rule.
842: * allowing/denying $role access to a $privilege upon $resource
843: *
844: * This method returns TRUE if a rule is found and allows access. If a rule exists and denies access,
845: * then this method returns FALSE. If no applicable rule is found, then this method returns NULL.
846: *
847: * @param string role
848: * @param string resource
849: * @param string privilege
850: * @return bool|NULL
851: */
852: private function roleDFSOnePrivilege($role, $resource, $privilege)
853: {
854: $dfs = array(
855: 'visited' => array(),
856: 'stack' => array($role),
857: );
858:
859: while (NULL !== ($role = array_pop($dfs['stack']))) {
860: if (!isset($dfs['visited'][$role])) {
861: if (NULL !== ($result = $this->roleDFSVisitOnePrivilege($role, $resource, $privilege, $dfs))) {
862: return $result;
863: }
864: }
865: }
866:
867: return NULL;
868: }
869:
870:
871:
872: /**
873: * Visits a $role in order to look for a rule allowing/denying $role access to a $privilege upon $resource.
874: *
875: * This method returns TRUE if a rule is found and allows access. If a rule exists and denies access,
876: * then this method returns FALSE. If no applicable rule is found, then this method returns NULL.
877: *
878: * This method is used by the internal depth-first search algorithm and may modify the DFS data structure.
879: *
880: * @param string role
881: * @param string resource
882: * @param string privilege
883: * @param array dfs
884: * @return bool|NULL
885: */
886: private function roleDFSVisitOnePrivilege($role, $resource, $privilege, &$dfs)
887: {
888: if (NULL !== ($type = $this->getRuleType($resource, $role, $privilege))) {
889: return self::ALLOW === $type;
890: }
891:
892: if (NULL !== ($type = $this->getRuleType($resource, $role, NULL))) {
893: return self::ALLOW === $type;
894: }
895:
896: $dfs['visited'][$role] = TRUE;
897: foreach ($this->roles[$role]['parents'] as $roleParent => $foo)
898: $dfs['stack'][] = $roleParent;
899:
900: return NULL;
901: }
902:
903:
904:
905: /**
906: * Returns the rule type associated with the specified Resource, Role, and privilege.
907: * combination.
908: *
909: * If a rule does not exist or its attached assertion fails, which means that
910: * the rule is not applicable, then this method returns NULL. Otherwise, the
911: * rule type applies and is returned as either ALLOW or DENY.
912: *
913: * If $resource or $role is Permission::ALL, then this means that the rule must apply to
914: * all Resources or Roles, respectively.
915: *
916: * If $privilege is Permission::ALL, then the rule must apply to all privileges.
917: *
918: * If all three parameters are Permission::ALL, then the default ACL rule type is returned,
919: * based on whether its assertion method passes.
920: *
921: * @param string|Permission::ALL role
922: * @param string|Permission::ALL resource
923: * @param string|Permission::ALL privilege
924: * @return bool|NULL
925: */
926: private function getRuleType($resource, $role, $privilege)
927: {
928: // get the rules for the $resource and $role
929: if (NULL === ($rules = $this->getRules($resource, $role))) {
930: return NULL;
931: }
932:
933: // follow $privilege
934: if ($privilege === self::ALL) {
935: if (isset($rules['allPrivileges'])) {
936: $rule = $rules['allPrivileges'];
937: } else {
938: return NULL;
939: }
940: } elseif (!isset($rules['byPrivilege'][$privilege])) {
941: return NULL;
942:
943: } else {
944: $rule = $rules['byPrivilege'][$privilege];
945: }
946:
947: // check assertion if necessary
948: if ($rule['assert'] === NULL || $rule['assert']->assert($this, $role, $resource, $privilege)) {
949: return $rule['type'];
950:
951: } elseif ($resource !== self::ALL || $role !== self::ALL || $privilege !== self::ALL) {
952: return NULL;
953:
954: } elseif (self::ALLOW === $rule['type']) {
955: return self::DENY;
956:
957: } else {
958: return self::ALLOW;
959: }
960: }
961:
962:
963:
964: /**
965: * Returns the rules associated with a Resource and a Role, or NULL if no such rules exist.
966: *
967: * If either $resource or $role is Permission::ALL, this means that the rules returned are for all Resources or all Roles,
968: * respectively. Both can be Permission::ALL to return the default rule set for all Resources and all Roles.
969: *
970: * If the $create parameter is TRUE, then a rule set is first created and then returned to the caller.
971: *
972: * @param string|Permission::ALL resource
973: * @param string|Permission::ALL role
974: * @param boolean create
975: * @return array|NULL
976: */
977: private function & getRules($resource, $role, $create = FALSE)
978: {
979: // follow $resource
980: do {
981: if ($resource === self::ALL) {
982: $visitor = & $this->rules['allResources'];
983: break;
984: }
985: if (!isset($this->rules['byResource'][$resource])) {
986: if (!$create) {
987: $null = NULL;
988: return $null;
989: }
990: $this->rules['byResource'][$resource] = array();
991: }
992: $visitor = & $this->rules['byResource'][$resource];
993: } while (FALSE);
994:
995:
996: // follow $role
997: if ($role === self::ALL) {
998: if (!isset($visitor['allRoles'])) {
999: if (!$create) {
1000: $null = NULL;
1001: return $null;
1002: }
1003: $visitor['allRoles']['byPrivilege'] = array();
1004: }
1005: return $visitor['allRoles'];
1006: }
1007:
1008: if (!isset($visitor['byRole'][$role])) {
1009: if (!$create) {
1010: $null = NULL;
1011: return $null;
1012: }
1013: $visitor['byRole'][$role]['byPrivilege'] = array();
1014: }
1015:
1016: return $visitor['byRole'][$role];
1017: }
1018:
1019: }

Source for file Permission.php

Namespaces