Fontaine でよく使っているクラスを紹介する。データベースのテーブルを単に連想配列として扱う PHP クラスだ。トランザクション処理はしないので、直接データベース・アダプタからトランザクション処理をする必要はある。あまりに使いすぎてるため、致命的な欠陥があれば指摘していただきたい。（というのも値の取得時に同時アクセスがあったときが怪しい。）

入力値のサニテーションは Zend_Db_Adapter_Abstract が行うことを前提にしている。

例えば次のようなテーブルを考える。

CREATE TABLE IF NOT EXISTS dictionary (
    name  TEXT PRIMARY KEY,
    value TEXT
);

そのテーブルをこう扱うことができる。

<?php

// Given $db
$dictionary = new Fontaine_Db_Dictionary(array(
    'db'            => $db,
    'name'          => 'dictionary',
    'primary'       => 'name',
    'valueColumn'   => 'value'
));

$adapter = $dictionary->getAdapter();
$adapter->beginTransaction();
try {
    $dictionary->keyForStringValue  = 'string';
    $dictionary->keyForBooleanValue = true;
    $dictionary->keyForIntegerValue = 0xffff;
    $dictionary->keyForFloatValue   = M_PI;
    $dictionary->keyForArrayValue   = array('value1', 'value2');
    $adapter->commit();
    
} catch (Exception $e) {
    $adapter->rollBack();
    // TODO: Deal with error
}

// Output: string(6) "string"
var_dump($dictionary->keyForStringValue);
// Output: bool(true)
var_dump($dictionary->keyForBooleanValue);
// Output: int(65535)
var_dump($dictionary->keyForIntegerValue);
// Output: float(3.1415926535898)
var_dump($dictionary->keyForFloatValue);
// Output: array(2) { [0]=> string(6) "value1" [1]=> string(6) "value2" }
var_dump($dictionary->keyForArrayValue);

以下、クラス定義全文。Fontaine_Db_Dictionary_Interface はヘッダファイルの無い PHP のクラス定義を明確にするためのインタフェースだ。Fontaine_Db_Dictionary_Interface は ArrayAccess を継承している。

<?php
/**
 * Fontaine Library
 * 
 * @category  Fontaine
 * @package   Fontaine_Db
 * @author    Matsuda Shota
 * @copyright (c) 2010 Matsuda Shota
 * @license   http://www.opensource.org/licenses/bsd-license.php
 */


/**
 * @see Fontaine_Db_Dictionary_Interface
 */
require_once 'Fontaine/Db/Dictionary/Interface.php';


/**
 * @see Zend_Db_Table_Abstract
 */
require_once 'Zend/Db/Table/Abstract.php';


/**
 * @category  Fontaine
 * @package   Fontaine_Db
 * @author    Matsuda Shota
 * @copyright (c) 2010 Matsuda Shota
 * @license   http://www.opensource.org/licenses/bsd-license.php
 */
