Development

/branches/1.0/lib/i18n/sfMessageSource.class.php

You must first sign up to be able to contribute.

root/branches/1.0/lib/i18n/sfMessageSource.class.php

Revision 8785, 8.3 kB (checked in by fabien, 7 years ago)

reverted fix for #3472 as sfMessageFormat relies on the fact ->load() always returns true (updated the API doc)

  • Property svn:mime-type set to text/x-php
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Rev Date
Line 
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$
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    symfony
62  * @subpackage i18n
63  */
64 abstract class sfMessageSource implements sfIMessageSource
65 {
66   /**
67    * The culture name for this message source.
68    * @var string
69    */
70   protected $culture;
71
72   /**
73    * Array of translation messages.
74    * @var array
75    */
76   protected $messages = array();
77
78   /**
79    * The source of message translations.
80    * @var string
81    */
82   protected $source;
83
84   /**
85    * The translation cache.
86    * @var sfMessageCache
87    */
88   protected $cache;
89
90   protected $untranslated = array();
91
92   /**
93    * Private constructor. sfMessageSource must be initialized using
94    * the factory method.
95    */
96   private function __construct()
97   {
98     //throw new sfException('Please use the factory method to instantiate.');
99   }
100
101   /**
102    * Factory method to instantiate a new sfMessageSource depending on the
103    * source type. The built-in source types are 'XLIFF', 'SQLite',
104    * 'MySQL', 'gettext' and Creole. The source parameter is dependent on the
105    * source type. For 'gettext' and 'XLIFF', it should point to the directory
106    * where the messages are stored. For database types, e.g. 'SQLite' and
107    * 'MySQL', it should be a PEAR DB style DSN string.
108    *
109    * Custom message source are possible by supplying the a filename parameter
110    * in the factory method.
111    *
112    * @param string the message source type.
113    * @param string the location of the resource.
114    * @param string the filename of the custom message source.
115    * @return sfMessageSource a new message source of the specified type.
116    * @throws sfException
117    */
118   static function factory($type, $source = '.', $filename = '')
119   {
120     if ($filename)
121     {
122       if (!is_file($filename))
123       {
124         throw new sfException(sprintf("File %s not found.", $filename));
125       }
126
127       include_once($filename);
128     }
129
130     $class = 'sfMessageSource_'.$type;
131     if (!class_exists($class))
132     {
133       throw new sfException(sprintf('Unable to find type "%s".', $type));
134     }
135
136     return new $class($source);
137   }
138
139   /**
140    * Loads a particular message catalogue. Use read() to
141    * to get the array of messages. The catalogue loading sequence
142    * is as follows:
143    *
144    *  # [1] Call getCatalogueList($catalogue) to get a list of variants for for the specified $catalogue.
145    *  # [2] For each of the variants, call getSource($variant) to get the resource, could be a file or catalogue ID.
146    *  # [3] Verify that this resource is valid by calling isValidSource($source)
147    *  # [4] Try to get the messages from the cache
148    *  # [5] If a cache miss, call load($source) to load the message array
149    *  # [6] Store the messages to cache.
150    *  # [7] Continue with the foreach loop, e.g. goto [2].
151    *
152    * @param  string  a catalogue to load
153    * @return boolean always true
154    * @see    read()
155    */
156   function load($catalogue = 'messages')
157   {
158     $variants = $this->getCatalogueList($catalogue);
159
160     $this->messages = array();
161
162     foreach ($variants as $variant)
163     {
164       $source = $this->getSource($variant);
165
166       if ($this->isValidSource($source) == false)
167       {
168         continue;
169       }
170
171       $loadData = true;
172
173       if ($this->cache)
174       {
175         $data = $this->cache->get($variant, $this->culture, $this->getLastModified($source));
176
177         if (is_array($data))
178         {
179           $this->messages[$variant] = $data;
180           $loadData = false;
181         }
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
198         unset($data);
199       }
200     }
201
202     return true;
203   }
204
205   /**
206    * Gets the array of messages.
207    *
208    * @param parameter
209    * @return array translation messages.
210    */
211   public function read()
212   {
213     return $this->messages;
214   }
215
216   /**
217    * Gets the cache handler for this source.
218    *
219    * @return sfMessageCache cache handler
220    */
221   public function getCache()
222   {
223     return $this->cache;
224   }
225
226   /**
227    * Sets the cache handler for caching the messages.
228    *
229    * @param sfMessageCache the cache handler.
230    */
231   public function setCache(sfMessageCache $cache)
232   {
233     $this->cache = $cache;
234   }
235
236   /**
237    * Adds a untranslated message to the source. Need to call save()
238    * to save the messages to source.
239    *
240    * @param string message to add
241    */
242   public function append($message)
243   {
244     if (!in_array($message, $this->untranslated))
245     {
246       $this->untranslated[] = $message;
247     }
248   }
249
250   /**
251    * Sets the culture for this message source.
252    *
253    * @param string culture name
254    */
255   public function setCulture($culture)
256   {
257     $this->culture = $culture;
258   }
259
260   /**
261    * Gets the culture identifier for the source.
262    *
263    * @return string culture identifier.
264    */
265   public function getCulture()
266   {
267     return $this->culture;
268   }
269
270   /**
271    * Gets the last modified unix-time for this particular catalogue+variant.
272    *
273    * @param string catalogue+variant
274    * @return int last modified in unix-time format.
275    */
276   protected function getLastModified($source)
277   {
278     return 0;
279   }
280
281   /**
282    * Loads the message for a particular catalogue+variant.
283    * This methods needs to implemented by subclasses.
284    *
285    * @param string catalogue+variant.
286    * @return array of translation messages.
287    */
288   protected function &loadData($variant)
289   {
290     return array();
291   }
292
293   /**
294    * Gets the source, this could be a filename or database ID.
295    *
296    * @param string catalogue+variant
297    * @return string the resource key
298    */
299   protected function getSource($variant)
300   {
301     return $variant;
302   }
303
304   /**
305    * Determines if the source is valid.
306    *
307    * @param string catalogue+variant
308    * @return boolean true if valid, false otherwise.
309    */
310   protected function isValidSource($source)
311   {
312     return false;
313   }
314
315   /**
316    * Gets all the variants of a particular catalogue.
317    * This method must be implemented by subclasses.
318    *
319    * @param string catalogue name
320    * @return array list of all variants for this catalogue.
321    */
322   protected function getCatalogueList($catalogue)
323   {
324     return array();
325   }
326 }
327
Note: See TracBrowser for help on using the browser.