<!--?php
* CodeIgniter
*
* An open source application development framework for PHP
*
* This content is released under the MIT License (MIT)
*
* Copyright (c) 2014 - 2016, British Columbia Institute of Technology
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*
* @package   CodeIgniter
* @author   EllisLab Dev Team
* @copyright   Copyright (c) 2008 - 2014, EllisLab, Inc. ()
* @copyright   Copyright (c) 2014 - 2016, British Columbia Institute of Technology ()
* @license   MIT License
* @link
* @since   Version 1.0.0
* @filesource
*/
defined('BASEPATH') OR exit('No direct script access allowed');

/**
* Loader Class
*
* Loads framework components.
*
* @package       CodeIgniter
* @subpackage   Libraries
* @category   Loader
* @author       EllisLab Dev Team
* @link       /user_guide/libraries/loader.html
*/
class CI_Loader {

   // All these are set automatically. Don't mess with them.--所有這些變數都是自動設定的，請不要搞砸
   /**
   * level of the output buffering mechanism--buffer的巢狀層級
   *
   * @var   intNesting
   */
   protected $_ci_ob_level;

   /**
   * List of paths to load views from--載入檢視的路徑
   *
   * @var   array
   */
   protected $_ci_view_paths =   array(VIEWPATH   => TRUE);

   /**
   * List of paths to load libraries from--libraries的載入路徑
   *
   * @var   array
   */
   protected $_ci_library_paths =   array(APPPATH, BASEPATH);

   /**
   * List of paths to load models from--model的載入路徑
   *
   * @var   array
   */
   protected $_ci_model_paths =   array(APPPATH);

   /**
   * List of paths to load helpers from--第三方工具的載入路徑
   *
   * @var   array
   */
   protected $_ci_helper_paths =   array(APPPATH, BASEPATH);

   /**
   * List of cached variables--快取變數列表
   *
   * @var   array
   */
   protected $_ci_cached_vars =   array();

   /**
   * List of loaded classes--已經載入的類列表
   *
   * @var   array
   */
   protected $_ci_classes =   array();

   /**
   * List of loaded models--已經載入的models列表
   *
   * @var   array
   */
   protected $_ci_models =   array();

   /**
   * List of loaded helpers--已經載入的helper列表
   *
   * @var   array
   */
   protected $_ci_helpers =   array();

   /**
   *鍵到類名的一個匹配，可以自己設定
   * List of class name mappings
   *
   * @var   array
   */
   protected $_ci_varmap =   array(
       'unit_test' => 'unit',
       'user_agent' => 'agent'
   );

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

   /**
   *建構函式
   * Class constructor
   *設定元件的載入路徑，獲取初始化輸出buffer的巢狀層級
   * Sets component load paths, gets the initial output buffering level.
   *不返回值
   * @return   void
   */
   public function __construct()
   {
       //獲取巢狀層級
       $this->_ci_ob_level = ob_get_level();
       //獲取已經初始化的class列表（初始化指的是已經例項化的類）
       $this->_ci_classes =& is_loaded();

       log_message('info', 'Loader Class Initialized');
   }

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

   /**
   *初始化，其實就是將$outload中配置的檔案載入進來（包括config，libraries)
   * Initializer
   *
   * @todo   Figure out a way to move this to the constructor
   *       without breaking *package_path*() methods.
   *使用了CI_Loader::_ci_autoloader函式
   * @uses   CI_Loader::_ci_autoloader()
   *被CI_Controller::__construct()函式使用
   * @used-by   CI_Controller::__construct()
   * @return   void
   */
   public function initialize()
   {
       //載入libraris，models，config，database類
       $this->_ci_autoloader();
   }

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

   /**
   *判斷類是否已經載入
   * Is Loaded
   *
   * A utility method to test if a class is in the self::$_ci_classes array.
   *
   * @used-by   Mainly used by Form Helper function _get_validation_object().
   *
   *返回存在的物件或者False
   * @param    string       $class   Class name to check for
   * @return    string|bool   Class object name if loaded or FALSE
   */
   public function is_loaded($class)
   {
       return array_search(ucfirst($class), $this->_ci_classes, TRUE);
   }

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

   /**
   * Library Loader
   *
   *載入並初始化libraries
   * Loads and instantiates libraries.
   *設計由application controllers呼叫
   * Designed to be called from application controllers.
   *
   * @param   string   $library   Library name
   * @param   array   $params       Optional parameters to pass to the library class constructor
   * @param   string   $object_name   An optional object name to assign to
   * @return   object
   */
   public function library($library, $params = NULL, $object_name = NULL)
   {
       if (empty($library))
       {
           return $this;
       }
       elseif (is_array($library))
       {
           foreach ($library as $key => $value)
           {
               //鍵值為int
               if (is_int($key))
               {
                   $this->library($value, $params);
               }
               //鍵值為非int
               else
               {
                   $this->library($key, $params, $value);
               }
           }

           return $this;
       }
        //$params必須為非空陣列
       if ($params !== NULL && ! is_array($params))
       {
           $params = NULL;
       }

       $this->_ci_load_library($library, $params, $object_name);
       return $this;
   }

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

