[ZF-10166] Zend_Translate:

- allow tag usage (ZF-10166)
- added tag handling per instance


git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@22585 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Translate-Adapters.xml

@@ -416,6 +416,9 @@ $translate = new Zend_Translate(
         'locale'  => 'en'
     )
 );
+
+// to clear the cache somewhere later in your code
+Zend_Translate::clearCache();
 ]]></programlisting>
 
         <note>
@@ -426,6 +429,37 @@ $translate = new Zend_Translate(
                 <methodname>addTranslation()</methodname> method.
             </para>
         </note>
+
+        <para>
+            When the attached cache supports tagging you can set a own tag string by using the
+            option <property>tag</property>. This allows you do delete only the cache from this
+            single instance of <classname>Zend_Translate</classname>. When you are not using this
+            option the default tag <classname>Zend_Translate</classname> is used.
+        </para>
+
+        <para>
+            Using the option <property>tag</property> you must give the used tag to
+            <methodname>clearCache()</methodname> to declare which tag you want to delete.
+        </para>
+
+        <programlisting language="php"><![CDATA[
+$cache = Zend_Cache::factory('Core',
+                             'File',
+                             $frontendOptions,
+                             $backendOptions);
+Zend_Translate::setCache($cache);
+$translate = new Zend_Translate(
+    array(
+        'adapter' => 'gettext',
+        'content' => '/path/to/translate.mo',
+        'locale'  => 'en',
+        'tag'     => 'MyTag'
+    )
+);
+
+// somewhere later in your code
+Zend_Translate::clearCache('MyTag');
+]]></programlisting>
     </sect2>
 </sect1>
 <!--

documentation/manual/en/module_specs/Zend_Translate-Additional.xml

@@ -240,6 +240,19 @@ $translate->addTranslation(
                     </row>
 
                     <row>
+                        <entry>tag</entry>
+                        <entry>all</entry>
+
+                        <entry>
+                            Sets an individual tag which is used for the attached cache. Using this
+                            option allows to use and clear the cache for single instances. When this
+                            option is not set, the attached cache is used for all instances combined
+                        </entry>
+
+                        <entry><emphasis><classname>Zend_Translate</classname></emphasis></entry>
+                    </row>
+
+                    <row>
                         <entry>delimiter</entry>
                         <entry>Csv</entry>
 

library/Zend/Translate/Adapter.php

@@ -59,6 +59,13 @@ abstract class Zend_Translate_Adapter {
     protected static $_cache     = null;
 
     /**
+     * Internal value to remember if cache supports tags
+     *
+     * @var boolean
+     */
+    private static $_cacheTags = false;
+
+    /**
      * Scans for the locale within the name of the directory
      * @constant integer
      */
@@ -82,6 +89,7 @@ abstract class Zend_Translate_Adapter {
      *   'logUntranslated' => when true, untranslated messages are not logged
      *   'reload'          => reloads the cache by reading the content again
      *   'scan'            => searches for translation files using the LOCALE constants
+     *   'tag'             => tag to use for the cache
      *
      * @var array
      */
@@ -96,7 +104,8 @@ abstract class Zend_Translate_Adapter {
         'logUntranslated' => false,
         'reload'          => false,
         'route'           => null,
-        'scan'            => null
+        'scan'            => null,
+        'tag'             => 'Zend_Translate'
     );
 
     /**
@@ -347,7 +356,11 @@ abstract class Zend_Translate_Adapter {
 
         if (isset(self::$_cache) and ($change == true)) {
             $id = 'Zend_Translate_' . $this->toString() . '_Options';
-            self::$_cache->save($this->_options, $id);
+            if (self::$_cacheTags) {
+                self::$_cache->save($this->_options, $id, array($this->_options['tag']));
+            } else {
+                self::$_cache->save($this->_options, $id);
+            }
         }
 
         return $this;
@@ -435,7 +448,11 @@ abstract class Zend_Translate_Adapter {
 
             if (isset(self::$_cache)) {
                 $id = 'Zend_Translate_' . $this->toString() . '_Options';
-                self::$_cache->save($this->_options, $id);
+                if (self::$_cacheTags) {
+                    self::$_cache->save($this->_options, $id, array($this->_options['tag']));
+                } else {
+                    self::$_cache->save($this->_options, $id);
+                }
             }
         }
 
@@ -644,7 +661,11 @@ abstract class Zend_Translate_Adapter {
 
         if (($read) and (isset(self::$_cache))) {
             $id = 'Zend_Translate_' . md5(serialize($options['content'])) . '_' . $this->toString();
-            self::$_cache->save($temp, $id);
+            if (self::$_cacheTags) {
+                self::$_cache->save($temp, $id, array($this->_options['tag']));
+            } else {
+                self::$_cache->save($temp, $id);
+            }
         }
 
         return $this;
@@ -885,6 +906,7 @@ abstract class Zend_Translate_Adapter {
     public static function setCache(Zend_Cache_Core $cache)
     {
         self::$_cache = $cache;
+        self::_getTagSupportForCache();
     }
 
     /**
@@ -914,12 +936,21 @@ abstract class Zend_Translate_Adapter {
     /**
      * Clears all set cache data
      *
+     * @param string $tag Tag to clear when the default tag name is not used
      * @return void
      */
-    public static function clearCache()
+    public static function clearCache($tag = null)
     {
         require_once 'Zend/Cache.php';
-        self::$_cache->clean(Zend_Cache::CLEANING_MODE_ALL);
+        if (self::$_cacheTags) {
+            if ($tag == null) {
+                $tag = 'Zend_Translate';
+            }
+
+            self::$_cache->clean(Zend_Cache::CLEANING_MODE_MATCHING_TAG, array($tag));
+        } else {
+            self::$_cache->clean(Zend_Cache::CLEANING_MODE_ALL);
+        }
     }
 
     /**
@@ -928,4 +959,22 @@ abstract class Zend_Translate_Adapter {
      * @return string
      */
     abstract public function toString();
+
+    /**
+     * Internal method to check if the given cache supports tags
+     *
+     * @param Zend_Cache $cache
+     */
+    private static function _getTagSupportForCache()
+    {
+        $backend = self::$_cache->getBackend();
+        if ($backend instanceof Zend_Cache_Backend_ExtendedInterface) {
+            $cacheOptions = $backend->getCapabilities();
+            self::$_cacheTags = $cacheOptions['tags'];
+        } else {
+            self::$_cacheTags = false;
+        }
+
+        return self::$_cacheTags;
+    }
 }