1: <?php
  2: /**
  3:  * The Horde_Perms_Sql:: class provides a SQL driver for the Horde
  4:  * permissions system.
  5:  *
  6:  * Copyright 2008-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   Duck <duck@obala.net>
 12:  * @category Horde
 13:  * @package  Perms
 14:  */
 15: class Horde_Perms_Sql extends Horde_Perms_Base
 16: {
 17:     /**
 18:      * Configuration parameters.
 19:      *
 20:      * @var array
 21:      */
 22:     protected $_params = array();
 23: 
 24:     /**
 25:      * Handle for the current database connection.
 26:      *
 27:      * @var Horde_Db_Adapter
 28:      */
 29:     protected $_db;
 30: 
 31:     /**
 32:      * Incrementing version number if cached classes change.
 33:      *
 34:      * @var integer
 35:      */
 36:     private $_cacheVersion = 2;
 37: 
 38:     /**
 39:      * Cache of previously retrieved permissions.
 40:      *
 41:      * @var array
 42:      */
 43:     protected $_permsCache = array();
 44: 
 45:     /**
 46:      * Constructor.
 47:      *
 48:      * @param array $params  Configuration parameters (in addition to base
 49:      *                       Horde_Perms parameters):
 50:      * <pre>
 51:      * 'db' - (Horde_Db_Adapter) [REQUIRED] The DB instance.
 52:      * 'table' - (string) The name of the perms table.
 53:      *           DEFAULT: 'horde_perms'
 54:      * </pre>
 55:      *
 56:      * @throws Horde_Perms_Exception
 57:      */
 58:     public function __construct($params = array())
 59:     {
 60:         if (!isset($params['db'])) {
 61:             throw new Horde_Perms_Exception('Missing db parameter.');
 62:         }
 63:         $this->_db = $params['db'];
 64:         unset($params['db']);
 65: 
 66:         $this->_params = array_merge(array(
 67:             'table' => 'horde_perms'
 68:         ), $this->_params, $params);
 69: 
 70:         parent::__construct($params);
 71:     }
 72: 
 73:     /**
 74:      * Returns a new permissions object.
 75:      *
 76:      * @param string $name   The permission's name.
 77:      * @param string $type   The permission type.
 78:      * @param array $params  The permission parameters.
 79:      *
 80:      * @return Horde_Perms_Permission_Sql  A new permissions object.
 81:      */
 82:     public function newPermission($name, $type = 'matrix', $params = null)
 83:     {
 84:         $ob = new Horde_Perms_Permission_Sql($name, $this->_cacheVersion, $type, $params);
 85:         $ob->setObs($this->_cache, $this->_db);
 86:         return $ob;
 87:     }
 88: 
 89:     /**
 90:      * Returns an object corresponding to the named permission, with the
 91:      * users and other data retrieved appropriately.
 92:      *
 93:      * @param string $name  The name of the permission to retrieve.
 94:      *
 95:      * @return Horde_Perms_Permission_Sql  TODO
 96:      * @throw Horde_Perms_Exception
 97:      */
 98:     public function getPermission($name)
 99:     {
100:         if (isset($this->_permsCache[$name])) {
101:             return $this->_permsCache[$name];
102:         }
103: 
104:         $perm = $this->_cache->get('perm_sql_' . $this->_cacheVersion . $name, $GLOBALS['conf']['cache']['default_lifetime']);
105:         if (empty($perm)) {
106:             $query = 'SELECT perm_id, perm_data FROM ' .
107:                 $this->_params['table'] . ' WHERE perm_name = ?';
108: 
109:             try {
110:                 $result = $this->_db->selectOne($query, array($name));
111:             } catch (Horde_Db_Exception $e) {
112:                 throw new Horde_Perms_Exception($e);
113:             }
114: 
115:             if (empty($result)) {
116:                 throw new Horde_Perms_Exception('Does not exist');
117:             }
118: 
119:             $object = new Horde_Perms_Permission_Sql($name, $this->_cacheVersion);
120:             $object->setId($result['perm_id']);
121:             $object->setData(unserialize($result['perm_data']));
122: 
123:             $this->_cache->set('perm_sql_' . $this->_cacheVersion . $name, serialize($object));
124: 
125:             $this->_permsCache[$name] = $object;
126:         } else {
127:             $this->_permsCache[$name] = unserialize($perm);
128:         }
129: 
130:         $this->_permsCache[$name]->setObs($this->_cache, $this->_db);
131: 
132:         return $this->_permsCache[$name];
133:     }
134: 
135:     /**
136:      * Returns a permission object corresponding to the given unique ID,
137:      * with the users and other data retrieved appropriately.
138:      *
139:      * @param integer $id  The unique ID of the permission to retrieve.
140:      *
141:      * @return Horde_Perms_Permission_Sql  TODO
142:      * @throws Horde_Perms_Exception
143:      */
144:     public function getPermissionById($id)
145:     {
146:         if ($id == Horde_Perms::ROOT || empty($id)) {
147:             $object = $this->newPermission(Horde_Perms::ROOT);
148:         } else {
149:             $query = 'SELECT perm_name, perm_data FROM ' .
150:                 $this->_params['table'] . ' WHERE perm_id = ?';
151: 
152:             try {
153:                 $result = $this->_db->selectOne($query, array($id));
154:             } catch (Horde_Db_Exception $e) {
155:                 throw new Horde_Perms_Exception($e);
156:             }
157: 
158:             if (empty($result)) {
159:                 throw new Horde_Perms_Exception('Does not exist');
160:             }
161: 
162:             $object = new Horde_Perms_Permission_Sql($result['perm_name'], $this->_cacheVersion);
163:             $object->setId($id);
164:             $object->setData(unserialize($result['perm_data']));
165:             $object->setObs($this->_cache, $this->_db);
166:         }
167: 
168:         return $object;
169:     }
170: 
171:     /**
172:      * Adds a permission to the permissions system. The permission must first
173:      * be created with newPermission(), and have any initial users added to
174:      * it, before this function is called.
175:      *
176:      * @param Horde_Perms_Permission_Sql $perm  The perm object.
177:      *
178:      * @return integer  Permission ID in the database.
179:      * @throws Horde_Perms_Exception
180:      */
181:     public function addPermission(Horde_Perms_Permission $perm)
182:     {
183:         $name = $perm->getName();
184:         if (empty($name)) {
185:             throw new Horde_Perms_Exception('Permission name must be non-empty.');
186:         }
187: 
188:         $this->_cache->expire('perm_sql_' . $this->_cacheVersion . $name);
189:         $this->_cache->expire('perm_sql_exists_' . $this->_cacheVersion . $name);
190: 
191:         // remove root from the name
192:         $root = Horde_Perms::ROOT . ':';
193:         if (substr($name, 0, strlen($root)) == ($root)) {
194:             $name = substr($name, strlen($root));
195:         }
196: 
197:         // build parents
198:         $parents = '';
199:         if (($pos = strrpos($name, ':')) !== false) {
200:             $parent_name = substr($name, 0, $pos);
201:             $query = 'SELECT perm_id, perm_parents FROM ' .
202:                 $this->_params['table'] . ' WHERE perm_name = ?';
203:             $result = $this->_db->selectOne($query, array($parent_name));
204:             if (empty($result)) {
205:                 throw new Horde_Perms_Exception(Horde_Perms_Translation::t("Trying to create sub permission of non-existant parent permission. Create parent permission(s) first."));
206:             }
207:             $parents = $result['perm_parents'] . ':' . $result['perm_id'];
208:         }
209: 
210:         $query = 'INSERT INTO ' . $this->_params['table'] .
211:             ' (perm_name, perm_parents) VALUES (?, ?)';
212: 
213:         try {
214:             $id = $this->_db->insert($query, array($name, $parents));
215:         } catch (Horde_Db_Exception $e) {
216:             throw new Horde_Perms_Exception($e);
217:         }
218: 
219:         $perm->setId($id);
220:         $perm->save();
221: 
222:         return $id;
223:     }
224: 
225:     /**
226:      * Removes a permission from the permissions system permanently.
227:      *
228:      * @param Horde_Perms_Permission_Sql $perm  The permission to
229:      *                                                remove.
230:      * @param boolean $force                          Force to remove every
231:      *                                                child.
232:      *
233:      * @return boolean  True if permission was deleted.
234:      * @throws Horde_Perms_Exception
235:      */
236:     public function removePermission(Horde_Perms_Permission $perm,
237:                                      $force = false)
238:     {
239:         $name = $perm->getName();
240:         $this->_cache->expire('perm_sql_' . $this->_cacheVersion . $name);
241:         $this->_cache->expire('perm_sql_exists_' . $this->_cacheVersion . $name);
242: 
243:         $query = 'DELETE FROM ' . $this->_params['table'] .
244:             ' WHERE perm_name = ?';
245: 
246:         try {
247:             $result = $this->_db->delete($query, array($name));
248:         } catch (Horde_Db_Exception $e) {
249:             throw new Horde_Perms_Exception($e);
250:         }
251: 
252:         if (!$force) {
253:             return (bool)$result;
254:         }
255: 
256:         $query = 'DELETE FROM ' . $this->_params['table'] .
257:             ' WHERE perm_name LIKE ?';
258: 
259:         try {
260:             return (bool)$this->_db->delete($query, array($name . ':%'));
261:         } catch (Horde_Db_Exception $e) {
262:             throw new Horde_Perms_Exception($e);
263:         }
264:     }
265: 
266:     /**
267:      * Returns the unique identifier of this permission.
268:      *
269:      * @param Horde_Perms_Permission_Sql $perm  The permission object to
270:      *                                                get the ID of.
271:      *
272:      * @return integer  The unique id.
273:      * @throws Horde_Perms_Exception
274:      */
275:     public function getPermissionId($permission)
276:     {
277:         if ($permission->getName() == Horde_Perms::ROOT) {
278:             return Horde_Perms::ROOT;
279:         }
280: 
281:         $query = 'SELECT perm_id FROM ' . $this->_params['table'] .
282:             ' WHERE perm_name = ?';
283: 
284:         try {
285:             return $this->_db->selectValue($query, array($permission->getName()));
286:         } catch (Horde_Db_Exception $e) {
287:             throw new Horde_Perms_Exception($e);
288:         }
289:     }
290: 
291:     /**
292:      * Checks if a permission exists in the system.
293:      *
294:      * @param string $permission  The permission to check.
295:      *
296:      * @return boolean  True if the permission exists.
297:      * @throws Horde_Perms_Exception
298:      */
299:     public function exists($permission)
300:     {
301:         $key = 'perm_sql_exists_' . $this->_cacheVersion . $permission;
302:         $exists = $this->_cache->get($key, $GLOBALS['conf']['cache']['default_lifetime']);
303:         if ($exists === false) {
304:             $query = 'SELECT COUNT(*) FROM ' . $this->_params['table'] .
305:                 ' WHERE perm_name = ?';
306: 
307:             try {
308:                 $exists = $this->_db->selectValue($query, array($permission));
309:             } catch (Horde_Db_Exception $e) {
310:                 throw new Horde_Perms_Exception($e);
311:             }
312: 
313:             $this->_cache->set($key, (string)$exists);
314:         }
315: 
316:         return (bool)$exists;
317:     }
318: 
319:     /**
320:      * Returns a child's direct parent ID.
321:      *
322:      * @param mixed $child  The object name for which to look up the parent's
323:      *                      ID.
324:      *
325:      * @return integer  The unique ID of the parent.
326:      * @throws Horde_Perms_Exception
327:      */
328:     public function getParent($child)
329:     {
330:         $query = 'SELECT perm_parents FROM ' . $this->_params['table'] .
331:             ' WHERE perm_name = ?';
332: 
333:         try {
334:             $parents = $this->_db->selectValue($query, array($child));
335:         } catch (Horde_Db_Exception $e) {
336:             throw new Horde_Perms_Exception($e);
337:         }
338: 
339:         if (empty($parents)) {
340:             return Horde_Perms::ROOT;
341:         }
342: 
343:         $parents = explode(':', $parents);
344: 
345:         return array_pop($parents);
346:     }
347: 
348:     /**
349:      * Returns a list of parent permissions.
350:      *
351:      * @param string $child  The name of the child to retrieve parents for.
352:      *
353:      * @return array  A hash with all parents in a tree format.
354:      * @throws Horde_Perms_Exception
355:      */
356:     public function getParents($child)
357:     {
358:         $query = 'SELECT perm_parents FROM ' .  $this->_params['table'] .
359:             ' WHERE perm_name = ?';
360: 
361:         try {
362:             $result = $this->_db->selectValue($query, array($child));
363:         } catch (Horde_Db_Exception $e) {
364:             throw new Horde_Perms_Exception($e);
365:         }
366: 
367:         if (empty($result)) {
368:             throw new Horde_Perms_Exception('Does not exist');
369:         }
370: 
371:         return $this->_getParents($result);
372:     }
373: 
374:     /**
375:      * TODO
376:      */
377:     protected function _getParents($parents)
378:     {
379:         if (empty($parents)) {
380:             return array(Horde_Perms::ROOT => true);
381:         }
382: 
383:         $pname = $parents;
384:         $parents = substr($parents, 0, strrpos($parents, ':'));
385: 
386:         return array($pname => $this->_getParents($parents));
387:     }
388: 
389:     /**
390:      * Returns all permissions of the system in a tree format.
391:      *
392:      * @return array  A hash with all permissions in a tree format.
393:      * @throws Horde_Perms_Exception
394:      */
395:     public function getTree()
396:     {
397:         $query = 'SELECT perm_id, perm_name FROM ' . $this->_params['table'] .
398:             ' ORDER BY perm_name ASC';
399: 
400:         try {
401:             $tree = $this->_db->selectAssoc($query);
402:         } catch (Horde_Db_Exception $e) {
403:             throw new Horde_Perms_Exception($e);
404:         }
405: 
406:         $tree[Horde_Perms::ROOT] = Horde_Perms::ROOT;
407: 
408:         return $tree;
409:     }
410: }
411: