Zend_Cache_Core 注解

class  Zend_Cache_Core
{

     //  ------------------
    // --- Properties ---
    // ------------------

     /* *
     * Backend Object 保存采用后端实例
     *
     * @var object
      */
     private   $_backend   =   null ;

     /* *
     * Available options
     *
     * ====> (boolean) write_control : 
     * - Enable / disable write control (the cache is read just after writing to detect corrupt entries)
     * - Enable write control will lightly slow the cache writing but not the cache reading
     * Write control can detect some corrupt cache files but maybe it's not a perfect control
     * 写入时检测要缓存的内容与原来的内容是否一致 
     * 
     * ====> (boolean) caching :    是否要缓存的开关
     * - Enable / disable caching
     * (can be very usefull for the debug of cached scripts)
     *  可以在调试程序时关闭缓存开关
     * 
     * ====> (boolean) automatic_serialization : 自动序列化开关
     * - Enable / disable automatic serialization
     * - It can be used to save directly datas which aren't strings (but it's slower)
     * 开启后可以实现保存非字符窜类型数据
     * 
     * ====> (int) automatic_cleaning_factor :    自动清理过期缓存开关
     * - Disable / Tune the automatic cleaning process
     * - The automatic cleaning process destroy too old (for the given life time)
     *   cache files when a new cache file is written :
     *     0               => no automatic cache cleaning
     *     1               => systematic cache cleaning
     *     x (integer) > 1 => automatic cleaning randomly 1 times on x cache write
     *
     * ====> (int) lifetime :    缓存存在的时间
     * - Cache lifetime (in seconds)
     * - If null, the cache is valid forever. 为空表示缓存不过期
     *
     * ====> (boolean) logging :    日志开关
     * - If set to true, logging is activated (but the system is slower)
     *
     * @var array available options
      */
     protected   $_options   =   array (
         ' write_control '               =>   true ,
         ' caching '                     =>   true ,
         ' automatic_serialization '     =>   false ,
         ' automatic_cleaning_factor '   =>   10 ,
         ' lifetime '                    =>   3600 ,
         ' logging '                     =>   false ,
         ' logger '                      =>   null
    );

     /* *
     * Array of options which have to be transfered to backend 设置需要传递给后台模块的参数
      */
     protected   static   $_directivesList   =   array ( ' lifetime ' ,   ' logging ' ,   ' logger ' );

     /* *
     * Not used for the core, just a sort a hint to get a common setOption() method (for the core and for frontends)
      */
     protected   $_specificOptions   =   array ();

     /* *
     * Last used cache id
     * 最后一次使用的缓冲id
     * 
     * @var string $_lastId
      */
     private   $_lastId   =   null ;

     /* *
     * backward compatibility becase of ZF-879 and ZF-1172 (it will be removed in ZF 1.1)
     * 针对后台模块为兼容早期 zf  版本的设置
     * @var array
      */
     protected   $_backwardCompatibilityArray   =   array (
         ' lifeTime '   =>   ' lifetime ' ,
         ' writeControl '   =>   ' write_control ' ,
         ' automaticSerialization '   =>   ' automatic_serialization ' ,
         ' automaticCleaningFactor '   =>   ' automatic_cleaning_factor ' ,
         ' cachedEntity '   =>   ' cached_entity ' ,
         ' cacheByDefault '   =>   ' cache_by_default ' ,
         ' cachedMethods '   =>   ' cached_methods ' ,
         ' nonCachedMethods '   =>   ' non_cached_methods ' ,
         ' cachedFunctions '   =>   ' cached_functions ' ,
         ' nonCachedFunctions '   =>   ' non_cached_functions ' ,
         ' masterFile '   =>   ' master_file ' ,
         ' httpConditional '   =>   ' http_conditional ' ,
         ' debugHeader '   =>   ' debug_header ' ,
         ' defaultOptions '   =>   ' default_options ' ,
         ' cacheWithGetVariables '   =>   ' cache_with_get_variables ' ,
         ' cacheWithPostVariables '   =>   ' cache_with_post_variables ' ,
         ' cacheWithSessionVariables '   =>   ' cache_with_session_variables ' ,
         ' cacheWithFilesVariables '   =>   ' cache_with_files_variables ' ,
         ' cacheWithCookieVariables '   =>   ' cache_with_cookie_variables ' ,
         ' makeIdWithGetVariables '   =>   ' make_id_with_get_variables ' ,
         ' makeIdWithPostVariables '   =>   ' make_id_with_post_variables ' ,
         ' makeIdWithSessionVariables '   =>   ' make_id_with_session_variables ' ,
         ' makeIdWithFilesVariables '   =>   ' make_id_with_files_variables ' ,
         ' makeIdWithCookieVariables '   =>   ' make_id_with_cookie_variables '
    );

     //  ----------------------
    // --- Public methods ---
    // ----------------------

     /* *
     * Constructor
     *
     * @param array $options associative array of options
      */
     public   function  __construct( $options   =   array ())
    {
         if  ( ! is_array ( $options )) {
            Zend_Cache :: throwException( ' Options parameter must be an array ' );
        }
         while  ( list ( $name ,   $value )  =   each ( $options )) {
             $this -> setOption( $name ,   $value );
        }
         $this -> _loggerSanity();
    }

     /* *
     * Set the backend
     *
     * @param object $backendObject
      */
     public   function  setBackend( $backendObject )
    {
         if  ( ! is_object ( $backendObject )) {
            Zend_Cache :: throwException( ' Incorrect backend object ! ' );
        }
         $this -> _backend =   $backendObject ;
         //  some options (listed in $_directivesList) have to be given
        // to the backend too (even if they are not "backend specific")
         $directives   =   array ();
         foreach  (Zend_Cache_Core :: $_directivesList   as   $directive ) {
             $directives [ $directive ]  =   $this -> _options[ $directive ];
        }
         $this -> _backend -> setDirectives( $directives );
    }

     /* *
     * Public frontend to set an option
     *
     * There is an additional validation (relatively to the protected _setOption method)
     *
     * @param string $name name of the option
     * @param mixed $value value of the option
      */
     public   function  setOption( $name ,   $value )
    {
         if  ( is_string ( $name )) {
             if  ( array_key_exists ( $name ,   $this -> _backwardCompatibilityArray)) {
                 $tmp   =   $this -> _backwardCompatibilityArray[ $name ];
                 $this -> _log( " $name option is deprecated, use $tmp instead (same syntax) ! " );
                 $name   =   $tmp ;
            }  else  {
                 $name   =   strtolower ( $name );
            }
             if  ( array_key_exists ( $name ,   $this -> _options)) {
                 //  This is a Core option
                 $this -> _setOption( $name ,   $value );
                 return ;
            }
             if  ( array_key_exists ( $name ,   $this -> _specificOptions)) {
                 //  This a specic option of this frontend
                 $this -> _specificOptions[ $name ]  =   $value ;
                 return ;
            }
        }
        Zend_Cache :: throwException( " Incorrect option name : $name " );
    }

     /* *
     * Set an option
     *
     * @param string $name name of the option
     * @param mixed $value value of the option
      */
     private   function  _setOption( $name ,   $value )
    {
         if  ( ! is_string ( $name )  ||   ! array_key_exists ( $name ,   $this -> _options)) {
            Zend_Cache :: throwException( " Incorrect option name : $name " );
        }
         $this -> _options[ $name ]  =   $value ;
    }

     /* *
     * Force a new lifetime
     * 设置缓存的生命期
     * The new value is set for the core/frontend but for the backend too (directive)
     *
     * @param int $newLifetime new lifetime (in seconds)
      */
     public   function  setLifetime( $newLifetime )
    {
         $this -> _options[ ' lifetime ' ]  =   $newLifetime ;
         $this -> _backend -> setDirectives( array (
             ' lifetime '   =>   $newLifetime
        ));
    }

     /* *
     * Test if a cache is available for the given id and (if yes) return it (false else)
     * 加载缓存 返回内容
     * @param string $id cache id
     * @param boolean $doNotTestCacheValidity if set to true, the cache validity won't be tested
     * @param boolean $doNotUnserialize do not serialize (even if automatic_serialization is true) => for internal use
     * @return mixed cached datas (or false)
      */
     public   function  load( $id ,   $doNotTestCacheValidity   =   false ,   $doNotUnserialize   =   false )
    {
         if  ( ! $this -> _options[ ' caching ' ]) {
             return   false ;
        }
         $this -> _lastId  =   $id ;     // 保存为最后一次使用的缓冲
        self :: _validateIdOrTag( $id );
         $data   =   $this -> _backend -> load( $id ,   $doNotTestCacheValidity );     // 采用后端模块加载缓存 得到被缓存的内容
         if  ( $data === false ) {
             //  no cache available
             return   false ;
        }
         if  (( ! $doNotUnserialize )  &&   $this -> _options[ ' automatic_serialization ' ]) {
             //  we need to unserialize before sending the result
             return   unserialize ( $data );     // 到内容进行　反序列化
        }
         return   $data ;
    }