class Fontaine_Db_Dictionary
extends Zend_Db_Table_Abstract
implements Fontaine_Db_Dictionary_Interface
{
    /**
     * @var string
     */
    const VALUE_COLUMN = 'valueColumn';
    
    /**
     * @var string
     */
    protected $_valueColumn = null;
    
    /**
     * @param   array $config
     * @return  void
     * @see     Zend_Db_Table_Abstract::__construct()
     */
    public function __construct($config)
    {
        parent::__construct($config);
    }
    
    /**
     * @param   array $options
     * @return  Zend_Db_Table_Abstract
     * @see     Zend_Db_Table_Abstract::setOptions()
     */
    public function setOptions(array $options)
    {
        foreach ($options as $key => $value) {
            switch ($key) {
                case self::VALUE_COLUMN:
                    $this->_valueColumn = $value;
                    break;
            }
        }
        return parent::setOptions($options);
    }
    
    /**
     * @return  void
     * @throws  Fontaine_Db_Exception
     */
    protected function _setupValueColumn()
    {
        if ($this->_valueColumn === null) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("The name of the value column does not specified.");
        }
        $tableDescription = $this->getAdapter()->describeTable($this->_name);
        if (!isset($tableDescription[$this->_valueColumn])) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("The value column \"{$this->_valueColumn}\" does not exist.");
        }
    }
    
    /**
     * @param   string $primaryKey
     * @return  Zend_Db_Table_Row|null
     * @throws  Fontaine_Db_Exception
     */
    private function _fetchSingleRow($primaryKey)
    {
        $fetchedRow  = null;
        $rowset      = $this->find($primaryKey);
        $rowsetCount = $rowset->count();
        
        if ($rowsetCount == 1) {
            $fetchedRow = $rowset->current();
        
        } else if ($rowsetCount > 1) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("Detected violation error -- found multiple rows corresponding to the given primary key: $primaryKey");
        }
        
        // This returns null when this dictionary does not have the given key
        return $fetchedRow;
    }
    
    /**
     * @return  string
     * @throws  Fontaine_Db_Exception
     */
    private function _primaryColumn()
    {
        // Check if we have multiple primary key columns
        $primaryCount = count($this->_primary);
        if ($primaryCount > 1) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("A dictionary table should have only one primary key. $primaryCount found.");
        }
        
        return reset($this->_primary);
    }
    
    /**
     * @param   string $value
     * @return  mixed
     * @throws  Fontaine_Db_Exception
     */
    protected function _wakeupValue($value)
    {
        $unserializedValue = @unserialize($value);
        if ($unserializedValue === null) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("Unable to wakeup the given value.");
        }
        return $unserializedValue;
    }
    
    /**
     * @param   mixed $value
     * @return  string
     * @throws  Fontaine_Db_Exception
     */
    protected function _sleepValue($value)
    {
        if (is_resource($value)) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("Unable to sleep the value -- resource type of value given.");
        }
        if (is_null($value)) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("Unable to sleep the value -- null value given.");
        }
        
        $serializedValue = @serialize($value);
        if ($serializedValue === null) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("Unable to sleep the given value.");
        }
        return $serializedValue;
    }
    
    /**
     * @param   string $key
     * @return  mixed|null
     * @see     Fontaine_Db_Dictionary_Interface::get()
     */
    public function get($key)
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        $value = null;
        $fetchedRow = $this->_fetchSingleRow($key);
        if ($fetchedRow) {
            $value = $this->_wakeupValue($fetchedRow[$this->_valueColumn]);
        }
        
        // This returns null when this dictionary does not have the given key
        return $value;
    }
    
    /**
     * @param   string $key
     * @param   mixed $value
     * @return  Fontaine_Db_Dictionary_Interface
     * @see     Fontaine_Db_Dictionary_Interface::set()
     */
    public function set($key, $value)
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        $fetchedRow = $this->_fetchSingleRow($key);
        if (!$fetchedRow) {
            // Create a new row with the given key as our primary key
            $primaryColumn = $this->_primaryColumn();
            $fetchedRow = $this->createRow();
            $fetchedRow[$primaryColumn] = $key;
        }
        
        $fetchedRow[$this->_valueColumn] = $this->_sleepValue($value);
        $fetchedRow->save();
        
        return $this;
    }
    
    /**
     * @param   array|Traversable $dictionary
     * @return  Fontaine_Db_Dictionary_Interface
     * @throws  Fontaine_Db_Exception
     * @see     Fontaine_Db_Dictionary_Interface::setAll()
     */
    public function setAll($dictionary)
    {
        if (!is_array($dictionary) && !$dictionary instanceof Traversable) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("The argument should be traversable.");
        }
        
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        foreach ($dictionary as $eachKey => $eachValue) {
            $fetchedRow = $this->_fetchSingleRow($eachKey);
            if (!$fetchedRow) {
                // Create a new row with the given key as our primary key
                $primaryColumn = $this->_primaryColumn();
                $fetchedRow = $this->createRow();
                $fetchedRow[$primaryColumn] = $eachKey;
            }
            
            $fetchedRow[$this->_valueColumn] = $this->_sleepValue($eachValue);
            $fetchedRow->save();
        }
        
        return $this;
    }
    
    /**
     * @param   string $key
     * @return  boolean
     * @see     Fontaine_Db_Dictionary_Interface::hasKey()
     */
    public function hasKey($key)
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        return $this->_fetchSingleRow($key) !== null;
    }
    
    /**
     * @param   array|Traversable $keys
     * @return  boolean
     * @throws  Fontaine_Db_Exception
     * @see     Fontaine_Db_Dictionary_Interface::hasAllKeys()
     */
    public function hasAllKeys($keys)
    {
        if (!is_array($keys) && !$keys instanceof Traversable) {
            require_once 'Fontaine/Db/Exception.php';
            throw new Fontaine_Db_Exception("The argument should be traversable.");
        }
        
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        foreach ($keys as $eachKey) {
            if (!$this->_fetchSingleRow($eachKey)) {
                return false;
            }
        }
        
        return true;
    }
    
    /**
     * @param   string $key
     * @return  Fontaine_Db_Dictionary_Interface
     * @see     Fontaine_Db_Dictionary_Interface::remove()
     */
    public function remove($key)
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        $fetchedRow = $this->_fetchSingleRow($key);
        if ($fetchedRow) {
            $fetchedRow->delete();
        }
        
        return $this;
    }
    
    /**
     * @param   array|Traversable|null $keys
     * @return  Fontaine_Db_Dictionary_Interface
     * @throws  Fontaine_Db_Exception
     * @see     Fontaine_Db_Dictionary_Interface::removeAll()
     */
    public function removeAll($keys = null)
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        if ($keys === null) {
            $fetchedRows = $this->fetchAll();
            foreach ($fetchedRows as $eachRow) {
                $eachRow->delete();
            }
        } else {
            if (!is_array($keys) && !$keys instanceof Traversable) {
                require_once 'Fontaine/Db/Exception.php';
                throw new Fontaine_Db_Exception("The argument should be traversable.");
            }
            
            foreach ($keys as $eachKey) {
                $fetchedRow = $this->_fetchSingleRow($eachKey);
                if ($fetchedRow) {
                    $fetchedRow->delete();
                }
            }
        }
        
        return true;
    }
    
    /**
     * @return  boolean
     * @see     Fontaine_Db_Dictionary_Interface::isEmpty()
     */
    public function isEmpty()
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        return $this->fetchAll()->count() == 0;
    }
    
    /**
     * @return  array
     * @see     Fontaine_Db_Dictionary_Interface::toValueArray()
     */
    public function toValueArray()
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        $resultArray   = array();
        $primaryColumn = $this->_primaryColumn();
        $fetchedRowset = $this->fetchAll();
        
        foreach ($fetchedRowset as $eachRow) {
            $resultArray[] = $this->_wakeupValue($eachRow[$this->_valueColumn]);
        }
        
        return $resultArray;
    }
    
    /**
     * @return  array
     * @see     Fontaine_Db_Dictionary_Interface::toKeyArray()
     */
    public function toKeyArray()
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        $resultArray   = array();
        $primaryColumn = $this->_primaryColumn();
        $fetchedRowset = $this->fetchAll();
        
        foreach ($fetchedRowset as $eachRow) {
            $resultArray[] = $eachRow[$primaryColumn];
        }
        
        return $resultArray;
    }
    
    /**
     * @return  array
     * @see     Fontaine_Db_Dictionary_Interface::toArray()
     */
    public function toArray()
    {
        $this->_setupPrimaryKey();
        $this->_setupValueColumn();
        
        $resultArray   = array();
        $primaryColumn = $this->_primaryColumn();
        $fetchedRowset = $this->fetchAll();
        
        foreach ($fetchedRowset as $eachRow) {
            $eachKey   = $eachRow[$primaryColumn];
            $eachValue = $this->_wakeupValue($eachRow[$this->_valueColumn]);
            $resultArray[$eachKey] = $eachValue;
        }
        
        return $resultArray;
    }
    
    /**
     * @param   string $name
     * @return  boolean
     * @see     Fontaine_Db_Dictionary_Interface::__isset()
     * @uses    Fontaine_Db_Dictionary_Interface::hasKey()
     */
    public function __isset($name)
    {
        return $this->hasKey($name);
    }
    
    /**
     * @param   string $name
     * @return  mixed
     * @see     Fontaine_Db_Dictionary_Interface::__get()
     * @uses    Fontaine_Db_Dictionary_Interface::get()
     */
    public function __get($name)
    {
        return $this->get($name);
    }
    
    /**
     * @param   string $name
     * @param   mixed $value
     * @return  mixed
     * @see     Fontaine_Db_Dictionary_Interface::__set()
     * @uses    Fontaine_Db_Dictionary_Interface::set()
     */
    public function __set($name, $value)
    {
        $this->set($name, $value);
        return $value;
    }
    
    /**
     * @param   string $name
     * @see     Fontaine_Db_Dictionary_Interface::__unset()
     * @uses    Fontaine_Db_Dictionary_Interface::remove()
     */
    public function __unset($name)
    {
        $this->remove($name);
    }
    
    /**
     * @param   string $offset
     * @return  boolean
     * @see     ArrayAccess::offsetExists()
     * @uses    Fontaine_Db_Dictionary_Interface::hasKey()
     */
    public function offsetExists($offset)
    {
        return $this->hasKey($offset);
    }
    
    /**
     * @param   string $offset
     * @return  mixed
     * @see     ArrayAccess::offsetGet()
     * @uses    Fontaine_Db_Dictionary_Interface::get()
     */
    public function offsetGet($offset)
    {
        return $this->get($offset);
    }
    
    /**
     * @param   string $offset
     * @param   mixed $value
     * @return  mixed
     * @see     ArrayAccess::offsetSet()
     * @uses    Fontaine_Db_Dictionary_Interface::set()
     */
    public function offsetSet($offset, $value)
    {
        $this->set($offset, $value);
        return $value;
    }
    
    /**
     * @param   string $offset
     * @see     ArrayAccess::offsetUnset()
     * @uses    Fontaine_Db_Dictionary_Interface::remove()
     */
    public function offsetUnset($offset)
    {
        $this->remove($offset);
    }
}