source: trunk/lib/ACL.inc.php @ 505

<?php
/**
 * The Strangecode Codebase - a general application development framework for PHP
 * For details visit the project site: <http://trac.strangecode.com/codebase/>
 * Copyright 2001-2012 Strangecode, LLC
 *
 * This file is part of The Strangecode Codebase.
 *
 * The Strangecode Codebase is free software: you can redistribute it and/or
 * modify it under the terms of the GNU General Public License as published by the
 * Free Software Foundation, either version 3 of the License, or (at your option)
 * any later version.
 *
 * The Strangecode Codebase is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * The Strangecode Codebase. If not, see <http://www.gnu.org/licenses/>.
 */

/*
* ACL.inc.php
*
* Uses the ARO/ACO/AXO model of Access Control Lists.
* Uses Modified Preorder Tree Traversal to maintain a tree-structure.
* See: http://www.sitepoint.com/print/hierarchical-data-database
* Includes a command-line tool for managing rights (codebase/bin/acl.cli.php).
*
*
* @author   Quinn Comendant <quinn@strangecode.com>
* @version  1.0
* @since    14 Jun 2006 22:35:11
*/

require_once dirname(__FILE__) . '/Cache.inc.php';

class ACL
{

    // A place to keep an object instance for the singleton pattern.
    protected static $instance = null;

    // Configuration parameters for this object.
    protected $_params = array(
        // If false nothing will be cached or retrieved. Useful for testing realtime data requests.
        'enable_cache' => true,

        // Automatically create table and verify columns. Better set to false after site launch.
        'create_table' => false,

        // Maximum allowed length of names.
        // This value can be increased only if {aro,aco,axo}_tbl.name VARCHAR length is increased.
        'name_max_length' => 32.
    );

    /**
     * Constructor.
     */
    public function __construct()
    {
        $app =& App::getInstance();

        // Configure the cache object.
        $this->cache = new Cache('acl');
        $this->cache->setParam(array('enabled' => true));

        // Get create tables config from global context.
        if (!is_null($app->getParam('db_create_tables'))) {
            $this->setParam(array('create_table' => $app->getParam('db_create_tables')));
        }
    }

    /**
     * This method enforces the singleton pattern for this class.
     *
     * @return  object  Reference to the global ACL object.
     * @access  public
     * @static
     */
    public static function &getInstance()
    {
        if (self::$instance === null) {
            self::$instance = new self();
        }

        return self::$instance;
    }

    /**
     * Set (or overwrite existing) parameters by passing an array of new parameters.
     *
     * @access public
     *
     * @param  array    $params     Array of parameters (key => val pairs).
     */
    public function setParam($params)
    {
        $app =& App::getInstance();

        if (isset($params) && is_array($params)) {
            // Merge new parameters with old overriding only those passed.
            $this->_params = array_merge($this->_params, $params);
        } else {
            $app->logMsg(sprintf('Parameters are not an array: %s', $params), LOG_ERR, __FILE__, __LINE__);
        }
    }

    /**
     * Return the value of a parameter, if it exists.
     *
     * @access public
     * @param string $param        Which parameter to return.
     * @return mixed               Configured parameter value.
     */
    public function getParam($param)
    {
        $app =& App::getInstance();

        if (array_key_exists($param, $this->_params)) {
            return $this->_params[$param];
        } else {
            $app->logMsg(sprintf('Parameter is not set: %s', $param), LOG_NOTICE, __FILE__, __LINE__);
            return null;
        }
    }

