[Sommaire] [Imprimer]

   1  <?php
   2  
   3  /**
   4   * sfMessageSource class file.
   5   *
   6   * This program is free software; you can redistribute it and/or modify
   7   * it under the terms of the BSD License.
   8   *
   9   * Copyright(c) 2004 by Qiang Xue. All rights reserved.
  10   *
  11   * To contact the author write to {@link mailto:qiang.xue@gmail.com Qiang Xue}
  12   * The latest version of PRADO can be obtained from:
  13   * {@link http://prado.sourceforge.net/}
  14   *
  15   * @author     Wei Zhuo <weizhuo[at]gmail[dot]com>
  16   * @version    $Id: sfMessageSource.class.php 2834 2006-11-27 14:09:05Z fabien $
  17   * @package    symfony
  18   * @subpackage i18n
  19   */
  20  
  21  /**
  22   * Abstract sfMessageSource class.
  23   *
  24   * The base class for all sfMessageSources. Message sources must be instantiated
  25   * using the factory method. The default valid sources are
  26   *
  27   *  # XLIFF -- using XML XLIFF format to store the translation messages.
  28   *  # SQLite -- Store the translation messages in a SQLite database.
  29   *  # MySQL -- Using a MySQL database to store the messages.
  30   *  # gettext -- Translated messages are stored in the gettext format.
  31   *
  32   * A custom message source can be instantiated by specifying the filename
  33   * parameter to point to the custom class file. E.g.
  34   * <code>
  35   *   $resource = '...'; //custom message source resource
  36   *   $classfile = '../sfMessageSource_MySource.php'; //custom message source
  37   *   $source = sfMessageSource::factory('MySource', $resource, $classfile);
  38   * </code>
  39   *
  40   * If you are writting your own message sources, pay attention to the
  41   * loadCatalogue method. It details how the resources are loaded and cached.
  42   * See also the existing message source types as examples.
  43   *
  44   * The following example instantiates a MySQL message source, set the culture,
  45   * set the cache handler, and use the source in a message formatter.
  46   * The messages are store in a database named "messages". The source parameter
  47   * for the actory method is a PEAR DB style DSN.
  48   * <code>
  49   *   $dsn = 'mysql://username:password@localhost/messages';
  50   *   $source = sfMessageSource::factory('MySQL', $dsn);
  51   *
  52   *   //set the culture and cache, store the cache in the /tmp directory.
  53   *   $source->setCulture('en_AU')l
  54   *   $source->setCache(new sfMessageCache('/tmp'));
  55   *
  56   *   $formatter = new sfMessageFormat($source);
  57   * </code>
  58   *
  59   * @author Xiang Wei Zhuo <weizhuo[at]gmail[dot]com>
  60   * @version v1.0, last update on Fri Dec 24 19:55:49 EST 2004
  61   * @package System.I18N.core
  62   */
  63  abstract class sfMessageSource implements sfIMessageSource
  64  {
  65    /**
  66     * The culture name for this message source.
  67     * @var string
  68     */
  69    protected $culture;
  70  
  71    /**
  72     * Array of translation messages.
  73     * @var array
  74     */
  75    protected $messages = array();
  76  
  77    /**
  78     * The source of message translations.
  79     * @var string
  80     */
  81    protected $source;
  82  
  83    /**
  84     * The translation cache.
  85     * @var sfMessageCache
  86     */
  87    protected $cache;
  88  
  89    protected $untranslated = array();
  90  
  91    /**
  92     * Private constructor. sfMessageSource must be initialized using
  93     * the factory method.
  94     */
  95    private function __construct()
  96    {
  97      //throw new sfException('Please use the factory method to instantiate.');
  98    }
  99  
 100    /**
 101     * Factory method to instantiate a new sfMessageSource depending on the
 102     * source type. The built-in source types are 'XLIFF', 'SQLite',
 103     * 'MySQL', 'gettext' and Creole. The source parameter is dependent on the
 104     * source type. For 'gettext' and 'XLIFF', it should point to the directory
 105     * where the messages are stored. For database types, e.g. 'SQLite' and
 106     * 'MySQL', it should be a PEAR DB style DSN string.
 107     *
 108     * Custom message source are possible by supplying the a filename parameter
 109     * in the factory method.
 110     *
 111     * @param string the message source type.
 112     * @param string the location of the resource.
 113     * @param string the filename of the custom message source.
 114     * @return sfMessageSource a new message source of the specified type.
 115     * @throws sfException
 116     */
 117    static function factory($type, $source = '.', $filename = '')
 118    {
 119      if ($filename)
 120      {
 121        if (!is_file($filename))
 122        {
 123          throw new sfException("File $filename not found");
 124        }
 125  
 126        include_once($filename);
 127      }
 128  
 129      $class = 'sfMessageSource_'.$type;
 130      if (!class_exists($class))
 131      {
 132        throw new sfException(sprintf('Unable to find type "%s"', $type));
 133      }
 134  
 135      return new $class($source);
 136    }
 137  
 138    /**
 139     * Load a particular message catalogue. Use read() to
 140     * to get the array of messages. The catalogue loading sequence
 141     * is as follows
 142     *
 143     *  # [1] call getCatalogeList($catalogue) to get a list of
 144     *    variants for for the specified $catalogue.
 145     *  # [2] for each of the variants, call getSource($variant)
 146     *    to get the resource, could be a file or catalogue ID.
 147     *  # [3] verify that this resource is valid by calling isValidSource($source)
 148     *  # [4] try to get the messages from the cache
 149     *  # [5] if a cache miss, call load($source) to load the message array
 150     *  # [6] store the messages to cache.
 151     *  # [7] continue with the foreach loop, e.g. goto [2].
 152     *
 153     * @param string a catalogue to load
 154     * @return boolean true if loaded, false otherwise.
 155     * @see read()
 156     */
 157    function load($catalogue='messages')
 158    {
 159      $variants = $this->getCatalogueList($catalogue);
 160  
 161      $this->messages = array();
 162  
 163      foreach ($variants as $variant)
 164      {
 165        $source = $this->getSource($variant);
 166  
 167        if ($this->isValidSource($source) == false)
 168        {
 169          continue;
 170        }
 171  
 172        $loadData = true;
 173  
 174        if ($this->cache)
 175        {
 176          $data = $this->cache->get($variant, $this->culture, $this->getLastModified($source));
 177  
 178          if (is_array($data))
 179          {
 180            $this->messages[$variant] = $data;
 181            $loadData = false;
 182          }
 183          unset($data);
 184        }
 185  
 186        if ($loadData)
 187        {
 188          $data = &$this->loadData($source);
 189          if (is_array($data))
 190          {
 191            $this->messages[$variant] = $data;
 192            if ($this->cache)
 193            {
 194              $this->cache->save($data, $variant, $this->culture);
 195            }
 196          }
 197          unset($data);
 198        }
 199      }
 200  
 201      return true;
 202    }
 203  
 204    /**
 205     * Get the array of messages.
 206     *
 207     * @param parameter
 208     * @return array translation messages.
 209     */
 210    public function read()
 211    {
 212      return $this->messages;
 213    }
 214  
 215    /**
 216     * Get the cache handler for this source.
 217     *
 218     * @return sfMessageCache cache handler
 219     */
 220    public function getCache()
 221    {
 222      return $this->cache;
 223    }
 224  
 225    /**
 226     * Set the cache handler for caching the messages.
 227     *
 228     * @param sfMessageCache the cache handler.
 229     */
 230    public function setCache(sfMessageCache $cache)
 231    {
 232      $this->cache = $cache;
 233    }
 234  
 235    /**
 236     * Add a untranslated message to the source. Need to call save()
 237     * to save the messages to source.
 238     *
 239     * @param string message to add
 240     */
 241    public function append($message)
 242    {
 243      if (!in_array($message, $this->untranslated))
 244      {
 245        $this->untranslated[] = $message;
 246      }
 247    }
 248  
 249    /**
 250     * Set the culture for this message source.
 251     *
 252     * @param string culture name
 253     */
 254    public function setCulture($culture)
 255    {
 256      $this->culture = $culture;
 257    }
 258  
 259    /**
 260     * Get the culture identifier for the source.
 261     *
 262     * @return string culture identifier.
 263     */
 264    public function getCulture()
 265    {
 266      return $this->culture;
 267    }
 268  
 269    /**
 270     * Get the last modified unix-time for this particular catalogue+variant.
 271     *
 272     * @param string catalogue+variant
 273     * @return int last modified in unix-time format.
 274     */
 275    protected function getLastModified($source)
 276    {
 277      return 0;
 278    }
 279  
 280    /**
 281     * Load the message for a particular catalogue+variant.
 282     * This methods needs to implemented by subclasses.
 283     *
 284     * @param string catalogue+variant.
 285     * @return array of translation messages.
 286     */
 287    protected function &loadData($variant)
 288    {
 289      return array();
 290    }
 291  
 292    /**
 293     * Get the source, this could be a filename or database ID.
 294     *
 295     * @param string catalogue+variant
 296     * @return string the resource key
 297     */
 298    protected function getSource($variant)
 299    {
 300      return $variant;
 301    }
 302  
 303    /**
 304     * Determine if the source is valid.
 305     *
 306     * @param string catalogue+variant
 307     * @return boolean true if valid, false otherwise.
 308     */
 309    protected function isValidSource($source)
 310    {
 311      return false;
 312    }
 313  
 314    /**
 315     * Get all the variants of a particular catalogue.
 316     * This method must be implemented by subclasses.
 317     *
 318     * @param string catalogue name
 319     * @return array list of all variants for this catalogue.
 320     */
 321    protected function getCatalogueList($catalogue)
 322    {
 323      return array();
 324    }
 325  }