   /**
   * Model Loader
   *
   * Loads and instantiates models.
   *
   * @param   string   $model       Model name
   * @param   string   $name       An optional object name to assign to
   * @param   bool   $db_conn   An optional database connection configuration to initialize
   * @return   object
   */
   public function model($model, $name = '', $db_conn = FALSE)
   {
       if (empty($model))
       {
           return $this;
       }
       elseif (is_array($model))
       {
           //遍歷$model
           foreach ($model as $key => $value)
           {
               //$key是int，則將$value當作model，如果$key不是int，則將key當作是$model
               is_int($key) ? $this->model($value, '', $db_conn) : $this->model($key, $value, $db_conn);
           }

           return $this;
       }

       $path = '';

       // Is the model in a sub-folder? If so, parse out the filename and path.
       //是否model在一個子資料夾中，如果是，則解析檔名和路徑
       if (($last_slash = strrpos($model, '/')) !== FALSE)
       {
           // The path is in front of the last slash
           $path = substr($model, 0, ++$last_slash);

           // And the model name behind it
           $model = substr($model, $last_slash);
       }

       if (empty($name))
       {
           $name = $model;
       }
        //如果在$this->_ci_models找到了該類名，則直接返回$this
       if (in_array($name, $this->_ci_models, TRUE))
       {
           return $this;
       }
        //獲取CI例項
       $CI =& get_instance();
       //如果CI例項中已經存在$name例項，則丟擲異常
       if (isset($CI->$name))
       {
           throw new RuntimeException('The model name you are loading is the name of a resource that is already being used: '.$name);
       }
        //$db_conn!==FALSE,並且不存在CI_DB類的情況下，說明沒有初始化DB例項
       if ($db_conn !== FALSE && ! class_exists('CI_DB', FALSE))
       {
           if ($db_conn === TRUE)
           {
               $db_conn = '';
           }
            //初始化DB例項
           $this->database($db_conn, FALSE, TRUE);
       }

       // Note: All of the code under this condition used to be just:
       //
       //       load_class('Model', 'core');
       //
       //       However, load_class() instantiates classes
       //       to cache them for later use and that prevents
       //       MY_Model from being an abstract class and is
       //       sub-optimal otherwise anyway.
       if ( ! class_exists('CI_Model', FALSE))
       {
           $app_path = APPPATH.'core'.DIRECTORY_SEPARATOR;
           if (file_exists($app_path.'Model.php'))
           {
               //require基類
               require_once($app_path.'Model.php');
               //require基類後仍然不存子CI_Model,則丟擲異常
               if ( ! class_exists('CI_Model', FALSE))
               {
                   throw new RuntimeException($app_path."Model.php exists, but doesn't declare class CI_Model");
               }
           }
           //如果有環境的Model.php,則載入
           elseif ( ! class_exists('CI_Model', FALSE))
           {
               require_once(BASEPATH.'core'.DIRECTORY_SEPARATOR.'Model.php');
           }
            //require帶字首的Model,如：$apps_path./ls_Model
           $class = config_item('subclass_prefix').'Model';
           if (file_exists($app_path.$class.'.php'))
           {
               require_once($app_path.$class.'.php');
               if ( ! class_exists($class, FALSE))
               {
                   throw new RuntimeException($app_path.$class.".php exists, but doesn't declare class ".$class);
               }
           }
       }

       $model = ucfirst($model);
       if ( ! class_exists($model))
       {
           //遍歷$this->_ci_model_paths的路徑，尋早model，並require
           foreach ($this->_ci_model_paths as $mod_path)
           {
               if ( ! file_exists($mod_path.'models/'.$path.$model.'.php'))
               {
                   continue;
               }

               require_once($mod_path.'models/'.$path.$model.'.php');
               if ( ! class_exists($model, FALSE))
               {
                   throw new RuntimeException($mod_path."models/".$path.$model.".php exists, but doesn't declare class ".$model);
               }

               break;
           }
            //require之後，仍然沒找到，丟擲異常
           if ( ! class_exists($model, FALSE))
           {
               throw new RuntimeException('Unable to locate the model you have specified: '.$model);
           }
       }
       //如果model類沒有繼承CI_Model,丟擲異常
       elseif ( ! is_subclass_of($model, 'CI_Model'))
       {
           throw new RuntimeException("Class ".$model." already exists and doesn't extend CI_Model");
       }
        //將要例項化的model類存入$this->_ci_models[]，表示已經載入過的model類
       $this->_ci_models[] = $name;
       //例項化，並返回
       $CI->$name = new $model();
       return $this;
   }

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

   /**
   * Database Loader
   *
   * @param   mixed   $params       Database configuration options
   * @param   bool   $return    Whether to return the database object
   * @param   bool   $query_builder   Whether to enable Query Builder
   *                   (overrides the configuration setting)
   *
   * @return   object|bool   Database object if $return is set to TRUE,
   *                   FALSE on failure, CI_Loader instance in any other case
   */
   public function database($params = '', $return = FALSE, $query_builder = NULL)
   {
       // Grab the super object
       //獲取超級物件
       $CI =& get_instance();

       // Do we even need to load the database class?
       //isset($CI->db) && is_object($CI->db) && ! empty($CI->db->conn_id)，這裡判斷$CI->db是否已經例項化，如果例項化了，就直接返回
       if ($return === FALSE && $query_builder === NULL && isset($CI->db) && is_object($CI->db) && ! empty($CI->db->conn_id))
       {
           return FALSE;
       }
        //include DB.php
       require_once(BASEPATH.'database/DB.php');

       if ($return === TRUE)
       {
           return DB($params, $query_builder);
       }

       // Initialize the db variable. Needed to prevent
       // reference errors with some configurations
       //初始化db變數
       $CI->db = '';

       // Load the DB class
       //載入db class,並例項化
       $CI->db =& DB($params, $query_builder);
       return $this;
   }

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

   /**
   * Load the Database Utilities Class
   *
   * @param   object   $db   Database object
   * @param   bool   $return   Whether to return the DB Utilities class object or not
   * @return   object
   */
   public function dbutil($db = NULL, $return = FALSE)
   {
       $CI =& get_instance();

       if ( ! is_object($db) OR ! ($db instanceof CI_DB))
       {
           class_exists('CI_DB', FALSE) OR $this->database();
           $db =& $CI->db;
       }

       require_once(BASEPATH.'database/DB_utility.php');
       require_once(BASEPATH.'database/drivers/'.$db->dbdriver.'/'.$db->dbdriver.'_utility.php');
       $class = 'CI_DB_'.$db->dbdriver.'_utility';

       if ($return === TRUE)
       {
           return new $class($db);
       }

       $CI->dbutil = new $class($db);
       return $this;
   }

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

   /**
   * Load the Database Forge Class
   *
   * @param   object   $db   Database object
   * @param   bool   $return   Whether to return the DB Forge class object or not
   * @return   object
   */
   public function dbforge($db = NULL, $return = FALSE)
   {
       $CI =& get_instance();
       if ( ! is_object($db) OR ! ($db instanceof CI_DB))
       {
           //存在CI_DB類，返回ture，否則例項化CI_DB類
           class_exists('CI_DB', FALSE) OR $this->database();
           $db =& $CI->db;
       }

       require_once(BASEPATH.'database/DB_forge.php');
       require_once(BASEPATH.'database/drivers/'.$db->dbdriver.'/'.$db->dbdriver.'_forge.php');
        //載入子驅動
       if ( ! empty($db->subdriver))
       {
           $driver_path = BASEPATH.'database/drivers/'.$db->dbdriver.'/subdrivers/'.$db->dbdriver.'_'.$db->subdriver.'_forge.php';
           if (file_exists($driver_path))
           {
               require_once($driver_path);
               //獲取子驅動類名
               $class = 'CI_DB_'.$db->dbdriver.'_'.$db->subdriver.'_forge';
           }
       }
       else
       {
           //獲取工具驅動類名
           $class = 'CI_DB_'.$db->dbdriver.'_forge';
       }
        //需要直接返回
       if ($return === TRUE)
       {
           //例項化
           return new $class($db);
       }
        //例項化驅動類
       $CI->dbforge = new $class($db);
       return $this;
   }

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

   /**
   *檢視載入
   * View Loader
   *
   * Loads "view" files.
   *
   *檢視的名稱
   * @param   string   $view   View name
   *將控制器的資料（例：$data陣列）分發到檢視中
   * @param   array   $vars   An associative array of data
   *               to be extracted for use in the view
   * @param   bool   $return   Whether to return the view output
   *               or leave it to the Output class
   * @return   object|string
   */
   public function view($view, $vars = array(), $return = FALSE)
   {
       return $this->_ci_load(array('_ci_view' => $view, '_ci_vars' => $this->_ci_object_to_array($vars), '_ci_return' => $return));
   }

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

   /**
   * Generic File Loader
   *
   * @param   string   $path   File path
   * @param   bool   $return   Whether to return the file output
   * @return   object|string
   */
   public function file($path, $return = FALSE)
   {
       return $this->_ci_load(array('_ci_path' => $path, '_ci_return' => $return));
   }

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

   /**
   * Set Variables
   *
   *一旦變數設定，他們有變成可行的在控制器類和檢視檔案中
   * Once variables are set they become available within
   * the controller class and its "view" files.
   *
   * @param   array|object|string   $vars
   *                   An associative array or object containing values
   *                   to be set, or a value's name if string
   * @param    string   $val   Value to set, only used if $vars is a string
   * @return   object
   */
   public function vars($vars, $val = '')
   {
       if (is_string($vars))
       {
           $vars = array($vars => $val);
       }

       $vars = $this->_ci_object_to_array($vars);

       if (is_array($vars) && count($vars) > 0)
       {
           foreach ($vars as $key => $val)
           {
               //放入快取的變數
               $this->_ci_cached_vars[$key] = $val;
           }
       }

       return $this;
   }

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

   /**
   *清除快取變數
   * Clear Cached Variables
   *
   * Clears the cached variables.
   *
   * @return   CI_Loader
   */
   public function clear_vars()
   {
       $this->_ci_cached_vars = array();
       return $this;
   }

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

   /**
   * Get Variable
   *
   *檢查變數是否設定並獲取它
   * Check if a variable is set and retrieve it.
   *
   * @param   string   $key   Variable name
   * @return   mixed   The variable or NULL if not found
   */
   public function get_var($key)
   {
       return isset($this->_ci_cached_vars[$key]) ? $this->_ci_cached_vars[$key] : NULL;
   }

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

   /**
   * Get Variables
   *
   *返回所有load的物件
   * Retrieves all loaded variables.
   *
   * @return   array
   */
   public function get_vars()
   {
       return $this->_ci_cached_vars;
   }

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

   /**
   *load第三方工具
   * Helper Loader
   *
   *參數列示要載入的三方工具filenames
   * @param   string|string[]   $helpers   Helper name(s)
   * @return   object
   */
   public function helper($helpers = array())
   {
       foreach ($this->_ci_prep_filename($helpers, '_helper') as $helper)
       {
           if (isset($this->_ci_helpers[$helper]))
           {
               continue;
           }

           // Is this a helper extension request?
           //是否是helper的擴充套件請求
           $ext_helper = config_item('subclass_prefix').$helper;
           $ext_loaded = FALSE;
           foreach ($this->_ci_helper_paths as $path)
           {
               //是否有$ext_helper這檔案，有則包含
               if (file_exists($path.'helpers/'.$ext_helper.'.php'))
               {
                   include_once($path.'helpers/'.$ext_helper.'.php');
                   $ext_loaded = TRUE;
               }
           }

           // If we have loaded extensions - check if the base one is here
           //如果載入了擴充套件，則檢查base檔案是否load
           if ($ext_loaded === TRUE)
           {
               $base_helper = BASEPATH.'helpers/'.$helper.'.php';
               if ( ! file_exists($base_helper))
               {
                   show_error('Unable to load the requested file: helpers/'.$helper.'.php');
               }
                //載入base file
               include_once($base_helper);
               $this->_ci_helpers[$helper] = TRUE;
               log_message('info', 'Helper loaded: '.$helper);
               continue;
           }

           // No extensions found ... try loading regular helpers and/or overrides
           //如果沒有擴充套件發現，則嘗試載入規則的helper
           foreach ($this->_ci_helper_paths as $path)
           {
               if (file_exists($path.'helpers/'.$helper.'.php'))
               {
                   include_once($path.'helpers/'.$helper.'.php');

                   $this->_ci_helpers[$helper] = TRUE;
                   log_message('info', 'Helper loaded: '.$helper);
                   break;
               }
           }

           // unable to load the helper
           //如果載入helper失敗，則顯示錯誤資訊
           if ( ! isset($this->_ci_helpers[$helper]))
           {
               show_error('Unable to load the requested file: helpers/'.$helper.'.php');
           }
       }

       return $this;
   }

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

   /**
   * Load Helpers
   *
   *這是helper函式的一個別名
   * An alias for the helper() method in case the developer has
   * written the plural form of it.
   *
   * @uses   CI_Loader::helper()
   * @param   string|string[]   $helpers   Helper name(s)
   * @return   object
   */
   public function helpers($helpers = array())
   {
       return $this->helper($helpers);
   }

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

   /**
   * Language Loader
   *
   * Loads language files.
   *
   *該引數為要load的language檔案
   * @param   string|string[]   $files   List of language file names to load
   * @param   string       Language name
   * @return   object
   */
   public function language($files, $lang = '')
   {
       get_instance()->lang->load($files, $lang);
       return $this;
   }

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

   /**
   * Config Loader
   *載入一個配置檔案，參看CI_Config::load()
   * Loads a config file (an alias for CI_Config::load()).
   *
   * @uses   CI_Config::load()
   * @param   string   $file           Configuration file name
   * @param   bool   $use_sections       Whether configuration values should be loaded into their own section
   * @param   bool   $fail_gracefully   Whether to just return FALSE or display an error message
   * @return   bool   TRUE if the file was loaded correctly or FALSE on failure
   */
   public function config($file, $use_sections = FALSE, $fail_gracefully = FALSE)
   {
       return get_instance()->config->load($file, $use_sections, $fail_gracefully);
   }

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

   /**
   *驅動載入
   * Driver Loader
   *載入驅動庫，這些繼承自CI_Driver_library
   * Loads a driver library.
   *
   * @param   string|string[]   $library   Driver name(s)
   * @param   array       $params       Optional parameters to pass to the driver
   * @param   string       $object_name   An optional object name to assign to
   *
   * @return   object|bool   Object or FALSE on failure if $library is a string
   *               and $object_name is set. CI_Loader instance otherwise.
   */
   public function driver($library, $params = NULL, $object_name = NULL)
   {
       //如果是陣列
       if (is_array($library))
       {
           //則迭代
           foreach ($library as $driver)
           {
               $this->driver($driver);
           }

           return $this;
       }
       //library為空
       elseif (empty($library))
       {
           return FALSE;
       }
        //如果無CI_Driver_Library，則載入BASEPATH.'libraries/Driver.php'
       if ( ! class_exists('CI_Driver_Library', FALSE))
       {
           // We aren't instantiating an object here, just making the base class available
           //我們沒有在這裡初始化一個物件，僅僅是包含了該檔案
           require BASEPATH.'libraries/Driver.php';
       }

       // We can save the loader some time since Drivers will *always* be in a subfolder,
       // and typically identically named to the library
       //沒有找到/分隔符
       if ( ! strpos($library, '/'))
       {
           $library = ucfirst($library).'/'.$library;
       }

       return $this->library($library, $params, $object_name);
   }

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

   /**
   * Add Package Path
   *
   * Prepends a parent path to the library, model, helper and config
   * path arrays.
   *
   * @see   CI_Loader::$_ci_library_paths
   * @see   CI_Loader::$_ci_model_paths
   * @see CI_Loader::$_ci_helper_paths
   * @see CI_Config::$_config_paths
   *
   * @param   string   $path       Path to add
   * @param    bool   $view_cascade   (default: TRUE)
   * @return   object
   */
   public function add_package_path($path, $view_cascade = TRUE)
   {
       $path = rtrim($path, '/').'/';
        //插入陣列
       array_unshift($this->_ci_library_paths, $path);
       array_unshift($this->_ci_model_paths, $path);
       array_unshift($this->_ci_helper_paths, $path);

       $this->_ci_view_paths = array($path.'views/' => $view_cascade) + $this->_ci_view_paths;

       // Add config file path
       $config =& $this->_ci_get_component('config');
       //配置檔案加入該路路徑
       $config->_config_paths[] = $path;

       return $this;
   }

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

   /**
   * Get Package Paths
   *
   * Return a list of all package paths.
   *
   *是否包含BASEPATH
   * @param   bool   $include_base   Whether to include BASEPATH (default: FALSE)
   * @return   array
   */
   public function get_package_paths($include_base = FALSE)
   {
       //預設返回的是_ci_model_paths
       return ($include_base === TRUE) ? $this->_ci_library_paths : $this->_ci_model_paths;
   }

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

