CI框架源码阅览-钩子类hooks.php

<?php  if ( ! defined('BASEPATH')) exit('No direct script access allowed');
/**
 * CodeIgniter
 *
 * An open source application development framework for PHP 5.1.6 or newer
 *
 * @package		CodeIgniter
 * @author		ExpressionEngine Dev Team
 * @copyright	Copyright (c) 2008 - 2011, EllisLab, Inc.
 * @license		http://codeigniter.com/user_guide/license.html
 * @link		http://codeigniter.com
 * @since		Version 1.0
 * @filesource
 */

// ------------------------------------

/**
 * CodeIgniter Hooks Class
 *
 * Provides 提供 a mechanism 机制 to extend the base system without hacking.
 * 用户手册地址：http://codeigniter.org.cn/user_guide/general/hooks.html
 * @package		CodeIgniter
 * @subpackage	Libraries
 * @category	Libraries
 * @author		ExpressionEngine Dev Team
 * @link		http://codeigniter.com/user_guide/libraries/encryption.html
 */
class CI_Hooks {

	/**
	 * Determines wether hooks are enabled
	 * 决定钩子是否启用
	 *
	 * @var bool
	 */
	var $enabled		= FALSE;
	/**
	 * List of all hooks set in config/hooks.php
	 *
	 * @var array
	 */
	var $hooks			= array();
	/**
	 * Determines wether hook is in progress, used to prevent 防止 infinte 无限 loops
	 *
	 * @var bool
	 */
	var $in_progress	= FALSE;

	/**
	 * Constructor
	 *
	 */
	function __construct()
	{
		$this->_initialize();
		log_message('debug', "Hooks Class Initialized");
	}

	// --------------------------------

	/**
	 * Initialize the Hooks Preferences 参数，首选项
	 * 初始化钩子
	 * @access	private
	 * @return	void
	 */
	function _initialize()
	{
		$CFG =& load_class('Config', 'core');

		// If hooks are not enabled in the config file
		// there is nothing else to do
		// 如果配置文件中设置了是不允许hooks，则直接返回退出本函数。
		if ($CFG->item('enable_hooks') == FALSE)
		{
			return;
		}

		// Grab the "hooks" definition file.
		// 抓取钩子的定义文件
		// If there are no hooks, we're done.
		// 如果没有定义hooks.php没有定义$hook数组我们直接返回

		if (defined('ENVIRONMENT') AND is_file(APPPATH.'config/'.ENVIRONMENT.'/hooks.php'))
		{
		    include(APPPATH.'config/'.ENVIRONMENT.'/hooks.php');
		}
		elseif (is_file(APPPATH.'config/hooks.php'))
		{
			include(APPPATH.'config/hooks.php');
		}


		if ( ! isset($hook) OR ! is_array($hook))
		{
			return;
		}
		
		// 将hooks.php 中的$hook数组引用到$this->hooks
		// 开启$this->enabled
		$this->hooks =& $hook;
		$this->enabled = TRUE;
	}

	// --------------------------------

	/**
	 * Call Hook
	 * 外部其实就是调用这个_call_hook函数进行调用钩子程序。
	 * 而此方法中再调用_run_hook去执行相应的钩子。
	 * Calls a particular hook
	 *
	 * @access	private
	 * @param	string	the hook name
	 * @return	mixed
	 */
	function _call_hook($which = '')
	{
		// 判断$this->enabled 是否开启 和 要调用的钩子是否在$htis->hooks中存在。
		if ( ! $this->enabled OR ! isset($this->hooks[$which]))
		{
			return FALSE;
		}
		
		// 判断要调用的钩子是否是一个二维数组，如果是就遍历执行。
		// 如果不是二维数组就直接执行
		// 这里说明，在一个挂钩点可以执行多个钩子，就是通过定义二维数组来实现的。
		if (isset($this->hooks[$which][0]) AND is_array($this->hooks[$which][0]))
		{
			foreach ($this->hooks[$which] as $val)
			{
				$this->_run_hook($val);
			}
		}
		else
		{
			$this->_run_hook($this->hooks[$which]);
		}

		return TRUE;
	}

	// --------------------------------

	/**
	 * Run Hook
	 * 运行钩子
	 * Runs a particular 特别的 hook
	 * 
	 * @access	private
	 * @param	array	the hook details
	 * @return	bool
	 */
	function _run_hook($data)
	{
		/*
		 * $data 就是我们在APPPATH/config/hook.php 定义的hook数组
         * $hook['pre_controller'] = array(
         *        'class'    => 'MyClass',
         *        'function' => 'Myfunction',
         *        'filename' => 'Myclass.php',
         *        'filepath' => 'hooks',
         *        'params'   => array('beer', 'wine', 'snacks')
         *         );
		 *
		 * 由于每一个钩子肯定是由数组组成的
		 * 所以这里就判断$data是不是数组如果不是则返回
		 * 
		 */
		if ( ! is_array($data))
		{
			return FALSE;
		}

		// -----------------------------------
		// Safety - Prevents run-away loops
		// -----------------------------------

		// If the script being called happens to have the same
		// hook call within it a loop can happen
		// 如果调用某一个hook，执行某些脚本，而有可能这些脚本里面再会触发其它hook
		// 如果这个其它hook里面又包含了当前
		// 的hook，那么就会进入死循环，这个in_progress的存在就是阻止这种情况。
		
		if ($this->in_progress == TRUE)
		{
			return;
		}

		// -----------------------------------
		// 取出data里面的数据，加载  APPPATH.$data['filepath'].$data['filename'];
        // Set file path
		// -----------------------------------

		if ( ! isset($data['filepath']) OR ! isset($data['filename']))
		{
			return FALSE;
		}

		$filepath = APPPATH.$data['filepath'].'/'.$data['filename'];

		if ( ! file_exists($filepath))
		{
			return FALSE;
		}

		// -----------------------------------
		// Set class/function name
		// -----------------------------------

		$class		= FALSE;
		$function	= FALSE;
		$params		= '';
		// 取出$hooks 中的class function params 
		if (isset($data['class']) AND $data['class'] != '')
		{
			$class = $data['class'];
		}

		if (isset($data['function']))
		{
			$function = $data['function'];
		}

		if (isset($data['params']))
		{
			$params = $data['params'];
		}

		if ($class === FALSE AND $function === FALSE)
		{
			return FALSE;
		}

		// -----------------------------------
		// Set the in_progress flag
		// 在开始执行钩子相应的程序之前，先把当前hook的状态设为正在运行中。
		// -----------------------------------
		
		$this->in_progress = TRUE;

		// -----------------------------------
		// Call the requested class and/or function
		// 包含钩子文件并实例化类，调用函数
		// -----------------------------------

		if ($class !== FALSE)
		{
			if ( ! class_exists($class))
			{
				require($filepath);
			}

			$HOOK = new $class;
			$HOOK->$function($params);
		}
		else
		{
			if ( ! function_exists($function))
			{
				require($filepath);
			}

			$function($params);
		}
		// 执行相应程序完毕后，重新把当前hook的状态改为非运行中
		// 以让它可以再次被触发。
		$this->in_progress = FALSE;
		return TRUE;
	}

}

// END CI_Hooks class

/* End of file Hooks.php */
/* Location: ./system/core/Hooks.php */