Source for file lib_counters.php

<?php
/*
 * Lokorin.com
 * Copyright 2004-2006
 * Licensed under the GNU LGPL. See COPYING for full terms.
 */
/**
 * A library that contains everything that is connected to counters.
 * @author Andreas Launila
 * @version $Revision: 1.11 $
 * @package com.lokorin.lokorin.lib
 * @license http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
 */
 
/**
 * For access to common constants and functions.
 */
require_once('common.php');
 
/**
 * Gets the descriptions of all available counters.
 * @return array An array with the counters' unique identifiers as key and the
 *          corresponding descriptions as value.
 * @access public
 */
function getAllCounterDescriptions() {
    global $db;
    
    $fields = array('id');
    $rows = $db->querySelect(TABLE_COUNTERS, $fields);
    $descriptions = array();
    foreach($rows as $row) {
        $counter = new Counter($row['id']);
        $descriptions[$row['id']] = $counter->getDescription();
    }
    return $descriptions;
}
 
/**
 * Describes a counter which maintains a value that can be incremented by one.
 * @author Andreas Launila
 * @package com.lokorin.lokorin.lib
 */
class Counter extends TableEntry{
    /**
     * The number of hits that the counter has recorded.
     * @var integer 
     */
    private $hits;
    /**
     * The unix timestamp of the last hit that the counter recorded.
     * @var integer 
     */
    private $lastTimestamp;
    /**
     * The description of what the counter records.
     * @var string 
     */
    private $description;
    
    /**
     * Constructor for Counter.
     * @param integer $id The unique identifier for the counter. This parameter
     *          is optional, if it's not given then a new counter is created.
     */
    public function __construct($id = 0) {
        if($id === 0) {
            //Create a new counter.
            global $db;
            
            $vars = array(
                'hits'                => 0,
                'latest_timestamp'    => 0,
                'description'        => ''
            );
            $db->queryInsert(TABLE_COUNTERS, $vars);
            $id = $db->getLastInsertId();
        }
        
        //Get the counter's information.
        $fields = array(
            'hits', 
            'latest_timestamp', 
            'description'
        );
        parent::__construct(TABLE_COUNTERS, $id, $fields);
    }
    
    /**
     * @see com.lokorin.dfcrafters.TableEntry.readRow($row)
     */
    protected function readRow($row) {
        $this->hits = $row['hits'];
        $this->lastTimestamp = $row['latest_timestamp'];
        $this->description = $row['description'];
    }
    
    /**
     * Records that a hit has occured. Increments the counter.
     * @access public
     */
    public function recordHit() {
        $this->hits++;
        $this->lastTimestamp = time();
        $this->save();
    }
    
    /**
     * Saves the current information held by the counter. This public function should
     * be concidered private.
     * @access private
     */
    public function save() {
        global $db;
        
        $vars = array(
            'hits'                => $this->hits,
            'latest_timestamp'    => $this->lastTimestamp,
            'description'        => $this->description
        );
        $idFields = array(
            'id'    => parent::$this->getId()
        );
        $db->queryUpdate(TABLE_COUNTERS, $vars, $db->buildsqlSelector($idFields));
    }
    
    /**
     * Sets the counters description to a new value.
     * @param string $newDescription The new description that should be used
     *          for the counter. This description should describe what the counter
     *          records.
     * @access public
     */
    public function setDescription($newDescription) {
        $this->description = $newDescription;
        $this->save();
    }
    
    /**
     * Gets the counter's description. The description describes what the
     * counter is recording.
     * @return string A description.
     * @access public
     */
    public function getDescription() {
        return $this->description;
    }
    
    /**
     * Gets the number of hits that have been recorded by the counter.
     * @return integer A non-negative number describing the number of recorded
     *          hits.
     * @access public
     */
    function getHits() {
        return $this->hits;
    }
}
?>