   /**
   * Remove Package Path
   *
   * Remove a path from the library, model, helper and/or config
   * path arrays if it exists. If no path is provided, the most recently
   * added path will be removed removed.
   *
   * @param   string   $path   Path to remove
   * @return   object
   */
   public function remove_package_path($path = '')
   {
       $config =& $this->_ci_get_component('config');

       if ($path === '')
       {
           //去除掉以下路徑
           array_shift($this->_ci_library_paths);
           array_shift($this->_ci_model_paths);
           array_shift($this->_ci_helper_paths);
           array_shift($this->_ci_view_paths);
           //最後一個元素出棧
           array_pop($config->_config_paths);
       }
       else
       {
           $path = rtrim($path, '/').'/';
           foreach (array('_ci_library_paths', '_ci_model_paths', '_ci_helper_paths') as $var)
           {
               //找出要消除的$key
               if (($key = array_search($path, $this->{$var})) !== FALSE)
               {
                   //刪除變數
                   unset($this->{$var}[$key]);
               }
           }
            //對於_ci_view_paths
           if (isset($this->_ci_view_paths[$path.'views/']))
           {
               //刪除變數
               unset($this->_ci_view_paths[$path.'views/']);
           }
            //這個同上foreach，但是$config->_config_paths無法用$this指代，所以單獨起了一個條件
           if (($key = array_search($path, $config->_config_paths)) !== FALSE)
           {
               unset($config->_config_paths[$key]);
           }
       }

       // make sure the application default paths are still in the array
       //檢查預設的路徑仍然在以下陣列中
       $this->_ci_library_paths = array_unique(array_merge($this->_ci_library_paths, array(APPPATH, BASEPATH)));
       $this->_ci_helper_paths = array_unique(array_merge($this->_ci_helper_paths, array(APPPATH, BASEPATH)));
       $this->_ci_model_paths = array_unique(array_merge($this->_ci_model_paths, array(APPPATH)));
       $this->_ci_view_paths = array_merge($this->_ci_view_paths, array(APPPATH.'views/' => TRUE));
       $config->_config_paths = array_unique(array_merge($config->_config_paths, array(APPPATH)));

       return $this;
   }

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