    /**
     * Setup the database tables for this class.
     *
     * @access  public
     * @author  Quinn Comendant <quinn@strangecode.com>
     * @since   04 Jun 2006 16:41:42
     */
    public function initDB($recreate_db=false)
    {
        $app =& App::getInstance();
        $db =& DB::getInstance();

        static $_db_tested = false;

        if ($recreate_db || !$_db_tested && $this->getParam('create_table')) {

            if ($recreate_db) {
                $db->query("DROP TABLE IF EXISTS acl_tbl");
                $db->query("DROP TABLE IF EXISTS aro_tbl");
                $db->query("DROP TABLE IF EXISTS aco_tbl");
                $db->query("DROP TABLE IF EXISTS axo_tbl");
                $app->logMsg(sprintf('Dropping and recreating tables acl_tbl, aro_tbl, aco_tbl, axo_tbl.', null), LOG_INFO, __FILE__, __LINE__);
            }

            // acl_tbl
            $db->query("
                CREATE TABLE IF NOT EXISTS acl_tbl (
                    aro_id SMALLINT UNSIGNED NOT NULL DEFAULT '0',
                    aco_id SMALLINT UNSIGNED NOT NULL DEFAULT '0',
                    axo_id SMALLINT UNSIGNED NOT NULL DEFAULT '0',
                    access ENUM('allow', 'deny') DEFAULT NULL,
                    added_datetime DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
                    UNIQUE KEY (aro_id, aco_id, axo_id),
                    KEY (access)
                ) ENGINE=MyISAM
            ");
            if (!$db->columnExists('acl_tbl', array(
                'aro_id',
                'aco_id',
                'axo_id',
                'access',
                'added_datetime',
            ), false, false)) {
                $app->logMsg(sprintf('Database table acl_tbl has invalid columns. Please update this table manually.', null), LOG_ALERT, __FILE__, __LINE__);
                trigger_error(sprintf('Database table acl_tbl has invalid columns. Please update this table manually.', null), E_USER_ERROR);
            } else {
                // Insert root node data if nonexistant, dely all by default.
                $qid = $db->query("SELECT 1 FROM acl_tbl");
                if (mysql_num_rows($qid) == 0) {
                    $qid = $db->query("REPLACE INTO acl_tbl VALUES ('1', '1', '1', 'deny', NOW())");
                }
            }

            // aro_tbl, aco_tbl, axo_tbl
            foreach (array('aro', 'aco', 'axo') as $a_o) {
                $db->query("
                    CREATE TABLE IF NOT EXISTS {$a_o}_tbl (
                        {$a_o}_id SMALLINT UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT,
                        name VARCHAR(" . $this->getParam('name_max_length') . ") NOT NULL DEFAULT '',
                        lft MEDIUMINT UNSIGNED NOT NULL DEFAULT '0',
                        rgt MEDIUMINT UNSIGNED NOT NULL DEFAULT '0',
                        added_datetime DATETIME NOT NULL DEFAULT '0000-00-00 00:00:00',
                        UNIQUE KEY name (name(15)),
                        KEY transversal (lft, rgt)
                    ) ENGINE=MyISAM;
                ");

                if (!$db->columnExists("{$a_o}_tbl", array(
                    "{$a_o}_id",
                    'name',
                    'lft',
                    'rgt',
                    'added_datetime',
                ), false, false)) {
                    $app->logMsg(sprintf('Database table %s has invalid columns. Please update this table manually.', "{$a_o}_tbl"), LOG_ALERT, __FILE__, __LINE__);
                    trigger_error(sprintf('Database table %s has invalid columns. Please update this table manually.', "{$a_o}_tbl"), E_USER_ERROR);
                } else {
                    // Insert root node data if nonexistent.
                    $qid = $db->query("SELECT 1 FROM {$a_o}_tbl WHERE name = 'root'");
                    if (mysql_num_rows($qid) == 0) {
                        $qid = $db->query("REPLACE INTO {$a_o}_tbl (name, lft, rgt, added_datetime) VALUES ('root', 1, 2, NOW())");
                    }
                }

            }
        }
        $_db_tested = true;
        return true;
    }

    /*
    * Add a node to one of the aro/aco/axo tables.
    *
    * @access   public
    * @param    string $name A unique identifier for the new node.
    * @param    string $parent The name of the parent under-which to attach the new node.
    * @param    string $type The tree to add to, one of: aro, aco, axo.
    * @return   bool | int False on error, or the last_insert_id primary key of the new node.
    * @author   Quinn Comendant <quinn@strangecode.com>
    * @version  1.0
    * @since    14 Jun 2006 22:39:29
    */
    public function add($name, $parent=null, $type)
    {
        $app =& App::getInstance();
        $db =& DB::getInstance();

        $this->initDB();

        switch ($type) {
        case 'aro' :
            $tbl = 'aro_tbl';
            break;
        case 'aco' :
            $tbl = 'aco_tbl';
            break;
        case 'axo' :
            $tbl = 'axo_tbl';
            break;
        default :
            $app->logMsg(sprintf('Invalid access object type: %s', $type), LOG_ERR, __FILE__, __LINE__);
            return false;
            break;
        }

        // If $parent is null, use root object.
        if (is_null($parent)) {
            $parent = 'root';
        }

        // Ensure node and parent name aren't empty.
        if ('' == trim($name) || '' == trim($parent)) {
            $app->logMsg(sprintf('Cannot add node, parent (%s) or name (%s) missing.', $name, $parent), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Ensure node node name fits in the column size.
        // This value can be increased if {aro,aco.axo}_tbl.name VARCHAR length is increased.
        if (strlen(trim($name)) > $this->getParam('name_max_length')) {
            $app->logMsg(sprintf('Cannot add node, %s character limit exceeded for name "%s"', $this->getParam('name_max_length'), $name, $parent), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Ensure node is unique.
        $qid = $db->query("SELECT 1 FROM $tbl WHERE name = '" . $db->escapeString($name) . "'");
        if (mysql_num_rows($qid) > 0) {
            $app->logMsg(sprintf('Cannot add %s node, already exists: %s', $type, $name), LOG_INFO, __FILE__, __LINE__);
            return false;
        }

        // Select the rgt of $parent.
        $qid = $db->query("SELECT rgt FROM $tbl WHERE name = '" . $db->escapeString($parent) . "'");
        if (!list($parent_rgt) = mysql_fetch_row($qid)) {
            $app->logMsg(sprintf('Cannot add %s node to nonexistent parent: %s', $type, $parent), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Update transversal numbers for all nodes to the rgt of $parent.
        $db->query("UPDATE $tbl SET lft = lft + 2 WHERE lft >= $parent_rgt");
        $db->query("UPDATE $tbl SET rgt = rgt + 2 WHERE rgt >= $parent_rgt");

        // Insert new node just below parent. Lft is parent's old rgt.
        $db->query("
            INSERT INTO $tbl (name, lft, rgt, added_datetime)
            VALUES ('" . $db->escapeString($name) . "', $parent_rgt, $parent_rgt + 1, NOW())
        ");

        $app->logMsg(sprintf('Added %s node %s to parent %s.', $type, $name, $parent), LOG_INFO, __FILE__, __LINE__);
        return mysql_insert_id($db->getDBH());
    }

    // Alias functions for the different object types.
    public function addRequestObject($name, $parent=null)
    {
        return $this->add($name, $parent, 'aro');
    }
    public function addControlObject($name, $parent=null)
    {
        return $this->add($name, $parent, 'aco');
    }
    public function addXtraObject($name, $parent=null)
    {
        return $this->add($name, $parent, 'axo');
    }

    /*
    * Remove a node from one of the aro/aco/axo tables.
    *
    * @access   public
    * @param    string $name The identifier for the node to remove.
    * @param    string $type The tree to modify, one of: aro, aco, axo.
    * @return   bool | int False on error, or true on success.
    * @author   Quinn Comendant <quinn@strangecode.com>
    * @version  1.0
    * @since    14 Jun 2006 22:39:29
    */
    public function remove($name, $type)
    {
        $app =& App::getInstance();
        $db =& DB::getInstance();

        $this->initDB();

        switch ($type) {
        case 'aro' :
            $tbl = 'aro_tbl';
            $primary_key = 'aro_id';
            break;
        case 'aco' :
            $tbl = 'aco_tbl';
            $primary_key = 'aco_id';
            break;
        case 'axo' :
            $tbl = 'axo_tbl';
            $primary_key = 'axo_id';
            break;
        default :
            $app->logMsg(sprintf('Invalid access object type: %s', $type), LOG_ERR, __FILE__, __LINE__);
            return false;
            break;
        }

        // Ensure node name isn't empty.
        if ('' == trim($name)) {
            $app->logMsg(sprintf('Cannot add node, name missing.', null), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Select the lft and rgt of $name to use for selecting children and reordering transversals.
        $qid = $db->query("SELECT lft, rgt FROM $tbl WHERE name = '" . $db->escapeString($name) . "'");
        if (!list($lft, $rgt) = mysql_fetch_row($qid)) {
            $app->logMsg(sprintf('Cannot delete nonexistent %s name: %s', $type, $name), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Remove node and all children of node, as well as acl_tbl links.
        $db->query("
            DELETE $tbl, acl_tbl
            FROM $tbl
            LEFT JOIN acl_tbl ON ($tbl.$primary_key = acl_tbl.$primary_key)
            WHERE $tbl.lft BETWEEN $lft AND $rgt
        ");
        $num_deleted_nodes = mysql_affected_rows($db->getDBH());

        // Update transversal numbers for all nodes to the rgt of $parent, taking in to account the absence of it's children.
        $db->query("UPDATE $tbl SET lft = lft - ($rgt - $lft + 1) WHERE lft > $lft");
        $db->query("UPDATE $tbl SET rgt = rgt - ($rgt - $lft + 1) WHERE rgt > $rgt");

        $app->logMsg(sprintf('Removed %s node %s along with %s children.', $type, $name, $num_deleted_nodes - 1), LOG_INFO, __FILE__, __LINE__);
        return true;
    }

    // Alias functions for the different object types.
    public function removeRequestObject($name)
    {
        return $this->remove($name, 'aro');
    }
    public function removeControlObject($name)
    {
        return $this->remove($name, 'aco');
    }
    public function removeXtraObject($name)
    {
        return $this->remove($name, 'axo');
    }

    /*
    * Move a node to a new parent in one of the aro/aco/axo tables.
    *
    * @access   public
    * @param    string $name The identifier for the node to remove.
    * @param    string $new_parent The name of the parent under-which to attach the new node.
    * @param    string $type The tree to modify, one of: aro, aco, axo.
    * @return   bool | int False on error, or the last_insert_id primary key of the new node.
    * @author   Quinn Comendant <quinn@strangecode.com>
    * @version  1.0
    * @since    14 Jun 2006 22:39:29
    */
    public function move($name, $new_parent, $type)
    {
        $app =& App::getInstance();
        $db =& DB::getInstance();

        $this->initDB();

        switch ($type) {
        case 'aro' :
            $tbl = 'aro_tbl';
            $primary_key = 'aro_id';
            break;
        case 'aco' :
            $tbl = 'aco_tbl';
            $primary_key = 'aco_id';
            break;
        case 'axo' :
            $tbl = 'axo_tbl';
            $primary_key = 'axo_id';
            break;
        default :
            $app->logMsg(sprintf('Invalid access object type: %s', $type), LOG_ERR, __FILE__, __LINE__);
            return false;
            break;
        }

        // If $new_parent is null, use root object.
        if (is_null($new_parent)) {
            $new_parent = 'root';
        }

        // Ensure node and parent name aren't empty.
        if ('' == trim($name) || '' == trim($new_parent)) {
            $app->logMsg(sprintf('Cannot add node, parent (%s) or name (%s) missing.', $name, $new_parent), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Select the lft and rgt of $name to use for selecting children and reordering transversals.
        $qid = $db->query("SELECT lft, rgt FROM $tbl WHERE name = '" . $db->escapeString($name) . "'");
        if (!list($lft, $rgt) = mysql_fetch_row($qid)) {
            $app->logMsg(sprintf('Cannot move nonexistent %s name: %s', $type, $name), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Total number of transversal values (that is, the count of self plus all children times two).
        $total_transversal_value = ($rgt - $lft + 1);

        // Select the rgt of the new parent.
        $qid = $db->query("SELECT rgt FROM $tbl WHERE name = '" . $db->escapeString($new_parent) . "'");
        if (!list($new_parent_rgt) = mysql_fetch_row($qid)) {
            $app->logMsg(sprintf('Cannot move %s node to nonexistent parent: %s', $type, $new_parent), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Ensure the new parent is not a child of the node being moved.
        if ($new_parent_rgt <= $rgt && $new_parent_rgt >= $lft) {
            $app->logMsg(sprintf('Cannot move %s node %s to parent %s because it is a child of itself.', $type, $name, $new_parent), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Collect unique ids of all nodes being moved. The transversal numbers will become duplicated so these will be needed to identify these.
        $qid = $db->query("
            SELECT $primary_key
            FROM $tbl
            WHERE lft BETWEEN $lft AND $rgt
            AND rgt BETWEEN $lft AND $rgt
        ");
        $ids = array();
        while (list($id) = mysql_fetch_row($qid)) {
            $ids[] = $id;
        }

        // Update transversal numbers for all nodes to the rgt of the node being moved, taking in to account the absence of it's children.
        // This will temporarily "remove" the node from the tree, and its transversal values will be duplicated.
        $db->query("UPDATE $tbl SET lft = lft - $total_transversal_value WHERE lft > $rgt");
        $db->query("UPDATE $tbl SET rgt = rgt - $total_transversal_value WHERE rgt > $rgt");

        // Apply transformation to new parent rgt also.
        $new_parent_rgt = $new_parent_rgt > $rgt ? $new_parent_rgt - $total_transversal_value : $new_parent_rgt;

        // Update transversal values of moved node and children.
        $db->query("
            UPDATE $tbl SET
                lft = lft - ($lft - $new_parent_rgt),
                rgt = rgt - ($lft - $new_parent_rgt)
            WHERE $primary_key IN ('" . join("','", $ids) . "')
        ");

        // Update transversal values of all nodes to the rgt of moved node.
        $db->query("UPDATE $tbl SET lft = lft + $total_transversal_value WHERE lft >= $new_parent_rgt AND $primary_key NOT IN ('" . join("','", $ids) . "')");
        $db->query("UPDATE $tbl SET rgt = rgt + $total_transversal_value WHERE rgt >= $new_parent_rgt AND $primary_key NOT IN ('" . join("','", $ids) . "')");

        $app->logMsg(sprintf('Moved %s node %s to new parent %s.', $type, $name, $new_parent), LOG_INFO, __FILE__, __LINE__);
        return true;
    }

    // Alias functions for the different object types.
    public function moveRequestObject($name, $new_parent=null)
    {
        return $this->move($name, $new_parent, 'aro');
    }
    public function moveControlObject($name, $new_parent=null)
    {
        return $this->move($name, $new_parent, 'aco');
    }
    public function moveXtraObject($name, $new_parent=null)
    {
        return $this->move($name, $new_parent, 'axo');
    }

    /*
    * Add an entry to the acl_tbl to allow (or deny) a truple with the specified
    * ARO -> ACO -> AXO entry.
    *
    * @access   public
    * @param    string|null $aro Identifier of an existing ARO object (or null to use root).
    * @param    string|null $aco Identifier of an existing ACO object (or null to use root).
    * @param    string|null $axo Identifier of an existing AXO object (or null to use root).
    * @return   bool False on error, true on success.
    * @author   Quinn Comendant <quinn@strangecode.com>
    * @version  1.0
    * @since    15 Jun 2006 01:58:48
    */
    public function grant($aro=null, $aco=null, $axo=null, $access='allow')
    {
        $app =& App::getInstance();
        $db =& DB::getInstance();

        $this->initDB();

        // If any access objects are null, assume using root values.
        // However if they're empty we don't want to escalate the grant command to root!
        $aro = is_null($aro) ? 'root' : $aro;
        $aco = is_null($aco) ? 'root' : $aco;
        $axo = is_null($axo) ? 'root' : $axo;

        // Flush old cached values.
        $cache_hash = $aro . '|' . $aco . '|' . $axo;
        $this->cache->delete($cache_hash);

        // Ensure values exist.
        $qid = $db->query("SELECT aro_tbl.aro_id FROM aro_tbl WHERE aro_tbl.name = '" . $db->escapeString($aro) . "'");
        if (!list($aro_id) = mysql_fetch_row($qid)) {
            $app->logMsg(sprintf('Grant failed, aro_tbl.name = "%s" does not exist.', $aro), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }
        $qid = $db->query("SELECT aco_tbl.aco_id FROM aco_tbl WHERE aco_tbl.name = '" . $db->escapeString($aco) . "'");
        if (!list($aco_id) = mysql_fetch_row($qid)) {
            $app->logMsg(sprintf('Grant failed, aco_tbl.name = "%s" does not exist.', $aco), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }
        $qid = $db->query("SELECT axo_tbl.axo_id FROM axo_tbl WHERE axo_tbl.name = '" . $db->escapeString($axo) . "'");
        if (!list($axo_id) = mysql_fetch_row($qid)) {
            $app->logMsg(sprintf('Grant failed, axo_tbl.name = "%s" does not exist.', $axo), LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        // Access must be 'allow' or 'deny'.
        $allow = 'allow' == $access ? 'allow' : 'deny';

        $db->query("REPLACE INTO acl_tbl VALUES ('$aro_id', '$aco_id', '$axo_id', '$allow', NOW())");
        $app->logMsg(sprintf('Set %s: %s -> %s -> %s.', $allow, $aro, $aco, $axo), LOG_INFO, __FILE__, __LINE__);

        return true;
    }

    /*
    * Add an entry to the acl_tbl to deny a truple with the specified
    * ARO -> ACO -> AXO entry. This calls the ACL::grant function to create the entry
    * but uses 'deny' as the fourth argument.
    *
    * @access   public
    * @param    string|null $aro Identifier of an existing ARO object (or null to use root).
    * @param    string|null $aco Identifier of an existing ACO object (or null to use root).
    * @param    string|null $axo Identifier of an existing AXO object (or null to use root).
    * @return   bool False on error, true on success.
    * @author   Quinn Comendant <quinn@strangecode.com>
    * @version  1.0
    * @since    15 Jun 2006 04:35:54
    */
    public function revoke($aro=null, $aco=null, $axo=null)
    {
        return $this->grant($aro, $aco, $axo, 'deny');
    }

    /*
    * Delete an entry from the acl_tbl completely to allow other permissions to cascade down.
    * Null values act as a "wildcard" and will cause ALL matches in that column to be deleted.
    *
    * @access   public
    * @param    string|null $aro Identifier of an existing ARO object (or null for *).
    * @param    string|null $aco Identifier of an existing ACO object (or null for *).
    * @param    string|null $axo Identifier of an existing AXO object (or null for *).
    * @return   bool False on error, true on success.
    * @author   Quinn Comendant <quinn@strangecode.com>
    * @version  1.0
    * @since    20 Jun 2006 20:16:12
    */
    public function delete($aro=null, $aco=null, $axo=null)
    {
        $app =& App::getInstance();
        $db =& DB::getInstance();

        $this->initDB();

        // If any access objects are null, assume using root values.
        // However if they're empty we don't want to escalate the grant command to root!
        $where = array();
        $where[] = is_null($aro) ? "aro_tbl.name IS NOT NULL" : "aro_tbl.name = '" . $db->escapeString($aro) . "' ";
        $where[] = is_null($aco) ? "aco_tbl.name IS NOT NULL" : "aco_tbl.name = '" . $db->escapeString($aco) . "' ";
        $where[] = is_null($axo) ? "axo_tbl.name IS NOT NULL" : "axo_tbl.name = '" . $db->escapeString($axo) . "' ";

        // If any access objects are null, assume using root values.
        // However if they're empty we don't want to escalate the grant command to root!
        $aro = is_null($aro) ? 'root' : $aro;
        $aco = is_null($aco) ? 'root' : $aco;
        $axo = is_null($axo) ? 'root' : $axo;

        // Flush old cached values.
        $cache_hash = $aro . '|' . $aco . '|' . $axo;
        $this->cache->delete($cache_hash);

        $final_where = join(' AND ', $where);
        if (mb_substr_count($final_where, 'IS NOT NULL') == 3) {
            // Null on all three tables will delete ALL entries including the root -> root -> root = deny.
            $app->logMsg('Cannot allow deletion of ALL acl entries.', LOG_WARNING, __FILE__, __LINE__);
            return false;
        }

        $qid = $db->query("
            DELETE acl_tbl
            FROM acl_tbl
            LEFT JOIN aro_tbl ON (acl_tbl.aro_id = aro_tbl.aro_id)
            LEFT JOIN aco_tbl ON (acl_tbl.aco_id = aco_tbl.aco_id)
            LEFT JOIN axo_tbl ON (acl_tbl.axo_id = axo_tbl.axo_id)
            WHERE $final_where
        ");

        $app->logMsg(sprintf('Deleted %s acl_tbl links: %s -> %s -> %s', mysql_affected_rows($db->getDBH()), $aro, $aco, $axo), LOG_INFO, __FILE__, __LINE__);

        return true;
    }

    /*
    * Calculates the most specific cascading privilege found for a requested
    * ARO -> ACO -> AXO entry. Returns FALSE if the entry is denied. By default,
    * all entries are denied, unless some point in the hierarchy is set to "allow."
    *
    * @access   public
    * @param    string $aro Identifier of an existing ARO object.
    * @param    string $aco Identifier of an existing ACO object (or null to use root).
    * @param    string $axo Identifier of an existing AXO object (or null to use root).
    * @return   bool False if denied, true on allowed.
    * @author   Quinn Comendant <quinn@strangecode.com>
    * @version  1.0
    * @since    15 Jun 2006 03:58:23
    */
    public function check($aro, $aco=null, $axo=null)
    {
        $app =& App::getInstance();
        $db =& DB::getInstance();

        $this->initDB();

        // If any access objects are null or empty, assume using root values.
        $aro = is_null($aro) || '' == trim($aro) ? 'root' : $aro;
        $aco = is_null($aco) || '' == trim($aco) ? 'root' : $aco;
        $axo = is_null($axo) || '' == trim($axo) ? 'root' : $axo;

        $cache_hash = $aro . '|' . $aco . '|' . $axo;
        if ($this->cache->exists($cache_hash) && true === $this->getParam('enable_cache')) {
            // Access value is cached.
            $access = $this->cache->get($cache_hash);
        } else {
            // Retrieve access value from db.
            $qid = $db->query("
                SELECT acl_tbl.access
                FROM acl_tbl
                LEFT JOIN aro_tbl ON (acl_tbl.aro_id = aro_tbl.aro_id)
                LEFT JOIN aco_tbl ON (acl_tbl.aco_id = aco_tbl.aco_id)
                LEFT JOIN axo_tbl ON (acl_tbl.axo_id = axo_tbl.axo_id)
                WHERE (aro_tbl.lft <= (SELECT lft FROM aro_tbl WHERE name = '" . $db->escapeString($aro) . "') AND aro_tbl.rgt >= (SELECT rgt FROM aro_tbl WHERE name = '" . $db->escapeString($aro) . "'))
                AND (aco_tbl.lft <= (SELECT lft FROM aco_tbl WHERE name = '" . $db->escapeString($aco) . "') AND aco_tbl.rgt >= (SELECT rgt FROM aco_tbl WHERE name = '" . $db->escapeString($aco) . "'))
                AND (axo_tbl.lft <= (SELECT lft FROM axo_tbl WHERE name = '" . $db->escapeString($axo) . "') AND axo_tbl.rgt >= (SELECT rgt FROM axo_tbl WHERE name = '" . $db->escapeString($axo) . "'))
                ORDER BY aro_tbl.lft DESC, aco_tbl.lft DESC, axo_tbl.lft DESC
                LIMIT 1
            ");
            if (!list($access) = mysql_fetch_row($qid)) {
                $this->cache->set($cache_hash, 'deny');
                $app->logMsg(sprintf('Access denied: %s -> %s -> %s. No records found.', $aro, $aco, $axo), LOG_DEBUG, __FILE__, __LINE__);
                return false;
            }
            $this->cache->set($cache_hash, $access);
        }

        if ('allow' == $access) {
            $app->logMsg(sprintf('Access granted: %s -> %s -> %s.', $aro, $aco, $axo), LOG_DEBUG, __FILE__, __LINE__);
            return true;
        } else {
            $app->logMsg(sprintf('Access denied: %s -> %s -> %s.', $aro, $aco, $axo), LOG_DEBUG, __FILE__, __LINE__);
            return false;
        }
    }

    /*
    * Bounce user if they are denied access. Because this function calls dieURL() it must be called before any other HTTP header output.
    *
    * @access   public
    * @param    string $aro Identifier of an existing ARO object.
    * @param    string $aco Identifier of an existing ACO object (or null to use root).
    * @param    string $axo Identifier of an existing AXO object (or null to use root).
    * @param    string $message The text description of a message to raise.
    * @param    int    $type    The type of message: MSG_NOTICE,
    *                           MSG_SUCCESS, MSG_WARNING, or MSG_ERR.
    * @param    string $file    __FILE__.
    * @param    string $line    __LINE__.
    * @author   Quinn Comendant <quinn@strangecode.com>
    * @version  1.0
    * @since    20 Jan 2014 12:09:03
    */
    public function requireAllow($aro, $aco=null, $axo=null, $message='', $type=MSG_NOTICE, $file=null, $line=null)
    {
        $app =& App::getInstance();

        if (!$this->check($aro, $aco, $axo)) {
            $message = '' == trim($message) ? sprintf(_("Sorry, you have insufficient privileges for <em>%s %s</em>."), $aco, $axo) : $message;
            $app->raiseMsg($message, $type, $file, $line);
            $app->dieBoomerangURL();
        }
    }

} // End class.