     /* *
     * THIS METHOD IS DEPRECATED : USE LOAD() INSTEAD (same syntax) !
     * 为了兼容 早期zf 等同于 load 方法
     * it will be removed in ZF 1.1 !
      */
     public   function  get( $id ,   $doNotTestCacheValidity   =   false ,   $doNotUnserialize   =   false )
    {
         $this -> _log( " get() method is deprecated => use load() method instead (same syntax) ! " );
         return   $this -> load( $id ,   $doNotTestCacheValidity ,   $doNotUnserialize );
    }

     /* *
     * Test if a cache is available for the given id
     *    通过调用后端模块  检测缓存是否可用 
     * @param string $id cache id
     * @return boolean true is a cache is available, false else
      */
     public   function  test( $id )
    {
         if  ( ! $this -> _options[ ' caching ' ]) {
             return   false ;
        }
        self :: _validateIdOrTag( $id );
         $this -> _lastId  =   $id ;
         return   $this -> _backend -> test( $id );
    }

     /* *
     * Save some data in a cache 保存数据到缓存
     *
     * @param mixed $data data to put in cache (can be another type than string if automatic_serialization is on)
     *      $data 混合类型 如果不是字符窜类型 必须打开 automatic_serialization 
     * @param cache $id cache id (if not set, the last cache id will be used) 默认采用最后一次使用的缓存id
     * @param array $tags cache tags    标签数组
     * @param int $specificLifetime if != false, set a specific lifetime for this cache record (null => infinite lifetime)
     * @return boolean true if no problem
      */
     public   function  save( $data ,   $id   =   null ,   $tags   =   array () ,   $specificLifetime   =   false )
    {
         if  ( ! $this -> _options[ ' caching ' ]) {     // 不进行缓存
             return   true ;
        }
         if  ( is_null ( $id )) {
             $id   =   $this -> _lastId;
        }
        self :: _validateIdOrTag( $id );
        self :: _validateTagsArray( $tags );
         if  ( $this -> _options[ ' automatic_serialization ' ]) {
             //  we need to serialize datas before storing them
             $data   =   serialize ( $data );
        }  else  {
             if  ( ! is_string ( $data )) {
                Zend_Cache :: throwException( " Datas must be string or set automatic_serialization = true " );
            }
        }
         //  automatic cleaning 随机清理过期缓存
         if  ( $this -> _options[ ' automatic_cleaning_factor ' ]  >   0 ) {
             $rand   =   rand ( 1 ,   $this -> _options[ ' automatic_cleaning_factor ' ]);
             if  ( $rand == 1 ) {
                 if  ( $this -> _backend -> isAutomaticCleaningAvailable()) {
                     $this -> clean(Zend_Cache :: CLEANING_MODE_OLD);
                }  else  {
                     $this -> _log( ' Zend_Cache_Core::save() / automatic cleaning is not available with this backend ' );
                }
            }
        }
         $result   =   $this -> _backend -> save( $data ,   $id ,   $tags ,   $specificLifetime ); // 通过后台模块进行保存缓存
         if  ( ! $result ) {
             //  maybe the cache is corrupted, so we remove it !
             if  ( $this -> _options[ ' logging ' ]) {
                 $this -> _log( " Zend_Cache_Core::save() : impossible to save cache (id=$id) " );
            }
             $this -> remove( $id );
             return   false ;
        }
         if  ( $this -> _options[ ' write_control ' ]) {  // 写入时检测与原来的内容是否不一致
             $data2   =   $this -> _backend -> load( $id ,   true );     // 得到缓冲内容
             if  ( $data != $data2 ) {     // 内容不一样了 
                 $this -> _log( ' Zend_Cache_Core::save() / write_control : written and read data do not match ' );
                 $this -> remove( $id );     // 删除当前缓存 
                 return   false ;
            }
        }
         return   true ;
    }

     /* *
     * Remove a cache
     * 调用后端模块 删除指定id的缓存
     * @param string $id cache id to remove
     * @return boolean true if ok
      */
     public   function  remove( $id )
    {
         if  ( ! $this -> _options[ ' caching ' ]) {
             return   true ;
        }
        self :: _validateIdOrTag( $id );
         return   $this -> _backend -> remove( $id );
    }

