git.roojs.org Git - pear/blob - Translation2/Admin.php

   1 <?php
   2 /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
   3
   4 /**
   5  * Contains the Translation2_Admin base class
   6  *
   7  * PHP versions 4 and 5
   8  *
   9  * LICENSE: Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted provided that the following conditions are met:
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in the
  15  *    documentation and/or other materials provided with the distribution.
  16  * 3. The name of the author may not be used to endorse or promote products
  17  *    derived from this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED
  20  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  21  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  22  * IN NO EVENT SHALL THE FREEBSD PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY
  23  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  26  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  *
  30  * @category  Internationalization
  31  * @package   Translation2
  32  * @author    Lorenzo Alberton <l.alberton@quipo.it>
  33  * @copyright 2004-2005 Lorenzo Alberton
  34  * @license   http://www.debian.org/misc/bsd.license  BSD License (3 Clause)
  35  * @version   CVS: $Id: Admin.php 305985 2010-12-05 22:55:33Z clockwerx $
  36  * @link      http://pear.php.net/package/Translation2
  37  */
  38
  39 /**
  40  * require Translation2 base class
  41  */
  42 require_once 'Translation2.php';
  43
  44 /**
  45  * Administration utilities for translation string management
  46  *
  47  * Set of methods to easily add/remove languages and strings,
  48  * with a common API for all the containers.
  49  *
  50  * @category  Internationalization
  51  * @package   Translation2
  52  * @author    Lorenzo Alberton <l.alberton@quipo.it>
  53  * @copyright 2004-2005 Lorenzo Alberton
  54  * @license   http://www.debian.org/misc/bsd.license  BSD License (3 Clause)
  55  * @link      http://pear.php.net/package/Translation2
  56  */
  57 class Translation2_Admin extends Translation2
  58 {
  59     // {{{ class vars
  60
  61     // }}}
  62     // {{{ factory()
  63
  64     /**
  65      * Return a Translation2_Admin instance already initialized
  66      *
  67      * @param string $driver  Type of the storage driver
  68      * @param mixed  $options Additional options for the storage driver
  69      *                        (example: if you are using DB as the storage
  70      *                        driver, you have to pass the DSN string here)
  71      * @param array  $params  Array of parameters for the adapter class
  72      *                        (i.e. you can set here the mappings between your
  73      *                        table/field names and the ones used by this class)
  74      *
  75      * @return object Translation2 instance or PEAR_Error on failure
  76      * @access public
  77      * @static
  78      */
  79     function & factory($driver, $options = '', $params = array())
  80     {
  81         $tr = new Translation2_Admin;
  82         $tr->storage = Translation2_Admin::_storageFactory($driver, $options);
  83         if (PEAR::isError($tr->storage)) {
  84             return $tr->storage;
  85         }
  86         $tr->_setDefaultOptions();
  87         $tr->_parseOptions($params);
  88         $tr->storage->_parseOptions($params);
  89         return $tr;
  90     }
  91
  92     // }}}
  93     // {{{ _storageFactory()
  94
  95     /**
  96      * Return a storage driver based on $driver and $options
  97      *
  98      * Override Translation2::_storageFactory()
  99      *
 100      * @param string $driver  Type of storage class to return
 101      * @param string $options Optional parameters for the storage class
 102      *
 103      * @return object Object Storage object
 104      * @access private
 105      * @static
 106      */
 107     function & _storageFactory($driver, $options = '')
 108     {
 109         if (is_object($driver)) {
 110             return $driver;
 111         }
 112         $storage_path  = 'Translation2/Admin/Container/'.strtolower($driver).'.php';
 113         $storage_class = 'Translation2_Admin_Container_'.strtolower($driver);
 114         include_once $storage_path;
 115         $storage = new $storage_class;
 116         $err = $storage->init($options);
 117         if (PEAR::isError($err)) {
 118             return $err;
 119         }
 120         return $storage;
 121     }
 122
 123     // }}}
 124     // {{{ _setDefaultOptions()
 125
 126     /**
 127      * Set some default options
 128      *
 129      * @return void
 130      * @access private
 131      */
 132     function _setDefaultOptions()
 133     {
 134         $this->options['autoCleanCache'] = false;
 135         $this->options['cacheOptions']   = array('defaultGroup' => 'Translation2');
 136         parent::_setDefaultOptions();
 137     }
 138
 139     // }}}
 140     // {{{ getAdminDecorator()
 141
 142     /**
 143      * Return an instance of an admin decorator
 144      *
 145      * @param string $decorator Name of the decorator
 146      *
 147      * @return object Decorator object reference
 148      * @see    Translation2::getDecorator()
 149      * @access public
 150      */
 151     function &getAdminDecorator($decorator)
 152     {
 153         $decorator_path  = 'Translation2/Admin/Decorator/'.$decorator.'.php';
 154         $decorator_class = 'Translation2_Admin_Decorator_'.$decorator;
 155         include_once $decorator_path;
 156         if (func_num_args() > 1) {
 157             $obj =& func_get_arg(1);
 158             $ret = new $decorator_class($obj);
 159         } else {
 160             $ret = new $decorator_class($this);
 161         }
 162         return $ret;
 163     }
 164
 165     // }}}
 166     // {{{ addLang
 167
 168     /**
 169      * Prepare the storage container for a new lang.
 170      * If the langsAvail table doesn't exist yet, it is created.
 171      *
 172      * @param array $langData array('lang_id'    => 'en',
 173      *                              'table_name' => 'i18n',
 174      *                              'name'       => 'english',
 175      *                              'meta'       => 'some meta info',
 176      *                              'error_text' => 'not available');
 177      * @param array $options  array('charset'   => 'utf8',
 178      *                              'collation' => 'utf8_general_ci');
 179      *
 180      * @return mixed true on success, PEAR_Error on failure
 181      */
 182     function addLang($langData, $options = array())
 183     {
 184         $res = $this->storage->addLang($langData, $options);
 185         if (PEAR::isError($res)) {
 186             return $res;
 187         }
 188         $res = $this->storage->addLangToList($langData);
 189         if (PEAR::isError($res)) {
 190             return $res;
 191         }
 192         $this->storage->fetchLangs(); //update local cache
 193         if ($this->options['autoCleanCache']) {
 194             $this->cleanCache();
 195         }
 196         return true;
 197     }
 198
 199     // }}}
 200     // {{{ removeLang
 201
 202     /**
 203      * Remove the lang from the langsAvail table and drop the strings table.
 204      * If the strings table holds other langs and $force==false, then
 205      * only the lang column is dropped. If $force==true the whole
 206      * table is dropped without any check
 207      *
 208      * @param string  $langID language ID
 209      * @param boolean $force  remove the language info without further checks
 210      *
 211      * @return mixed true on success, PEAR_Error on failure
 212      */
 213     function removeLang($langID = null, $force = false)
 214     {
 215         if (is_null($langID)) {
 216             //return error
 217         }
 218         $res = $this->storage->removeLang($langID, $force);
 219         if (PEAR::isError($res)) {
 220             return $res;
 221         }
 222         unset($this->storage->langs[$langID]);
 223         if ($this->options['autoCleanCache']) {
 224             $this->cleanCache();
 225         }
 226         return true;
 227     }
 228
 229     // }}}
 230     // {{{ updateLang
 231
 232     /**
 233      * Update the lang info in the langsAvail table
 234      *
 235      * @param array $langData array containing language info
 236      *
 237      * @return mixed true on success, PEAR_Error on failure
 238      */
 239     function updateLang($langData)
 240     {
 241         $result = $this->storage->updateLang($langData);
 242         if ($this->options['autoCleanCache']) {
 243             $this->cleanCache();
 244         }
 245         return $result;
 246     }
 247
 248     // }}}
 249     // {{{ add
 250
 251     /**
 252      * Add a new translation
 253      *
 254      * @param string $stringID    string ID
 255      * @param string $pageID      page/group ID
 256      * @param array  $stringArray Associative array with string translations.
 257      *               Sample format:  array('en' => 'sample', 'it' => 'esempio')
 258      *
 259      * @return mixed true on success, PEAR_Error on failure
 260      */
 261     function add($stringID, $pageID, $stringArray)
 262     {
 263         $result = $this->storage->add($stringID, $pageID, $stringArray);
 264         if ($this->options['autoCleanCache']) {
 265             $this->cleanCache();
 266         }
 267         return $result;
 268     }
 269
 270     // }}}
 271     // {{{ update
 272
 273     /**
 274      * Update an existing translation
 275      *
 276      * @param string $stringID    string ID
 277      * @param string $pageID      page/group ID
 278      * @param array  $stringArray Associative array with string translations.
 279      *               Sample format:  array('en' => 'sample', 'it' => 'esempio')
 280      *
 281      * @return mixed true on success, PEAR_Error on failure
 282      */
 283     function update($stringID, $pageID, $stringArray)
 284     {
 285         $result = $this->storage->update($stringID, $pageID, $stringArray);
 286         if ($this->options['autoCleanCache']) {
 287             $this->cleanCache();
 288         }
 289         return $result;
 290     }
 291
 292     // }}}
 293     // {{{ remove
 294
 295     /**
 296      * Remove a translated string
 297      *
 298      * @param string $stringID string ID
 299      * @param string $pageID   page/group ID
 300      *
 301      * @return mixed true on success, PEAR_Error on failure
 302      * @todo add a third $langs option, to conditionally remove only the langs specified
 303      */
 304     function remove($stringID, $pageID = null)
 305     {
 306         $result = $this->storage->remove($stringID, $pageID);
 307         if ($this->options['autoCleanCache']) {
 308             $this->cleanCache();
 309         }
 310         return $result;
 311     }
 312
 313     // }}}
 314     // {{{ removePage
 315
 316     /**
 317      * Remove all the strings in the given page/group
 318      *
 319      * @param string $pageID page/group ID
 320      *
 321      * @return mixed true on success, PEAR_Error on failure
 322      */
 323     function removePage($pageID = null)
 324     {
 325         $result = $this->storage->removePage($pageID);
 326         if ($this->options['autoCleanCache']) {
 327             $this->cleanCache();
 328         }
 329         return $result;
 330     }
 331
 332     // }}}
 333     // {{{ getPageNames()
 334
 335     /**
 336      * Get a list of all the pageIDs in any table.
 337      *
 338      * @return array
 339      */
 340     function getPageNames()
 341     {
 342         return $this->storage->getPageNames();
 343     }
 344
 345     // }}}
 346     // {{{ cleanCache()
 347
 348     /**
 349      * If you use the CacheLiteFunction decorator, you may want to invalidate
 350      * the cache after a change in the data base.
 351      *
 352      * @return void
 353      */
 354     function cleanCache()
 355     {
 356         static $cacheLiteFunction = null;
 357         if (is_null($cacheLiteFunction)) {
 358             include_once 'Cache/Lite/Function.php';
 359             $cacheLiteFunction = new Cache_Lite_Function($this->options['cacheOptions']);
 360         }
 361         $cacheLiteFunction->clean($this->options['cacheOptions']['defaultGroup']);
 362     }
 363
 364     // }}}
 365 }
 366 ?>