1: <?php
2: /**
3: * The Horde_Perms_Datatree class provides a Horde_DataTree driver for the Horde
4: * permissions system.
5: *
6: * Copyright 2001-2012 Horde LLC (http://www.horde.org/)
7: *
8: * See the enclosed file COPYING for license information (LGPL). If you
9: * did not receive this file, see http://www.horde.org/licenses/lgpl21.
10: *
11: * @author Chuck Hagenbuch <chuck@horde.org>
12: * @author Jan Schneider <jan@horde.org>
13: * @category Horde
14: * @package Perms
15: */
16: class Horde_Perms_Datatree extends Horde_Perms_Base
17: {
18: /**
19: * Pointer to a Horde_DataTree instance to manage the different permissions.
20: *
21: * @var Horde_DataTree
22: */
23: protected $_datatree;
24:
25: /**
26: * Incrementing version number if cached classes change.
27: *
28: * @var integer
29: */
30: private $_cacheVersion = 2;
31:
32: /**
33: * Cache for getPermission().
34: *
35: * @var array
36: */
37: protected $_permsCache = array();
38:
39: /**
40: * Constructor.
41: *
42: * @param array $params Configuration parameters (in addition to base
43: * Horde_Perms parameters):
44: * <pre>
45: * 'datatree' - (Horde_DataTree) A datatree object. [REQUIRED]
46: * </pre>
47: *
48: * @throws Horde_Perms_Exception
49: */
50: public function __construct($params = array())
51: {
52: if (empty($params['datatree'])) {
53: throw new Horde_Perms_Exception('You must configure a Horde_DataTree backend.');
54: }
55:
56: $this->_datatree = $params['datatree'];
57:
58: parent::__construct($params);
59: }
60:
61: /**
62: * Returns a new permissions object.
63: *
64: * @param string $name The permission's name.
65: * @param string $type The permission type.
66: * @param array $params The permission parameters.
67: *
68: * @return Horde_DataTreeObject_Permissions A new permissions object.
69: */
70: public function newPermission($name, $type = 'matrix', $params = null)
71: {
72: $perm = new Horde_Perms_Permission_Datatree($name, $this->_cacheVersion, $type, $params);
73: $perm->setCacheOb($this->_cache);
74: $perm->setDataTree($this->_datatree);
75: return $perm;
76: }
77:
78: /**
79: * Returns a permission object corresponding to the named permission,
80: * with the users and other data retrieved appropriately.
81: *
82: * @param string $name The name of the permission to retrieve.
83: *
84: * @return TODO
85: */
86: public function getPermission($name)
87: {
88: if (isset($this->_permsCache[$name])) {
89: return $this->_permsCache[$name];
90: }
91:
92: $perm = $this->_cache->get('perm_' . $this->_cacheVersion . $name, $GLOBALS['conf']['cache']['default_lifetime']);
93: if ($perm === false) {
94: $perm = $this->_datatree->getObject($name, 'Horde_Perms_Permission_Datatree');
95: $perm->setCacheVersion($this->_cacheVersion);
96: $this->_cache->set('perm_' . $this->_cacheVersion . $name, serialize($perm), $GLOBALS['conf']['cache']['default_lifetime']);
97: $this->_permsCache[$name] = $perm;
98: } else {
99: $this->_permsCache[$name] = unserialize($perm);
100: }
101:
102: $this->_permsCache[$name]->setCacheOb($this->_cache);
103: $this->_permsCache[$name]->setDataTree($this->_datatree);
104:
105: return $this->_permsCache[$name];
106: }
107:
108: /**
109: * Returns a permission object corresponding to the given unique ID,
110: * with the users and other data retrieved appropriately.
111: *
112: * @param integer $cid The unique ID of the permission to retrieve.
113: */
114: public function getPermissionById($cid)
115: {
116: if ($cid == Horde_Perms::ROOT) {
117: return $this->newPermission(Horde_Perms::ROOT);
118: }
119: $perm = $this->_datatree->getObjectById($cid, 'Horde_Perms_Permission_Datatree');
120: $perm->setCacheOb($this->_cache);
121: return $perm;
122: }
123:
124: /**
125: * Adds a permission to the permissions system. The permission must first
126: * be created with newPermission(), and have any initial users added to
127: * it, before this function is called.
128: *
129: * @param Horde_Perms_Permission_Datatree $perm The new perm
130: * object.
131: * @throws Horde_Perms_Exception
132: */
133: public function addPermission(Horde_Perms_Permission $perm)
134: {
135: $name = $perm->getName();
136: if (empty($name)) {
137: throw Horde_Perms_Exception('Permission names must be non-empty.');
138: }
139: $this->_cache->expire('perm_' . $this->_cacheVersion . $name);
140: $this->_cache->expire('perm_exists_' . $this->_cacheVersion . $name);
141:
142: return $this->_datatree->add($perm);
143: }
144:
145: /**
146: * Removes a permission from the permissions system permanently.
147: *
148: * @param Horde_Perms_Permission_Datatree $perm The permission to
149: * remove.
150: * @param boolean $force Force to remove
151: * every child.
152: */
153: public function removePermission(Horde_Perms_Permission $perm,
154: $force = false)
155: {
156: $keys = $this->_datatree->get(DATATREE_FORMAT_FLAT, $perm->name, true);
157: foreach ($keys as $key) {
158: $this->_cache->expire('perm_' . $this->_cacheVersion . $key);
159: $this->_cache->expire('perm_exists_' . $this->_cacheVersion . $key);
160: }
161:
162: return $this->_datatree->remove($perm->name, $force);
163: }
164:
165: /**
166: * Returns the unique identifier of this permission.
167: *
168: * @param Horde_Perms_Permission_Datatree $perm The permission
169: * object to get the
170: * ID of.
171: *
172: * @return integer The unique id.
173: */
174: public function getPermissionId($permission)
175: {
176: return $this->_datatree->getId($permission->getName());
177: }
178:
179: /**
180: * Checks if a permission exists in the system.
181: *
182: * @param string $permission The permission to check.
183: *
184: * @return boolean True if the permission exists.
185: */
186: public function exists($permission)
187: {
188: $key = 'perm_exists_' . $this->_cacheVersion . $permission;
189: $exists = $this->_cache->get($key, $GLOBALS['conf']['cache']['default_lifetime']);
190: if ($exists === false) {
191: $exists = $this->_datatree->exists($permission);
192: $this->_cache->set($key, (string)$exists);
193: }
194:
195: return (bool)$exists;
196: }
197:
198: /**
199: * Returns a list of parent permissions.
200: *
201: * @param string $child The name of the child to retrieve parents for.
202: *
203: * @return array A hash with all parents in a tree format.
204: */
205: public function getParents($child)
206: {
207: return $this->_datatree->getParents($child);
208: }
209:
210: /**
211: * Returns a child's direct parent ID.
212: *
213: * @param mixed $child Either the object, an array containing the
214: * path elements, or the object name for which
215: * to look up the parent's ID.
216: *
217: * @return mixed The unique ID of the parent or PEAR_Error on error.
218: */
219: public function getParent($child)
220: {
221: return $this->_datatree->getParent($child);
222: }
223:
224: /**
225: * Returns all permissions of the system in a tree format.
226: *
227: * @return array A hash with all permissions in a tree format.
228: */
229: public function getTree()
230: {
231: return $this->_datatree->get(DATATREE_FORMAT_FLAT, Horde_Perms::ROOT, true);
232: }
233: }
234: