php优秀框架codeigniter学习系列——common.php

　　文件位于system/core/common.php，是框架核心文件。

　　该文件中定义了一系列的函数，都是框架运行中经常需要用到的。下面逐一介绍。

is_php

    /**
     * Determines if the current version of PHP is equal to or greater than the supplied value
     *
     * @param    string
     * @return    bool    TRUE if the current version is $version or higher
     */
    function is_php($version)
    {
        static $_is_php;
        $version = (string) $version;

        if ( ! isset($_is_php[$version]))
        {
            $_is_php[$version] = version_compare(PHP_VERSION, $version, '>=');
        }

        return $_is_php[$version];
    }
}

　　该函数用于进行php版本比较，如果运行的php版本大于等于输入的php版本参数，则返回true。这里建立了一个$is_php静态数组，把新版本参数比较的结果存在数组里，如果再有类似的版本参数传入，不用比较，直接返回结果。是一种空间换时间的做法。

is_really_writable

    /**
     * Tests for file writability
     *
     * is_writable() returns TRUE on Windows servers when you really can't write to
     * the file, based on the read-only attribute. is_writable() is also unreliable
     * on Unix servers if safe_mode is on.
     *
     * @link    https://bugs.php.net/bug.php?id=54709
     * @param    string
     * @return    bool
     */
    function is_really_writable($file)
    {
        // If we're on a Unix server with safe_mode off we call is_writable
                //用DIRECTORY_SEPARATOR === '/'来判断是unix系统，
        if (DIRECTORY_SEPARATOR === '/' && (is_php('5.4') OR ! ini_get('safe_mode')))
        {
            return is_writable($file);
        }

        /* For Windows servers and safe_mode "on" installations we'll actually
         * write a file then read it. Bah...
                 * 对于windows操作系统和安全模式的处理方法
         */
        if (is_dir($file))//对于目录
        {
            $file = rtrim($file, '/').'/'.md5(mt_rand());
            if (($fp = @fopen($file, 'ab')) === FALSE)
            {
                return FALSE;
            }

            fclose($fp);
            @chmod($file, 0777);
            @unlink($file);
            return TRUE;
        }
        elseif ( ! is_file($file) OR ($fp = @fopen($file, 'ab')) === FALSE)//对于文件
        {
            return FALSE;
        }

        fclose($fp);
        return TRUE;
    }

　　该函数用于判断文件或目录是否可写。

　　对于linux系统未使用安全模式的情况，直接调用php函数is_writable($file)即可。

　　对于windows系统和使用安全模式的linux系统则根据是文件夹还是文件采取不同的方式：文件夹是 在看是否可在里面新建一个可读写的文件；文件是看是否可读写打开。　　

&load_class

    /**
     * Class registry
     *
     * This function acts as a singleton. If the requested class does not
     * exist it is instantiated and set to a static variable. If it has
     * previously been instantiated the variable is returned.
     *
     * @param    string    the class name being requested
     * @param    string    the directory where the class should be found
     * @param    mixed    an optional argument to pass to the class constructor
     * @return    object
     */
    function &load_class($class, $directory = 'libraries', $param = NULL)
    {
        static $_classes = array();

        // Does the class exist? If so, we're done...
        if (isset($_classes[$class]))
        {
            return $_classes[$class];
        }

        $name = FALSE;

        // Look for the class first in the local application/libraries folder
        // then in the native system/libraries folder
        foreach (array(APPPATH, BASEPATH) as $path)
        {
            if (file_exists($path.$directory.'/'.$class.'.php'))
            {
                $name = 'CI_'.$class;

                if (class_exists($name, FALSE) === FALSE)
                {
                    require_once($path.$directory.'/'.$class.'.php');
                }

                break;
            }
        }

        // Is the request a class extension? If so we load it too
        if (file_exists(APPPATH.$directory.'/'.config_item('subclass_prefix').$class.'.php'))
        {
            $name = config_item('subclass_prefix').$class;

            if (class_exists($name, FALSE) === FALSE)
            {
                require_once(APPPATH.$directory.'/'.$name.'.php');
            }
        }

        // Did we find the class?
        if ($name === FALSE)
        {
            // Note: We use exit() rather than show_error() in order to avoid a
            // self-referencing loop with the Exceptions class
            set_status_header(503);
            echo 'Unable to locate the specified class: '.$class.'.php';
            exit(5); // EXIT_UNK_CLASS
        }

        // Keep track of what we just loaded
        is_loaded($class);

        $_classes[$class] = isset($param)
            ? new $name($param)
            : new $name();
        return $_classes[$class];
    }
}

　　该函数用于类的注册，核心函数。

　　这个函数维护一个单例模式，即如果请求注册的类$class已经被实例化过了，则把保存的实例化对象返回，如果没有实例化过，就实例化该类。这个做法避免新建大量的对象，减少内存消耗，也减少了框架使用对象的维护成本，避免使用的混乱。

　　在搜索类文件的时候，既会搜索系统的类文件，也会搜索用户自定义的类文件。用户自定义类名需要定义统一的前缀，这个前缀在application/config/config.php文件的subclass_prefix变量中定义。

　　该函数前面有一个&，表明是引用传递返回值。即返回的对象以后发生变化的时候，在这个函数中定义的$_classes[$class]也会发生变化。参考知乎上的解释。

&is_loaded($class = '')

    /**
     * Keeps track of which libraries have been loaded. This function is
     * called by the load_class() function above
     *
     * @param    string
     * @return    array
     */
    function &is_loaded($class = '')
    {
        static $_is_loaded = array();

        if ($class !== '')
        {
            $_is_loaded[strtolower($class)] = $class;
        }
        return $_is_loaded;
    }

　　该函数可以获取已经在load_class函数中注册的类名数组，也可以往 类名数组中添加一个已经注册的类名。使用引用传递返回值。

&get_config(Array $replace = array())

 1     /**
 2      * Loads the main config.php file
 3      *
 4      * This function lets us grab the config file even if the Config class
 5      * hasn't been instantiated yet
 6      *
 7      * @param    array
 8      * @return    array
 9      */
10     function &get_config(Array $replace = array())
11     {
12         static $config;
13 
14         if (empty($config))
15         {
16             $file_path = APPPATH.'config/config.php';
17             $found = FALSE;
18             if (file_exists($file_path))
19             {
20                 $found = TRUE;
21                 require($file_path);
22             }
23 
24             // Is the config file in the environment folder?
25             if (file_exists($file_path = APPPATH.'config/'.ENVIRONMENT.'/config.php'))
26             {
27                 require($file_path);
28             }
29             elseif ( ! $found)
30             {
31                 set_status_header(503);
32                 echo 'The configuration file does not exist.';
33                 exit(3); // EXIT_CONFIG
34             }
35 
36             // Does the $config array exist in the file?
37             if ( ! isset($config) OR ! is_array($config))
38             {
39                 set_status_header(503);
40                 echo 'Your config file does not appear to be formatted correctly.';
41                 exit(3); // EXIT_CONFIG
42             }
43         }
44 
45         // Are any values being dynamically added or replaced?
46         foreach ($replace as $key => $val)
47         {
48             $config[$key] = $val;
49         }
50 
51         return $config;
52     }
53 }

　　该函数用来加载application/config/config.php中的$config数组变量。当然，如果存在，也加载用户根据环境定义的config.php文件。

　　config.php文件中定义了一些系统和应用程序的设置，包括使用何种编码，是否采用csrf,自定义的类的类名前缀等等。

       同时，使用该函数通过$replace也可以追加一些设置。

　　该函数使用静态局部变量数组$config来存储。使用引用传递返回值。

config_item($item)

    /**
     * Returns the specified config item
     *
     * @param    string
     * @return    mixed
     */
    function config_item($item)
    {
        static $_config;

        if (empty($_config))
        {
            // references cannot be directly assigned to static variables, so we use an array
            $_config[0] =& get_config();
        }

        return isset($_config[0][$item]) ? $_config[0][$item] : NULL;
    }

　　该函数用于获取某一个具体的在get_config()中定义的$config数组的值。

&get_mimes()

    /**
     * Returns the MIME types array from config/mimes.php
     *
     * @return    array
     */
    function &get_mimes()
    {
        static $_mimes;

        if (empty($_mimes))
        {
            $_mimes = file_exists(APPPATH.'config/mimes.php')
                ? include(APPPATH.'config/mimes.php')
                : array();

            if (file_exists(APPPATH.'config/'.ENVIRONMENT.'/mimes.php'))
            {
                $_mimes = array_merge($_mimes, include(APPPATH.'config/'.ENVIRONMENT.'/mimes.php'));
            }
        }

        return $_mimes;
    }

　　该函数用于获取在application/config/mimes.php中定义的mime类型数组。主要用于文件上传时候的检测。

is_https()

    /**
     * Is HTTPS?
     *
     * Determines if the application is accessed via an encrypted
     * (HTTPS) connection.
     *
     * @return    bool
     */
    function is_https()
    {
        if ( ! empty($_SERVER['HTTPS']) && strtolower($_SERVER['HTTPS']) !== 'off')
        {
            return TRUE;
        }
        elseif (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && strtolower($_SERVER['HTTP_X_FORWARDED_PROTO']) === 'https')
        {
            return TRUE;
        }
        elseif ( ! empty($_SERVER['HTTP_FRONT_END_HTTPS']) && strtolower($_SERVER['HTTP_FRONT_END_HTTPS']) !== 'off')
        {
            return TRUE;
        }

        return FALSE;
    }

　　该函数判断请求是否是http请求。

is_cli()

    /**
     * Is CLI?
     *
     * Test to see if a request was made from the command line.
     *
     * @return     bool
     */
    function is_cli()
    {
        return (PHP_SAPI === 'cli' OR defined('STDIN'));
    }

　　该函数用于判断请求是否是命令行方式。

show_error($message, $status_code = 500, $heading = 'An Error Was Encountered')

    /**
     * Error Handler
     *
     * This function lets us invoke the exception class and
     * display errors using the standard error template located
     * in application/views/errors/error_general.php
     * This function will send the error page directly to the
     * browser and exit.
     *
     * @param    string
     * @param    int
     * @param    string
     * @return    void
     */
    function show_error($message, $status_code = 500, $heading = 'An Error Was Encountered')
    {
        $status_code = abs($status_code);//取绝对值
        if ($status_code < 100)
        {
            $exit_status = $status_code + 9; // 9 is EXIT__AUTO_MIN
            $status_code = 500;
        }
        else
        {
            $exit_status = 1; // EXIT_ERROR
        }

        $_error =& load_class('Exceptions', 'core');
        echo $_error->show_error($heading, $message, 'error_general', $status_code);
        exit($exit_status);
    }

　　该函数用于主动显示一个错误提示给用户，无论是命令行模式还是浏览器显示。调用的是Exceptions类的show_error方法。

show_404($page = '', $log_error = TRUE)

    /**
     * 404 Page Handler
     *
     * This function is similar to the show_error() function above
     * However, instead of the standard error template it displays
     * 404 errors.
     *
     * @param    string
     * @param    bool
     * @return    void
     */
    function show_404($page = '', $log_error = TRUE)
    {
        $_error =& load_class('Exceptions', 'core');
        $_error->show_404($page, $log_error);
        exit(4); // EXIT_UNKNOWN_FILE
    }

　　该函数用于主动显示一个404错误给用户，无论是命令行模式还是浏览器显示。调用的是Exceptions类的show_404方法。

log_message($level, $message)

    /**
     * Error Logging Interface
     *
     * We use this as a simple mechanism to access the logging
     * class and send messages to be logged.
     *
     * @param    string    the error level: 'error', 'debug' or 'info'
     * @param    string    the error message
     * @return    void
     */
    function log_message($level, $message)
    {
        static $_log;

        if ($_log === NULL)
        {
            // references cannot be directly assigned to static variables, so we use an array
            $_log[0] =& load_class('Log', 'core');
        }

        $_log[0]->write_log($level, $message);
    }

　　该函数用于记录日志。常用的函数。日志分Error，Debug，Info三个级别。调用的是Log类的write_log方法。

set_status_header($code = 200, $text = '')

    /**
     * Set HTTP Status Header
     *
     * @param    int    the status code
     * @param    string
     * @return    void
     */
    function set_status_header($code = 200, $text = '')
    {
        if (is_cli())
        {
            return;
        }

        if (empty($code) OR ! is_numeric($code))
        {
            show_error('Status codes must be numeric', 500);
        }

        if (empty($text))
        {
            is_int($code) OR $code = (int) $code;
            $stati = array(
                100    => 'Continue',
                101    => 'Switching Protocols',

                200    => 'OK',
                201    => 'Created',
                202    => 'Accepted',
                203    => 'Non-Authoritative Information',
                204    => 'No Content',
                205    => 'Reset Content',
                206    => 'Partial Content',

                300    => 'Multiple Choices',
                301    => 'Moved Permanently',
                302    => 'Found',
                303    => 'See Other',
                304    => 'Not Modified',
                305    => 'Use Proxy',
                307    => 'Temporary Redirect',

                400    => 'Bad Request',
                401    => 'Unauthorized',
                402    => 'Payment Required',
                403    => 'Forbidden',
                404    => 'Not Found',
                405    => 'Method Not Allowed',
                406    => 'Not Acceptable',
                407    => 'Proxy Authentication Required',
                408    => 'Request Timeout',
                409    => 'Conflict',
                410    => 'Gone',
                411    => 'Length Required',
                412    => 'Precondition Failed',
                413    => 'Request Entity Too Large',
                414    => 'Request-URI Too Long',
                415    => 'Unsupported Media Type',
                416    => 'Requested Range Not Satisfiable',
                417    => 'Expectation Failed',
                422    => 'Unprocessable Entity',
                426    => 'Upgrade Required',
                428    => 'Precondition Required',
                429    => 'Too Many Requests',
                431    => 'Request Header Fields Too Large',

                500    => 'Internal Server Error',
                501    => 'Not Implemented',
                502    => 'Bad Gateway',
                503    => 'Service Unavailable',
                504    => 'Gateway Timeout',
                505    => 'HTTP Version Not Supported',
                511    => 'Network Authentication Required',
            );

            if (isset($stati[$code]))
            {
                $text = $stati[$code];
            }
            else
            {
                show_error('No status text available. Please check your status code number or supply your own message text.', 500);
            }
        }

        if (strpos(PHP_SAPI, 'cgi') === 0)
        {
            header('Status: '.$code.' '.$text, TRUE);
            return;
        }

        $server_protocol = (isset($_SERVER['SERVER_PROTOCOL']) && in_array($_SERVER['SERVER_PROTOCOL'], array('HTTP/1.0', 'HTTP/1.1', 'HTTP/2'), TRUE))
            ? $_SERVER['SERVER_PROTOCOL'] : 'HTTP/1.1';
        header($server_protocol.' '.$code.' '.$text, TRUE, $code);
    }

　　手动设置返回的http头，如果设置的是“500”。那么浏览器解析的Status Code就是500。

 _error_handler($severity, $message, $filepath, $line)

    /**
     * Error Handler
     *
     * This is the custom error handler that is declared at the (relative)
     * top of CodeIgniter.php. The main reason we use this is to permit
     * PHP errors to be logged in our own log files since the user may
     * not have access to server logs. Since this function effectively
     * intercepts PHP errors, however, we also need to display errors
     * based on the current error_reporting level.
     * We do that with the use of a PHP error template.
     *
     * @param    int    $severity
     * @param    string    $message
     * @param    string    $filepath
     * @param    int    $line
     * @return    void
     */
    function _error_handler($severity, $message, $filepath, $line)
    {
        $is_error = (((E_ERROR | E_PARSE | E_COMPILE_ERROR | E_CORE_ERROR | E_USER_ERROR) & $severity) === $severity);

        // When an error occurred, set the status header to '500 Internal Server Error'
        // to indicate to the client something went wrong.
        // This can't be done within the $_error->show_php_error method because
        // it is only called when the display_errors flag is set (which isn't usually
        // the case in a production environment) or when errors are ignored because
        // they are above the error_reporting threshold.
        if ($is_error)
        {
            set_status_header(500);
        }

        // Should we ignore the error? We'll get the current error_reporting
        // level and add its bits with the severity bits to find out.
        if (($severity & error_reporting()) !== $severity)
        {
            return;
        }

        $_error =& load_class('Exceptions', 'core');
        $_error->log_exception($severity, $message, $filepath, $line);

        // Should we display the error?
        if (str_ireplace(array('off', 'none', 'no', 'false', 'null'), '', ini_get('display_errors')))
        {
            $_error->show_php_error($severity, $message, $filepath, $line);
        }

        // If the error is fatal, the execution of the script should be stopped because
        // errors can't be recovered from. Halting the script conforms with PHP's
        // default error handling. See http://www.php.net/manual/en/errorfunc.constants.php
        if ($is_error)
        {
            exit(1); // EXIT_ERROR
        }
    }

　　该函数是在CodeIgniter.php中使用set_error_handler设置的用户自定义错误处理函数。该函数用于处理脚本中出现的错误。值得说明的是，以下级别的错误不能由用户定义的函数来处理： E_ERROR、 E_PARSE、 E_CORE_ERROR、 E_CORE_WARNING、 E_COMPILE_ERROR、 E_COMPILE_WARNING。所以即使不小心进入了这个方法，也需要屏蔽掉。

　　对于在函数前加了@屏蔽warning的函数，也会进入这个方法。但是它的error_reporting()返回值是0，而不管系统设置的是什么。可以由此来判断直接返回，不做处理。

　　$severity包含了错误的级别，是一个 integer。

　　调用Exceptions类的show_php_error方法。

_exception_handler($exception)

    /**
     * Exception Handler
     *
     * Sends uncaught exceptions to the logger and displays them
     * only if display_errors is On so that they don't show up in
     * production environments.
     *
     * @param    Exception    $exception
     * @return    void
     */
    function _exception_handler($exception)
    {
        $_error =& load_class('Exceptions', 'core');
        $_error->log_exception('error', 'Exception: '.$exception->getMessage(), $exception->getFile(), $exception->getLine());

        is_cli() OR set_status_header(500);
        // Should we display the error?
        if (str_ireplace(array('off', 'none', 'no', 'false', 'null'), '', ini_get('display_errors')))
        {
            $_error->show_exception($exception);
        }

        exit(1); // EXIT_ERROR
    }

　　该函数是在CodeIgniter.php中使用set_exception_handler设置的用户自定义异常处理函数。该函数是记录异常到日志中，并且展示给用户看到该异常。

　　set_error_handler和set_exception_handler的不同参见网上资料。

_shutdown_handler()

    /**
     * Shutdown Handler
     *
     * This is the shutdown handler that is declared at the top
     * of CodeIgniter.php. The main reason we use this is to simulate
     * a complete custom exception handler.
     *
     * E_STRICT is purposively neglected because such events may have
     * been caught. Duplication or none? None is preferred for now.
     *
     * @link    http://insomanic.me.uk/post/229851073/php-trick-catching-fatal-errors-e-error-with-a
     * @return    void
     */
    function _shutdown_handler()
    {
        $last_error = error_get_last();
        if (isset($last_error) &&
            ($last_error['type'] & (E_ERROR | E_PARSE | E_CORE_ERROR | E_CORE_WARNING | E_COMPILE_ERROR | E_COMPILE_WARNING)))
        {
            _error_handler($last_error['type'], $last_error['message'], $last_error['file'], $last_error['line']);
        }
    }

　　该函数是在CodeIgniter.php中使用register_shutdown_function 注册的会在php中止时执行的函数。

remove_invisible_characters($str, $url_encoded = TRUE)　　

    /**
     * Remove Invisible Characters
     *
     * This prevents sandwiching null characters
     * between ascii characters, like Javascript.
     *
     * @param    string
     * @param    bool
     * @return    string
     */
    function remove_invisible_characters($str, $url_encoded = TRUE)
    {
        $non_displayables = array();

        // every control character except newline (dec 10),
        // carriage return (dec 13) and horizontal tab (dec 09)
        if ($url_encoded)
        {
            $non_displayables[] = '/%0[0-8bcef]/i';    // url encoded 00-08, 11, 12, 14, 15
            $non_displayables[] = '/%1[0-9a-f]/i';    // url encoded 16-31
            $non_displayables[] = '/%7f/i';    // url encoded 127
        }

        $non_displayables[] = '/[x00-x08x0Bx0Cx0E-x1Fx7F]+/S';    // 00-08, 11, 12, 14-31, 127

        do
        {
            $str = preg_replace($non_displayables, '', $str, -1, $count);
        }
        while ($count);

        return $str;
    }

　　该函数用于清除字符串中的不可见字符。 $non_displayables[] = '/[x00-x08x0Bx0Cx0E-x1Fx7F]+/S';  会匹配ascII中00-08, 11, 12, 14-31, 127的字符，这些字符都是不可见的。参见ascII字符表。

html_escape($var, $double_encode = TRUE)

    /**
     * Returns HTML escaped variable.
     *
     * @param    mixed    $var        The input string or array of strings to be escaped.
     * @param    bool    $double_encode    $double_encode set to FALSE prevents escaping twice.
     * @return    mixed            The escaped string or array of strings as a result.
     */
    function html_escape($var, $double_encode = TRUE)
    {
        if (empty($var))
        {
            return $var;
        }

        if (is_array($var))
        {
            foreach (array_keys($var) as $key)
            {
                $var[$key] = html_escape($var[$key], $double_encode);
            }

            return $var;
        }

        return htmlspecialchars($var, ENT_QUOTES, config_item('charset'), $double_encode);
    }

　　该函数用于将字符串或者字符串数组转换为html实体。

_stringify_attributes($attributes, $js = FALSE)

 1     /**
 2      * Stringify attributes for use in HTML tags.
 3      *
 4      * Helper function used to convert a string, array, or object
 5      * of attributes to a string.
 6      *
 7      * @param    mixed    string, array, object
 8      * @param    bool
 9      * @return    string
10      */
11     function _stringify_attributes($attributes, $js = FALSE)
12     {
13         $atts = NULL;
14 
15         if (empty($attributes))
16         {
17             return $atts;
18         }
19 
20         if (is_string($attributes))
21         {
22             return ' '.$attributes;
23         }
24 
25         $attributes = (array) $attributes;
26 
27         foreach ($attributes as $key => $val)
28         {
29             $atts .= ($js) ? $key.'='.$val.',' : ' '.$key.'="'.$val.'"';
30         }
31 
32         return rtrim($atts, ',');
33     }

　　将一个字符串属性，数组属性或者对象属性转换为一个字符串。主要用于在显示html页面的时候使用。

function_usable($function_name)

    /**
     * Function usable
     *
     * Executes a function_exists() check, and if the Suhosin PHP
     * extension is loaded - checks whether the function that is
     * checked might be disabled in there as well.
     *
     * This is useful as function_exists() will return FALSE for
     * functions disabled via the *disable_functions* php.ini
     * setting, but not for *suhosin.executor.func.blacklist* and
     * *suhosin.executor.disable_eval*. These settings will just
     * terminate script execution if a disabled function is executed.
     *
     * The above described behavior turned out to be a bug in Suhosin,
     * but even though a fix was committed for 0.9.34 on 2012-02-12,
     * that version is yet to be released. This function will therefore
     * be just temporary, but would probably be kept for a few years.
     *
     * @link    http://www.hardened-php.net/suhosin/
     * @param    string    $function_name    Function to check for
     * @return    bool    TRUE if the function exists and is safe to call,
     *            FALSE otherwise.
     */
    function function_usable($function_name)
    {
        static $_suhosin_func_blacklist;

        if (function_exists($function_name))
        {
            if ( ! isset($_suhosin_func_blacklist))
            {
                $_suhosin_func_blacklist = extension_loaded('suhosin')
                    ? explode(',', trim(ini_get('suhosin.executor.func.blacklist')))
                    : array();
            }

            return ! in_array($function_name, $_suhosin_func_blacklist, TRUE);
        }

        return FALSE;
    }

　　函数功能类似于function_exist(),不过在外面包装了一层，还需要检查下函数是否在suhosin.executor.func.blacklist中（类似于黑名单？），如果在还是会返回false。