   /**
   *內部CI的資料載入器
   * Internal CI Data Loader
   *
   *用來load檢視和檔案
   * Used to load views and files.
   *
   * Variables are prefixed with _ci_ to avoid symbol collision with
   * variables made available to view files.
   *
   * @used-by   CI_Loader::view()
   * @used-by   CI_Loader::file()
   * @param   array   $_ci_data   Data to load
   * @return   object
   */
   protected function _ci_load($_ci_data)
   {
       // Set the default data variables
       foreach (array('_ci_view', '_ci_vars', '_ci_path', '_ci_return') as $_ci_val)
       {
           //$$_ci_val,如果$_ci_val='_ci_view'，則下面語句定義了$ci_view=$_ci_data['_ci_view']
           $$_ci_val = isset($_ci_data[$_ci_val]) ? $_ci_data[$_ci_val] : FALSE;
       }

       $file_exists = FALSE;

       // Set the path to the requested file
       //如果設定了$_ci_path，說明是獲取檔案
       if (is_string($_ci_path) && $_ci_path !== '')
       {
           $_ci_x = explode('/', $_ci_path);
           //獲取檔名
           $_ci_file = end($_ci_x);
       }
       else
       {
           //返回檢視的副檔名
           $_ci_ext = pathinfo($_ci_view, PATHINFO_EXTENSION);
           //獲取ci_view的檔名
           $_ci_file = ($_ci_ext === '') ? $_ci_view.'.php' : $_ci_view;
            //$this->_ci_view_paths的初始值為array(VIEWPATH=>TRUE),VIEWPATH在index.php中定義
           foreach ($this->_ci_view_paths as $_ci_view_file => $cascade)
           {
               if (file_exists($_ci_view_file.$_ci_file))
               {
                   //賦值給$_ci_path
                   $_ci_path = $_ci_view_file.$_ci_file;
                   $file_exists = TRUE;
                   break;
               }

               if ( ! $cascade)
               {
                   break;
               }
           }
       }
        //
       if ( ! $file_exists && ! file_exists($_ci_path))
       {
           show_error('Unable to load the requested file: '.$_ci_file);
       }

       // This allows anything loaded using $this->load (views, files, etc.)
       // to become accessible from within the Controller and Model functions.
       //這允許被$this->load載入的任何（view，files，etc)內容成為可訪問的在在控制器和Model functions中。
       //注意檢視是從load類中include，所以檢視中的$this,在控制器中就是$this->load
       $_ci_CI =& get_instance();
       foreach (get_object_vars($_ci_CI) as $_ci_key => $_ci_var)
       {
           //如果沒有設定$this->$_ci_key，則用&$_ci_CI->$_ci_key引用
           if ( ! isset($this->$_ci_key))
           {
               $this->$_ci_key =& $_ci_CI->$_ci_key;
           }
       }

       /*
       * Extract and cache variables
       *
       * You can either set variables using the dedicated $this->load->vars()
       * function or via the second parameter of this function. We'll merge
       * the two types and cache them so that views that are embedded within
       * other views can have access to these variables.
       */
       if (is_array($_ci_vars))
       {
           $this->_ci_cached_vars = array_merge($this->_ci_cached_vars, $_ci_vars);
       }
       //鍵名成單獨變數
       extract($this->_ci_cached_vars);

       /*
       * Buffer the output
       *
       * We buffer the output for two reasons:--我們buffer輸出有兩個原因
       * 1. Speed. You get a significant speed boost.--第一，你得到了一個顯著的速度提升
       * 2. So that the final rendered template can be post-processed by--第二，將結果（buffer中的內容）提交到output class來渲染模版
       *   the output class. Why do we need post processing? For one thing,--為什麼要提交到output class處理呢？
       *   in order to show the elapsed page load time. Unless we can--一方面，為了顯示頁面的load時間（在傳送到瀏覽器之前，除非我們能正確的擷取內容，然後停止計時器，但是它可能不準確）
       *   intercept the content right before it's sent to the browser and
       *   then stop the timer it won't be accurate.
       */
       ob_start();

       // If the PHP installation does not support short tags we'll
       // do a little string replacement, changing the short tags
       // to standard PHP echo statements.--如果在php安裝的時候沒有支援短標記，我們將做一點字串的替換
       if ( ! is_php('5.4') && ! ini_get('short_open_tag') && config_item('rewrite_short_tags') === TRUE)
       {
           //短標記用長標記替代，另外'; \?\>'用'; \?\>'替代，不能用多個空格,eval把檢視中的在''裡邊的程式碼執行了
           echo eval('?>'.preg_replace('/;*\s*\?>/', '; ?>', str_replace('<!--?=', '<?php echo ', file_get_contents($_ci_path))));
       else
       {
           include($_ci_path); // include() vs include_once() allows for multiple views with the same name
       }

       log_message('info', 'File loaded: '.$_ci_path);

       // Return the file data if requested
       if ($_ci_return === TRUE)
       {
           $buffer = ob_get_contents();
           @ob_end_clean();
           //返回view
           return $buffer;
       }

       /*
       * Flush the buffer... or buff the flusher?
       *
       * In order to permit views to be nested within
       * other views, we need to flush the content back out whenever
       * we are beyond the first level of output buffering so that
       * it can be seen and included properly by the first included
       * template and any subsequent ones. Oy!
       */
       if (ob_get_level() > $this->_ci_ob_level + 1)
       {
           ob_end_flush();
       }
       else
       {
           $_ci_CI->output->append_output(ob_get_contents());
           @ob_end_clean();
       }

       return $this;
   }

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

   /**
   *內部CI Library Loader
   *故名思議是load，但是該函式只是require或者include必要的檔案，真正例項化是要呼叫CI_Loader::_ci_init_library()函式
   * Internal CI Library Loader
   *
   * @used-by   CI_Loader::library()
   * @uses   CI_Loader::_ci_init_library()
   *
   *$class可以是帶路徑檔名，或者是檔名
   * @param   string   $class       Class name to load
   * @param   mixed   $params       Optional parameters to pass to the class constructor
   * @param   string   $object_name   Optional object name to assign to
   * @return   void
   */
   protected function _ci_load_library($class, $params = NULL, $object_name = NULL)
   {
       // Get the class name, and while we're at it trim any slashes.
       // The directory path can be included as part of the class name,
       // but we don't want a leading slash
       //去掉path兩邊的/,去掉.php的字尾
       $class = str_replace('.php', '', trim($class, '/'));

       // Was the path included with the class name?
       // We look for a slash to determine this
       //如果$class中有/說明是一個路徑
       if (($last_slash = strrpos($class, '/')) !== FALSE)
       {
           // Extract the path
           //抽取路徑
           $subdir = substr($class, 0, ++$last_slash);

           // Get the filename from the path
           //獲得$class name
           $class = substr($class, $last_slash);
       }
       else
       {
           $subdir = '';
       }
        //首字母大寫
       $class = ucfirst($class);

       // Is this a stock library? There are a few special conditions if so ...
       //是否有一個library的子目錄
       if (file_exists(BASEPATH.'libraries/'.$subdir.$class.'.php'))
       {
           return $this->_ci_load_stock_library($class, $subdir, $params, $object_name);
       }

       // Let's search for the requested and load it.
       //讓我們搜尋請求的 library file，並載入
       foreach ($this->_ci_library_paths as $path)
       {
           // BASEPATH has already been checked for
           if ($path === BASEPATH)
           {
               continue;
           }

           $filepath = $path.'libraries/'.$subdir.$class.'.php';

           // Safety: Was the class already loaded by a previous call?
           //安全：是否class先前已經被load
           if (class_exists($class, FALSE))
           {
               // Before we deem this to be a duplicate request, let's see
               // if a custom object name is being supplied. If so, we'll
               // return a new instance of the object
               //在我們確認這是一個重複的請求前，如果確認自定義的物件名提供，
               //則我們返回一個新的例項
               if ($object_name !== NULL)
               {
                   $CI =& get_instance();
                   //$CI不存在這個物件
                   if ( ! isset($CI->$object_name))
                   {
                       //例項化該類，並返回（void)
                       return $this->_ci_init_library($class, '', $params, $object_name);
                   }
               }

               log_message('debug', $class.' class already loaded. Second attempt ignored.');
               return;
           }
           // Does the file exist? No? Bummer...
           elseif ( ! file_exists($filepath))
           {
               continue;
           }

           include_once($filepath);
           return $this->_ci_init_library($class, '', $params, $object_name);
       }

       // One last attempt. Maybe the library is in a subdirectory, but it wasn't specified?
       //最後一個企圖，也許library是一個子目錄，但是沒有指定
       if ($subdir === '')
       {
           //例項化該類並返回
           return $this->_ci_load_library($class.'/'.$class, $params, $object_name);
       }

       // If we got this far we were unable to find the requested class.
       log_message('error', 'Unable to load the requested class: '.$class);
       show_error('Unable to load the requested class: '.$class);
   }

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

   /**
   *故名思議是load，但是該函式只是require或者include必要的檔案，真正例項化是要呼叫CI_Loader::_ci_init_library()函式
   * Internal CI Stock Library Loader
   *
   * @used-by   CI_Loader::_ci_load_library()
   * @uses   CI_Loader::_ci_init_library()
   *
   *這裡是一個檔名，不帶路徑
   * @param   string   $library   Library name to load
   * @param   string   $file_path   Path to the library filename, relative to libraries/
   * @param   mixed   $params       Optional parameters to pass to the class constructor
   * @param   string   $object_name   Optional object name to assign to
   * @return   void
   */
   protected function _ci_load_stock_library($library_name, $file_path, $params, $object_name)
   {
       $prefix = 'CI_';
        //如果存在帶字首的$prefix.$library_name類名，說明檔案已經載入
       if (class_exists($prefix.$library_name, FALSE))
       {
           //如果存在config_item('subclass_prefix').$library_name類，則將字首置為config_item('subclass_prefix');
           if (class_exists(config_item('subclass_prefix').$library_name, FALSE))
           {
               $prefix = config_item('subclass_prefix');
           }

           // Before we deem this to be a duplicate request, let's see
           // if a custom object name is being supplied. If so, we'll
           // return a new instance of the object
           if ($object_name !== NULL)
           {
               $CI =& get_instance();
               //如果$CI->$object_name不存在，也就是沒有重複載入，則例項化
               if ( ! isset($CI->$object_name))
               {
                   //例項化（注意，這裡的prefix帶有值的）
                   return $this->_ci_init_library($library_name, $prefix, $params, $object_name);
               }
           }

           log_message('debug', $library_name.' class already loaded. Second attempt ignored.');
           return;
       }

       $paths = $this->_ci_library_paths;
       array_pop($paths); // BASEPATH
       array_pop($paths); // APPPATH (needs to be the first path checked)
       array_unshift($paths, APPPATH);

       foreach ($paths as $path)
       {
           if (file_exists($path = $path.'libraries/'.$file_path.$library_name.'.php'))
           {
               // Override
               include_once($path);
               if (class_exists($prefix.$library_name, FALSE))
               {
                   return $this->_ci_init_library($library_name, $prefix, $params, $object_name);
               }
               else
               {
                   log_message('debug', $path.' exists, but does not declare '.$prefix.$library_name);
               }
           }
       }

       include_once(BASEPATH.'libraries/'.$file_path.$library_name.'.php');

       // Check for extensions
       $subclass = config_item('subclass_prefix').$library_name;
       foreach ($paths as $path)
       {
           if (file_exists($path = $path.'libraries/'.$file_path.$subclass.'.php'))
           {
               include_once($path);
               if (class_exists($subclass, FALSE))
               {
                   $prefix = config_item('subclass_prefix');
                   break;
               }
               else
               {
                   log_message('debug', $path.' exists, but does not declare '.$subclass);
               }
           }
       }

       return $this->_ci_init_library($library_name, $prefix, $params, $object_name);
   }

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

   /**
   *內部類庫的例項化
   * Internal CI Library Instantiator
   *
   *被以下函式呼叫
   * @used-by   CI_Loader::_ci_load_stock_library()
   * @used-by   CI_Loader::_ci_load_library()
   *
   * @param   string       $class       Class name
   * @param   string       $prefix       Class name prefix
   *例項初始化的一些配置引數
   * @param   array|null|bool   $config       Optional configuration to pass to the class constructor:
   *                       FALSE to skip;
   *                       NULL to search in config paths;
   *                       array containing configuration data
   * @param   string       $object_name   Optional object name to assign to
   * @return   void
   */
   protected function _ci_init_library($class, $prefix, $config = FALSE, $object_name = NULL)
   {
       // Is there an associated config file for this class? Note: these should always be lowercase
       if ($config === NULL)
       {
           // Fetch the config paths containing any package paths
           //這裡獲取$CI_Config的例項以及包路徑
           $config_component = $this->_ci_get_component('config');

           if (is_array($config_component->_config_paths))
           {
               $found = FALSE;
               foreach ($config_component->_config_paths as $path)
               {
                   // We test for both uppercase and lowercase, for servers that
                   // are case-sensitive with regard to file names. Load global first,
                   // override with environment next
                   //我們測試大寫與小寫，對於檔名來說，大小寫是敏感的。我們先載入全域性的，然後用環境下的檔案重寫
                   //--全域性小寫
                   if (file_exists($path.'config/'.strtolower($class).'.php'))
                   {
                       include($path.'config/'.strtolower($class).'.php');
                       $found = TRUE;
                   }
                   //--全域性首字母大寫
                   elseif (file_exists($path.'config/'.ucfirst(strtolower($class)).'.php'))
                   {
                       include($path.'config/'.ucfirst(strtolower($class)).'.php');
                       $found = TRUE;
                   }
                    //--環境下檔案覆蓋（小寫）
                   if (file_exists($path.'config/'.ENVIRONMENT.'/'.strtolower($class).'.php'))
                   {
                       include($path.'config/'.ENVIRONMENT.'/'.strtolower($class).'.php');
                       $found = TRUE;
                   }
                   ////--環境下檔案覆蓋（小寫）
                   elseif (file_exists($path.'config/'.ENVIRONMENT.'/'.ucfirst(strtolower($class)).'.php'))
                   {
                       include($path.'config/'.ENVIRONMENT.'/'.ucfirst(strtolower($class)).'.php');
                       $found = TRUE;
                   }

                   // Break on the first found configuration, thus package
                   // files are not overridden by default paths
                   if ($found === TRUE)
                   {
                       break;
                   }
               }
           }
       }

       $class_name = $prefix.$class;

       // Is the class name valid?
       //判斷$class檔案是否被include
       if ( ! class_exists($class_name, FALSE))
       {
           log_message('error', 'Non-existent class: '.$class_name);
           show_error('Non-existent class: '.$class_name);
       }

       // Set the variable name we will assign the class to
       // Was a custom class name supplied? If so we'll use it
       //是否是自定義類名提供？如果是，我們就使用他
       if (empty($object_name))
       {
           $object_name = strtolower($class);
           if (isset($this->_ci_varmap[$object_name]))
           {
               $object_name = $this->_ci_varmap[$object_name];
           }
       }

       // Don't overwrite existing properties
       //禁止重寫已經存在的屬性
       $CI =& get_instance();
       if (isset($CI->$object_name))
       {
           //如果$CI->$object_name是$class_name的例項，則提示已經初始化
           if ($CI->$object_name instanceof $class_name)
           {
               log_message('debug', $class_name." has already been instantiated as '".$object_name."'. Second attempt aborted.");
               return;
           }

           show_error("Resource '".$object_name."' already exists and is not a ".$class_name." instance.");
       }

       // Save the class name and object name
       //記錄即將要初始化的物件
       $this->_ci_classes[$object_name] = $class;

       // Instantiate the class
       //例項化類
       $CI->$object_name = isset($config)
           ? new $class_name($config)
           : new $class_name();
   }

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

   /**
   *CI Autoload，顧名思義是自動載入
   * CI Autoloader
   *載入元件從config/autoload.php file 列表中
   * Loads component listed in the config/autoload.php file.
   *
   * @used-by   CI_Loader::initialize()
   *無返回值
   * @return   void
   */
   protected function _ci_autoloader()
   {
       if (file_exists(APPPATH.'config/autoload.php'))
       {
           include(APPPATH.'config/autoload.php');
       }

       if (file_exists(APPPATH.'config/'.ENVIRONMENT.'/autoload.php'))
       {
           include(APPPATH.'config/'.ENVIRONMENT.'/autoload.php');
       }
        //如果配置檔案中不存在$autoload陣列，就返回
       if ( ! isset($autoload))
       {
           return;
       }

       // Autoload packages
       //載入包，格式在APPPATH的config目錄中定義，格式如下：
       //$autoload['packages'] = array(APPPATH.'third_party', '/usr/local/shared');
       if (isset($autoload['packages']))
       {
           foreach ($autoload['packages'] as $package_path)
           {
               $this->add_package_path($package_path);
           }
       }

       // Load any custom config file
       //load自定義的配置檔案，樣式：$autoload['config'] = array('config1', 'config2');
       if (count($autoload['config']) > 0)
       {
           foreach ($autoload['config'] as $val)
           {
               //載入配置檔案的函式，間接呼叫Config::load()函式
               $this->config($val);
           }
       }

       // Autoload helpers and languages
       foreach (array('helper', 'language') as $type)
       {
           //$autoload['helper'] = array('url', 'file');配置檔案中樣式
           //資料的個數大於0，則load
           if (isset($autoload[$type]) && count($autoload[$type]) > 0)
           {
               //載入helper工具以及language模組,參見helper與language()函式
               $this->$type($autoload[$type]);
           }
       }

       // Autoload drivers
       //載入驅動odbc等等，
       if (isset($autoload['drivers']))
       {
           foreach ($autoload['drivers'] as $item)
           {
               //driver函式，load dirvers ,擴充套件自CI_Driver_Library類（they extend the CI_Driver_Library class）
               //最後呼叫_ci_init_libraries函式初始化例項
               $this->driver($item);
           }
       }

       // Load libraries
       //load libraries庫，通常這些在system/libraries or application/libraries
       if (isset($autoload['libraries']) && count($autoload['libraries']) > 0)
       {
           // Load the database driver.
           //如果database配置項在$autoload['libraries']
           if (in_array('database', $autoload['libraries']))
           {
               //load database driver具體動作，參考database()函式，返回一個db例項
               $this->database();
               //值取差集，即在$autoload['libraries']去掉database鍵的值
               $autoload['libraries'] = array_diff($autoload['libraries'], array('database'));
           }

           // Load all other libraries
           //參考library()函式
           $this->library($autoload['libraries']);
       }

       // Autoload models
       //自動載入models
       if (isset($autoload['model']))
       {
           $this->model($autoload['model']);
       }
   }

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

   /**
   * CI Object to Array translator
   *
   * Takes an object as input and converts the class variables to
   * an associative array with key/value pairs.
   *將物件轉化為鍵值對陣列
   * @param   object   $object   Object data to translate
   * @return   array
   */
   protected function _ci_object_to_array($object)
   {
       return is_object($object) ? get_object_vars($object) : $object;
   }

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

   /**
   * CI Component getter
   *
   *獲得引用從指定的library或者是model
   * Get a reference to a specific library or model.
   *
   *這個元件是類的例項
   *例如：$component為'config'，則返回$CI->config即，CI_Config例項的類
   * @param    string   $component   Component name
   * @return   bool
   */
   protected function &_ci_get_component($component)
   {
       $CI =& get_instance();
       //返回引用的例項
       return $CI->$component;
   }

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

   /**
   * Prep filename
   *
   *從filenames中獲取不同items，使load時候更加可靠
   * This function prepares filenames of various items to
   * make their loading more reliable.
   *
   * @param   string|string[]   $filename   Filename(s)
   * @param    string       $extension   Filename extension
   * @return   array
   */
   protected function _ci_prep_filename($filename, $extension)
   {
        //如果$filename非array
       if ( ! is_array($filename))
       {
           //將filename中帶有$extension以及.php去掉，然後在帶上$extension(其實是返回一個php檔案)
           return array(strtolower(str_replace(array($extension, '.php'), '', $filename).$extension));
       }
       else
       {
           foreach ($filename as $key => $val)
           {
               $filename[$key] = strtolower(str_replace(array($extension, '.php'), '', $val).$extension);
           }

           return $filename;
       }
   }

}

【PHP】CI框架原始碼分析核心檔案之Loader.php

相關文章