     /* *
     * Clean cache entries
     * 调用后端模块 清除指定类型的缓存
     * Available modes are :
     * 'all' (default)  => remove all cache entries ($tags is not used)
     * 'old'            => remove too old cache entries ($tags is not used)
     * 'matchingTag'    => remove cache entries matching all given tags
     *                     ($tags can be an array of strings or a single string)
     * 'notMatchingTag' => remove cache entries not matching one of the given tags
     *                     ($tags can be an array of strings or a single string)
     *
     * @param string $mode
     * @param mixed $parameters
     * @return boolean true if ok
      */
     public   function  clean( $mode   =   ' all ' ,   $tags   =   array ())
    {
         if  ( ! $this -> _options[ ' caching ' ]) {
             return   true ;
        }
         if  ( ! in_array ( $mode ,   array (Zend_Cache :: CLEANING_MODE_ALL ,  Zend_Cache :: CLEANING_MODE_OLD ,  Zend_Cache :: CLEANING_MODE_MATCHING_TAG ,  Zend_Cache :: CLEANING_MODE_NOT_MATCHING_TAG))) {
            Zend_Cache :: throwException( ' Invalid cleaning mode ' );
        }
        self :: _validateTagsArray( $tags );
         return   $this -> _backend -> clean( $mode ,   $tags );
    }

     //  ------------------------------------
    // --- Private or protected methods ---
    // ------------------------------------

     /* *
     * Validate a cache id or a tag (security, reliable filenames, reserved prefixes...)
     * 检查缓存id格式 是否合法
     * 
     * Throw an exception if a problem is found
     *
     * @param string $string cache id or tag
      */
     private   static   function  _validateIdOrTag( $string )
    {
         if  ( ! is_string ( $string )) {     // 缓存id必须是字符窜
            Zend_Cache :: throwException( ' Invalid id or tag : must be a string ' );
        }
         if  ( substr ( $string ,   0 ,   9 )  ==   ' internal- ' ) {  // 是保留的关键字
            Zend_Cache :: throwException( ' "internal-*" ids or tags are reserved ' );
        }
         if  ( ! preg_match ( ' ~^[w]+$~ ' ,   $string )) {  // 使用了非法字符
            Zend_Cache :: throwException( ' Invalid id or tag : must use only [a-zA-Z0-9_] ' );
        }
    }

     /* *
     * Validate a tags array (security, reliable filenames, reserved prefixes...)
     *  检查缓存id数组 格式 是否合法
     * Throw an exception if a problem is found
     *
     * @param array $tags array of tags
      */
     private   static   function  _validateTagsArray( $tags )
    {
         if  ( ! is_array ( $tags )) {
            Zend_Cache :: throwException( ' Invalid tags array : must be an array ' );
        }
         foreach ( $tags   as   $tag ) {
            self :: _validateIdOrTag( $tag );
        }
         reset ( $tags );
    }

     /* *
     * Make sure if we enable logging that the Zend_Log class
     * is available.
     * Create a default log object if none is set.
     * 建立日志模块
     * @return void
     * @throws Zend_Cache_Exception
      */
     protected   function  _loggerSanity()
    {
         if  ( ! isset ( $this -> _options[ ' logging ' ])  ||   ! $this -> _options[ ' logging ' ]) {
             return ;
        }
         try  {
             require_once   ' Zend/Loader.php ' ;
            Zend_Loader :: loadClass( ' Zend_Log ' );
        }  catch  (Zend_Exception  $e ) {
            Zend_Cache :: throwException( ' Logging feature is enabled but the Zend_Log class is not available ' );
        }
         if  ( isset ( $this -> _options[ ' logger ' ])  &&   $this -> _options[ ' logger ' ] instanceof Zend_Log) {
             return ;
        }
         //  Create a default logger to the standard output stream
        Zend_Loader :: loadClass( ' Zend_Log_Writer_Stream ' );
         $logger   =   new  Zend_Log( new  Zend_Log_Writer_Stream( ' php://output ' ));
         $this -> _options[ ' logger ' ]  =   $logger ;
    }

     /* *
     * Log a message at the WARN (4) priority.
     * 记录日志
     * @param string $message
     * @return void
     * @throws Zend_Cache_Exception
      */
     protected   function  _log( $message ,   $priority   =   4 )
    {
         if  ( ! $this -> _options[ ' logging ' ]) {
             return ;
        }
         if  ( ! ( isset ( $this -> _options[ ' logger ' ])  ||   $this -> _options[ ' logger ' ] instanceof Zend_Log)) {
            Zend_Cache :: throwException( ' Logging is enabled but logger is not set ' );
        }
         $logger   =   $this -> _options[ ' logger ' ];
         $logger -> log ( $message ,   $priority );
    }

}