1. sfMessageSource.class.php
  2. /**
 * Abstract sfMessageSource class.
 *
 * The base class for all sfMessageSources. Message sources must be instantiated
 * using the factory method. The default valid sources are
 *
 *  # XLIFF -- using XML XLIFF format to store the translation messages.
 *  # SQLite -- Store the translation messages in a SQLite database.
 *  # MySQL -- Using a MySQL database to store the messages.
 *  # gettext -- Translated messages are stored in the gettext format.
 *
 * A custom message source can be instantiated by specifying the filename
 * parameter to point to the custom class file. E.g.
 * 
 *   $resource = '...'; //custom message source resource
 *   $classfile = '../sfMessageSource_MySource.php'; //custom message source
 *   $source = sfMessageSource::factory('MySource', $resource, $classfile);
 * 
 *
 * If you are writting your own message sources, pay attention to the
 * loadCatalogue method. It details how the resources are loaded and cached.
 * See also the existing message source types as examples.
 *
 * The following example instantiates a MySQL message source, set the culture,
 * set the cache handler, and use the source in a message formatter.
 * The messages are store in a database named "messages". The source parameter
 * for the actory method is a PEAR DB style DSN.
 * 
 *   $dsn = 'mysql://username:password@localhost/messages';
 *   $source = sfMessageSource::factory('MySQL', $dsn);
 *
 *   //set the culture and cache, store the cache in the /tmp directory.
 *   $source->setCulture('en_AU')l
 *   $source->setCache(new sfMessageCache(new sfFileCache(array('/tmp'))));
 *
 *   $formatter = new sfMessageFormat($source);
 * 
 *
 * @author Xiang Wei Zhuo 
 * @version v1.0, last update on Fri Dec 24 19:55:49 EST 2004
 * @package    symfony
 * @subpackage i18n
 */
  3. abstract class sfMessageSource implements sfIMessageSource
  4. {
  5.   /**
  6.    * The culture name for this message source.
  7.    * @var string
  8.    */
  9.   protected $culture;
  11.   /**
  12.    * Array of translation messages.
  13.    * @var array
  14.    */
  15.   protected $messages = array();
  17.   /**
  18.    * The source of message translations.
  19.    * @var string
  20.    */
  21.   protected $source;
  23.   /**
  24.    * The translation cache.
  25.    * @var sfMessageCache
  26.    */
  27.   protected $cache;
  29.   protected $untranslated = array();
  31.   /**
  32.    * Private constructor. sfMessageSource must be initialized using
  33.    * the factory method.
  34.    */
  35.   private function __construct()
  36.   {
  37.     //throw new sfException('Please use the factory method to instantiate.');
  38.   }
  40.   /**
  41.    * Factory method to instantiate a new sfMessageSource depending on the
  42.    * source type. The built-in source types are 'XLIFF', 'SQLite',
  43.    * 'MySQL', 'gettext', and 'Aggregate'.
  44.    * The source parameter is dependent on the source type.
  45.    * For 'gettext' and 'XLIFF', it should point to the directory
  46.    * where the messages are stored. For database types, e.g. 'SQLite' and
  47.    * 'MySQL', it should be a PEAR DB style DSN string.
  48.    *
  49.    * Custom message source are possible by supplying the a filename parameter
  50.    * in the factory method.
  51.    *
  52.    * @param string $type      the message source type.
  53.    * @param string $source    the location of the resource.
  54.    * @param string $filename  the filename of the custom message source.
  55.    * @return sfMessageSource a new message source of the specified type.
  56.    * @throws sfException
  57.    */
  58.   static function factory($type, $source = '.', $filename = '')
  59.   {
  60.     if ($filename)
  61.     {
  62.       if (!is_file($filename))
  63.       {
  64.         throw new sfException(sprintf("File %s not found.", $filename));
  65.       }
  67.       include_once($filename);
  68.     }
  70.     $class = 'sfMessageSource_'.$type;
  71.     if (!class_exists($class))
  72.     {
  73.       throw new sfException(sprintf('Unable to find type "%s".', $type));
  74.     }
  76.     return new $class($source);
  77.   }
  79.   /**
  80.    * Loads a particular message catalogue. Use read() to
  81.    * to get the array of messages. The catalogue loading sequence
  82.    * is as follows:
  83.    *
  84.    *  # [1] Call getCatalogueList($catalogue) to get a list of variants for for the specified $catalogue.
  85.    *  # [2] For each of the variants, call getSource($variant) to get the resource, could be a file or catalogue ID.
  86.    *  # [3] Verify that this resource is valid by calling isValidSource($source)
  87.    *  # [4] Try to get the messages from the cache
  88.    *  # [5] If a cache miss, call load($source) to load the message array
  89.    *  # [6] Store the messages to cache.
  90.    *  # [7] Continue with the foreach loop, e.g. goto [2].
  91.    *
  92.    * @param  string  $catalogue a catalogue to load
  93.    * @return boolean always true
  94.    * @see    read()
  95.    */
  96.   function load($catalogue = 'messages')
  97.   {
  98.     $variants = $this->getCatalogueList($catalogue);
  100.     $this->messages = array();
  102.     foreach ($variants as $variant)
  103.     {
  104.       $source = $this->getSource($variant);
  106.       if ($this->isValidSource($source) == false)
  107.       {
  108.         continue;
  109.       }
  111.       $loadData = true;
  113.       if ($this->cache)
  114.       {
  115.         $lastModified = $this->getLastModified($source);
  116.         if ($lastModified >= 0 && $lastModified < $this->cache->getLastModified($variant.':'.$this->culture))
  117.         {
  118.           $data = unserialize($this->cache->get($variant.':'.$this->culture));
  120.           if (is_array($data))
  121.           {
  122.             $this->messages[$variant] = $data;
  123.             $loadData = false;
  124.           }
  126.           unset($data);
  127.         }
  128.       }
  130.       if ($loadData)
  131.       {
  132.         $data = &$this->loadData($source);
  133.         if (is_array($data))
  134.         {
  135.           $this->messages[$variant] = $data;
  136.           if ($this->cache)
  137.           {
  138.             $this->cache->set($variant.':'.$this->culture, serialize($data));
  139.           }
  140.         }
  142.         unset($data);
  143.       }
  144.     }
  146.     return true;
  147.   }
  149.   /**
  150.    * Gets the array of messages.
  151.    *
  152.    * @return array translation messages.
  153.    */
  154.   public function read()
  155.   {
  156.     return $this->messages;
  157.   }
  159.   /**
  160.    * Gets the cache handler for this source.
  161.    *
  162.    * @return sfMessageCache cache handler
  163.    */
  164.   public function getCache()
  165.   {
  166.     return $this->cache;
  167.   }
  169.   /**
  170.    * Sets the cache handler for caching the messages.
  171.    *
  172.    * @param sfCache $cache the cache handler.
  173.    */
  174.   public function setCache(sfCache $cache)
  175.   {
  176.     $this->cache = $cache;
  177.   }
  179.   /**
  180.    * Adds a untranslated message to the source. Need to call save()
  181.    * to save the messages to source.
  182.    *
  183.    * @param string $message message to add
  184.    */
  185.   public function append($message)
  186.   {
  187.     if (!in_array($message, $this->untranslated))
  188.     {
  189.       $this->untranslated[] = $message;
  190.     }
  191.   }
  193.   /**
  194.    * Sets the culture for this message source.
  195.    *
  196.    * @param string $culture culture name
  197.    */
  198.   public function setCulture($culture)
  199.   {
  200.     $this->culture = $culture;
  201.   }
  203.   /**
  204.    * Gets the culture identifier for the source.
  205.    *
  206.    * @return string culture identifier.
  207.    */
  208.   public function getCulture()
  209.   {
  210.     return $this->culture;
  211.   }
  213.   /**
  214.    * Gets the last modified unix-time for this particular catalogue+variant.
  215.    *
  216.    * @param string $source catalogue+variant
  217.    * @return int last modified in unix-time format.
  218.    */
  219.   protected function getLastModified($source)
  220.   {
  221.     return 0;
  222.   }
  224.   /**
  225.    * Loads the message for a particular catalogue+variant.
  226.    * This methods needs to implemented by subclasses.
  227.    *
  228.    * @param string $variant catalogue+variant.
  229.    * @return array of translation messages.
  230.    */
  231.   public function &loadData($variant)
  232.   {
  233.     return array();
  234.   }
  236.   /**
  237.    * Gets the source, this could be a filename or database ID.
  238.    *
  239.    * @param string $variant catalogue+variant
  240.    * @return string the resource key
  241.    */
  242.   public function getSource($variant)
  243.   {
  244.     return $variant;
  245.   }
  247.   /**
  248.    * Determines if the source is valid.
  249.    *
  250.    * @param string $source catalogue+variant
  251.    * @return boolean true if valid, false otherwise.
  252.    */
  253.   public function isValidSource($source)
  254.   {
  255.     return false;
  256.   }
  258.   /**
  259.    * Gets all the variants of a particular catalogue.
  260.    * This method must be implemented by subclasses.
  261.    *
  262.    * @param string $catalogue catalogue name
  263.    * @return array list of all variants for this catalogue.
  264.    */
  265.   public function getCatalogueList($catalogue)
  266.   {
  267.     return array();
  268.   }
  269. }
Debug toolbar