Source for file Permission.php

Documentation is available at Permission.php

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