[Sommaire] [Imprimer]

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