root/tags/1.0/phptagengine.class.inc.php

<?php

// Copyright (c) 2006-2007 Alex King. All rights reserved.
// http://alexking.org/projects/php-tag-engine
//
// Released under the LGPL license
// http://www.opensource.org/licenses/lgpl-license.php
//
// **********************************************************************
// This program 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. 
// **********************************************************************

/**
 * This file contains the PHP Tag Engine class definition.
 * 
 * @package phptagengine
 */

if (__FILE__ == basename($_SERVER['SCRIPT_NAME'])) { die(); }

/**
 * The phptagengine class, all the good stuff happens here.
 * 
 * @package phptagengine
 */
class phptagengine {
        /**
         * set to global $ADOdb instance
         * @var mixed
         */
        var $db;
        /**
         * Column name escape string for the database being used. Checks for: mysql, postgres7, mssql
         *
         * @var string
         */
        var $db_col_escape_char;
        /**
         * Name of the tags table in the database
         *
         * @var string
         */
        var $table_tags;
        /**
         * Name of the tag names table in the database
         *
         * @var string
         */
        var $table_tag_names;
        /**
         * Name of the users table in the database
         *
         * @var string
         */
        var $table_users;
        /**
         * The display name column (normally name or username) in the users table in the database
         *
         * @var string
         */
        var $table_users_name;
        /**
         * URL to the PHP Tag Engine folder, include the trailing slash
         *
         * @var string
         */
        var $base_url;
        /**
         * URL of the file handling AJAX requests
         *
         * @var string
         */
        var $ajax_handler;
        /**
         * Name of language file to include - languages/(language).inc.php
         *
         * @var string
         */
        var $language;
        /**
         * Character set
         *
         * @var string
         */
        var $charset;
        /**
         * Array of strings for localization
         *
         * @var array
         */
        var $strings;
        /**
         * Value to be used if no type is passed in, useful if you only have one 
         * type of object you are tagging and just need a default value
         *
         * @var string
         */
        var $default_type;
        /**
         * Value to be used if no user is passed in, useful if you are not tracking 
         * tags by user and just need a default value
         *
         * @var string
         */
        var $default_user;
        /**
         * URL for browsing items by tag, includes token replacement for tag, type
         * 
         * example: http://example.com/index.php?view=tag&tag=<tag>&type=<type>
         *
         * @var string
         */
        var $tag_browse_url;
        /**
         * Show an X next to each tag to allow removal of that tag 
         *
         * @var boolean
         */
        var $show_remove_links;
        /**
         * Show text or image?
         * 
         * example: 'text' - uses @link phptagengine::$strings
         * example: 'image'
         *
         * @var string
         */
        var $edit_button_display;
        /**
         * URL of the image for the edit button
         *
         * @var string
         */
        var $edit_button_image_url;
        /**
         * Show text or image?
         * 
         * example: 'text' - uses @link phptagengine::$strings
         * example: 'image'
         *
         * @var string
         */
        var $delete_button_display;
        /**
         * URL of the image for the delete button
         *
         * @var string
         */
        var $delete_button_image_url;
        /**
         * Stores arrays of tags for items, use as a cache to reduce queries 
         *
         * @var array
         */
        var $item_tags_cache;
        /**
         * Enable Yahoo! Auto-Complete
         *
         * @var boolean
         */
        var $yac;
        /**
         * List of Yahoo! UI Pattern files to be included, in case Yahoo! UI Patterns are already in use elsewhere and we don't want to duplicate their inclusion. The array should contain filenames in the 'yui' directory.
         * 
         * Note: order matters in this list.
         *
         * @var array
         */
        var $yac_files;
        /**
         * PHP Tag Engine Version
         *
         * @var string
         */
        var $version;
        
        /**
         * Initializes the class
         *
         * @return phptagengine
         */
        function phptagengine() {
                $this->base_url = 'http://example.com/';
                $this->ajax_handler = 'http://example.com/ajax.php';
                $this->language = 'english';
                $this->charset = 'UTF-8';
                $this->db_type = 'mysql';
                $this->strings = array();
                $this->tag_browse_url = 'http://example.com/index.php?view=tags&tag=<tag>&type=<type>';
                $this->default_type = '';
                $this->default_user = 1;
                $this->edit_button_display = 'text';
                $this->delete_button_display = 'text';
                $this->yac = true;
                $this->yac_files = array(
                        'yahoo.js'
                        ,'dom.js'
                        ,'event.js'
                        ,'autocomplete.js'
                );
                $this->version = '1.0';
        }
        
        /**
         * Sets the character used for escaping column names for the database type in use
         */
        function set_db_col_escape_char() {
                switch ($this->db->databaseType) {
                        case 'mysql':
                                $this->db_col_escape_char = '`';
                                break;
                        case 'postgres7':
                        case 'mssql':
                                $this->db_col_escape_char = '"';
                                break;
                }
        }

        /**
         * Sets the type or user property to the default value if the value is 
         * null, could be extended in the future
         * @param string $prop expected 'type' or 'user'
         * @param mixed $value if this is null, we set the default
         */
        function default_value($prop, $value) {
                if ($value == null && in_array($prop, array('type', 'user'))) {
                        eval('$value = $this->default_'.$prop.';');
                }
                return $value;
        }
        
        /**
         * Set a tag to lowercase and remove spaces, could be extended in the future
         * @param mixed $value the value to be normalized
         * @param string $type the type of value, used for the switch statement
         * @return mixed
         */
        function normalize($value, $type = 'tag') {
                switch ($type) {
                        case 'tag':
                                $value = preg_replace('|[^a-z0-9_.\-@#$%*!&]|i', '', strtolower($value));
                                break;
                }
                return $value;
        }

        /**
         * Does a tag already exist
         *
         * @uses phptagengine::get_tag_id()
         * 
         * @param string $tag
         * @return boolean
         */
        function tag_exists($tag) {
                if ($this->get_tag_id($tag) != false) {
                        return true;
                }
                else {
                        return false;
                }
        }

        /**
         * Creates a new tag (noramlized) in the database, returns the ID of the 
         * created tag or false
         *
         * @uses phptagengine::normalize() to normalize the $tag
         * @uses phptagengine::tag_exists() to see if the tag needs creating
         * 
         * @param string $tag
         * @return mixed
         */
        function create_tag($tag = null) {
                if ($tag == null) {
                        return false;
                }
                $tag = $this->normalize($tag);
                if (strlen($tag) < 1) {
                        return false;
                }
                $test = $this->get_tag_id($tag);
                if ($test != false) {
                        return $test;
                }
                $result = $this->db->Execute("
                        INSERT
                        INTO $this->table_tag_names
                        ( ".$this->db_col_escape_char."name".$this->db_col_escape_char."
                        )
                        VALUES 
                        ( ".$this->db->qstr($tag)."                     
                        )
                ") or die($this->db->ErrorMsg().' in '.__FILE__);
                
                if ($result) {
                        $id = false;
                        if (strstr($this->db->databaseType, 'postgres')) {
                                $id = $this->db->GetOne("
                                        SELECT CURRVAL('".$this->table_tag_names."_id_seq') as id
                                ") or die($this->db->ErrorMsg());
                        }
                        else {
                                $id = $this->db->Insert_ID();
                        }
                        return $id;
                }
                
                return false;
        }

        /**
         * Adds a tag to an item, creates the tag if needed
         *
         * @uses phptagengine::default_value() to set a default value for $type and $user if needed
         * @uses phptagengine::create_tag() to create a new tag or get the id of the existing tag
         * 
         * @param string $user user creating the tag
         * @param string $item item being tagged
         * @param string $tag tag being used
         * @param string $type type of item being tagged
         * @return boolean
         */
        function add_tag($user = null, $item = null, $tag = null, $type = null) {
                if ($item == null || $tag == null) {
                        return false;
                }
                $type = $this->default_value('type', $type);
                $user = $this->default_value('user', $user);
                $tag_id = $this->create_tag($tag);
                if ($tag_id == false) {
                        return false;
                }
                if ($this->item_tag_exists($user, $item, $tag, $type)) {
                        return true;
                }
                else {
                        $this->set_db_col_escape_char();
                        $result = $this->db->Execute("
                                INSERT
                                INTO $this->table_tags
                                ( ".$this->db_col_escape_char."user".$this->db_col_escape_char."
                                , ".$this->db_col_escape_char."item".$this->db_col_escape_char."
                                , ".$this->db_col_escape_char."type".$this->db_col_escape_char."
                                , ".$this->db_col_escape_char."tag".$this->db_col_escape_char."
                                , ".$this->db_col_escape_char."date".$this->db_col_escape_char."
                                )
                                VALUES
                                ( ".$this->db->qstr($user)."
                                , ".$this->db->qstr($item)."
                                , ".$this->db->qstr($type)."
                                , ".$this->db->qstr($tag_id)."
                                , ".$this->db->DBDate(date("Y-m-d H:i:s"))."
                                )
                        ") or die($this->db->ErrorMsg().' in '.__FILE__);
                        if ($result) {
                                return true;
                        }
                }
                return false;
        }

        /**
         * Save item tags
         *
         * @param string $item
         * @param string $tags
         * @param string $type
         * @param string $user
         * 
         * @return array key success is 'y/n', key tags is an arra of the item's tags
         */
        function save_tags($item, $tags, $type = null, $user = null) {
                $type = $this->default_value('type', $type);
                $user = $this->default_value('user', $user);
                $old_tags = $this->get_tags($item, $type, $user);
                $new_tags = array();
                $success = 'y';
                if ($tags != null && $tags != '') {
                        $tags = explode(' ', $tags);
                        $tags = array_unique($tags);
                        natcasesort($tags);
                        reset($tags);
                        if (count($tags) > 0) {
                                foreach ($tags as $tag) {
                                        if ($tag != '') {
                                                if ($this->add_tag($user, $item, $tag, $type)) {
                                                        $new_tags[] = $this->normalize($tag);
                                                }
                                                else {
                                                        $success = 'n';
                                                }
                                        }
                                }
                                if (count($new_tags) > 0) {
                                        $tags = implode(' ', $new_tags);
                                }
                        }
                }
                if (count($old_tags) > 0) {
                        foreach ($old_tags as $id => $tag) {
                                if (!in_array($tag, $new_tags)) {
                                        if (!$this->remove_tag_by_id(str_replace('id_', '', $id))) {
                                                $success = 'n';
                                        }
                                }
                        }
                }
                $result = array(
                        'success' => $success
                        , 'tags' => $new_tags
                );
                return $result;
        }
        

        /**
         * Removes a tag
         * 
         * @uses phptagengine::get_item_tag_id()
         * @uses phptagengine::remove_tag_by_id()
         *
         * @param string $item
         * @param string $tag
         * @param string $user
         * @param string $type
         * @return boolean
         */
        function remove_tag($item = null, $tag = null, $user = null, $type = null) {
                $id = $this->get_item_tag_id($user, $item, $tag, $type);
                return $this->remove_tag_by_id($id);
        }

        /**
         * Removes a tag by id
         * 
         * @param integer $id
         * @return boolean
         */
        function remove_tag_by_id($id) {
                if ($id == null) {
                        return false;
                }
                $result = $this->db->Execute("
                        DELETE
                        FROM $this->table_tags
                        WHERE id = ".$this->db->qstr($id)."
                ") or die($this->db->ErrorMsg().' in '.__FILE__);
                if ($result) {
                        return true;
                }
                return false;
        }
        
        /**
         * Gets the tags for an item
         *
         * @param string $item
         * @param string $type
         * @param string $user
         * @param boolean $use_cache
         * @return array
         */
        function get_tags($item = null, $type = null, $user = null, $use_cache = false) {
                if ($item == null) {
                        return false;
                }
                $tags = array();
                if ($use_cache) {
                        if (isset($this->item_tags_cache['item_'.$item])) {
                                $tags = $this->item_tags_cache['item_'.$item];
                        }
                        return $tags;
                }
                $where = '';
                if ($user != null) {
                        $where .= ' AND t.user = '.$this->db->qstr($user);
                }
                if ($item != null) {
                        $where .= ' AND t.item = '.$this->db->qstr($item);
                }
                if ($type != null) {
                        $where .= ' AND t.type = '.$this->db->qstr($type);
                }
                if ($where == '') {
                        return false;
                }
                $result = $this->db->Execute("
                        SELECT t.id AS ID
                        , tn.name AS NAME
                        FROM $this->table_tags t
                        JOIN $this->table_tag_names tn
                        ON t.tag = tn.id
                        WHERE 1 = 1
                        $where
                        ORDER BY tn.name
                ") or die($this->db->ErrorMsg().' in '.__FILE__);
                if ($result && $result->RowCount() > 0) {
                        while ($data = $result->FetchNextObject()) {
                                $tags['id_'.$data->ID] = $data->NAME;
                        }
                }
                return $tags;
        }
        
        /**
         * Completely removes a tag from the system (from @link phptagengine::$table_tags and @link phptagengine::$table_tag_names)
         *
         * @param string $tag
         * @return boolean
         */
        function delete_tag($tag = null) {
                if (is_null($tag) || strstr($tag, ' ')) {
                        return false;
                }
                $tag_id = $this->get_tag_id($tag);
                if ($tag_id == false) {
                        return false;
                }
                $result = $this->db->Execute("
                        DELETE
                        FROM $this->table_tags
                        WHERE tag = '$tag_id'
                ") or die($this->db->ErrorMsg().' in '.__FILE__);
                if (!$result) {
                        return false;
                }
                $result = $this->db->Execute("
                        DELETE
                        FROM $this->table_tag_names
                        WHERE id = '$tag_id'
                ") or die($this->db->ErrorMsg().' in '.__FILE__);
                if (!$result) {
                        return false;
                }
                return true;
        }
        
        /**
         * Changes the name of a tag, or consolidates two existing tags
         *
         * @param string $old_tag
         * @param string $new_tag
         * @return boolean
         */
        function edit_tag($old_tag = null, $new_tag = null) {
                if (is_null($old_tag) || is_null($new_tag) || strstr($new_tag, ' ')) {
                        return false;
                }
                if ($old_tag == $new_tag