diff options
Diffstat (limited to 'user_guide_src/source/general')
-rw-r--r-- | user_guide_src/source/general/ancillary_classes.rst | 4 | ||||
-rw-r--r-- | user_guide_src/source/general/caching.rst | 3 | ||||
-rw-r--r-- | user_guide_src/source/general/cli.rst | 2 | ||||
-rw-r--r-- | user_guide_src/source/general/common_functions.rst | 227 | ||||
-rw-r--r-- | user_guide_src/source/general/controllers.rst | 2 | ||||
-rw-r--r-- | user_guide_src/source/general/creating_libraries.rst | 3 | ||||
-rw-r--r-- | user_guide_src/source/general/errors.rst | 27 | ||||
-rw-r--r-- | user_guide_src/source/general/hooks.rst | 2 | ||||
-rw-r--r-- | user_guide_src/source/general/profiling.rst | 6 | ||||
-rw-r--r-- | user_guide_src/source/general/requirements.rst | 23 | ||||
-rw-r--r-- | user_guide_src/source/general/reserved_names.rst | 29 | ||||
-rw-r--r-- | user_guide_src/source/general/routing.rst | 23 | ||||
-rw-r--r-- | user_guide_src/source/general/styleguide.rst | 2 |
13 files changed, 187 insertions, 166 deletions
diff --git a/user_guide_src/source/general/ancillary_classes.rst b/user_guide_src/source/general/ancillary_classes.rst index 5dc058ad4..edb3a14fb 100644 --- a/user_guide_src/source/general/ancillary_classes.rst +++ b/user_guide_src/source/general/ancillary_classes.rst @@ -9,7 +9,7 @@ resources. This is easily possible as you'll see. get_instance() ============== -.. php:function:: get_instance() +.. function:: get_instance() :returns: object of class CI_Controller @@ -48,7 +48,7 @@ Once you've assigned the object to a variable, you'll use that variable passed by reference:: $CI =& get_instance(); - + This is very important. Assigning by reference allows you to use the original CodeIgniter object rather than creating a copy of it. diff --git a/user_guide_src/source/general/caching.rst b/user_guide_src/source/general/caching.rst index 48385d6c9..f499f6e93 100644 --- a/user_guide_src/source/general/caching.rst +++ b/user_guide_src/source/general/caching.rst @@ -45,6 +45,9 @@ you. Once the tag is in place, your pages will begin being cached. caching will only work if you are generating display for your controller with a :doc:`view <./views>`. +.. important:: If you change configuration options that might affect + your output, you have to manually delete your cache files. + .. note:: Before the cache files can be written you must set the file permissions on your *application/cache/* directory such that it is writable. diff --git a/user_guide_src/source/general/cli.rst b/user_guide_src/source/general/cli.rst index 4145d5ccc..4f3b07d9e 100644 --- a/user_guide_src/source/general/cli.rst +++ b/user_guide_src/source/general/cli.rst @@ -23,7 +23,7 @@ but they are not always obvious. - Run your cron-jobs without needing to use *wget* or *curl* - Make your cron-jobs inaccessible from being loaded in the URL by - checking for ``$this->input->is_cli_request()`` + checking the return value of :func:`is_cli()`. - Make interactive "tasks" that can do things like set permissions, prune cache folders, run backups, etc. - Integrate with other applications in other languages. For example, a diff --git a/user_guide_src/source/general/common_functions.rst b/user_guide_src/source/general/common_functions.rst index 32e8a8be0..2ca7478ec 100644 --- a/user_guide_src/source/general/common_functions.rst +++ b/user_guide_src/source/general/common_functions.rst @@ -6,188 +6,183 @@ CodeIgniter uses a few functions for its operation that are globally defined, and are available to you at any point. These do not require loading any libraries or helpers. -is_php() -======== +.. contents:: + :local: -.. php:function:: is_php($version = '5.3.0') +.. raw:: html - :param string $version: Version number - :returns: bool + <div class="custom-index container"></div> + +.. function:: is_php([$version = '5.3.0']) -Determines of the PHP version being used is greater than the -supplied version number. + :param string $version: Version number + :returns: TRUE if the running PHP version is at least the one specified or FALSE if not + :rtype: bool -Example:: + Determines of the PHP version being used is greater than the + supplied version number. - if (is_php('5.3')) - { - $str = quoted_printable_encode($str); - } + Example:: -Returns boolean TRUE if the installed version of PHP is equal to or -greater than the supplied version number. Returns FALSE if the installed -version of PHP is lower than the supplied version number. + if (is_php('5.3')) + { + $str = quoted_printable_encode($str); + } -is_really_writable() -==================== + Returns boolean TRUE if the installed version of PHP is equal to or + greater than the supplied version number. Returns FALSE if the installed + version of PHP is lower than the supplied version number. -.. php:function:: is_really_writable($file) +.. function:: is_really_writable($file) :param string $file: File path - :returns: bool + :returns: TRUE if the path is writable, FALSE if not + :rtype: bool -``is_writable()`` returns TRUE on Windows servers when you really can't -write to the file as the OS reports to PHP as FALSE only if the -read-only attribute is marked. + ``is_writable()`` returns TRUE on Windows servers when you really can't + write to the file as the OS reports to PHP as FALSE only if the + read-only attribute is marked. -This function determines if a file is actually writable by attempting -to write to it first. Generally only recommended on platforms where -this information may be unreliable. + This function determines if a file is actually writable by attempting + to write to it first. Generally only recommended on platforms where + this information may be unreliable. -Example:: + Example:: - if (is_really_writable('file.txt')) - { - echo "I could write to this if I wanted to"; - } - else - { - echo "File is not writable"; - } + if (is_really_writable('file.txt')) + { + echo "I could write to this if I wanted to"; + } + else + { + echo "File is not writable"; + } -config_item() -============= + .. note:: See also `PHP bug #54709 <https://bugs.php.net/bug.php?id=54709>`_ for more info. -.. php:function:: config_item($key) +.. function:: config_item($key) :param string $key: Config item key - :returns: mixed + :returns: Configuration key value or FALSE if not found + :rtype: mixed -The :doc:`Config Library <../libraries/config>` is the preferred way of -accessing configuration information, however ``config_item()`` can be used -to retrieve single keys. See :doc:`Config Library <../libraries/config>` -documentation for more information. + The :doc:`Config Library <../libraries/config>` is the preferred way of + accessing configuration information, however ``config_item()`` can be used + to retrieve single keys. See :doc:`Config Library <../libraries/config>` + documentation for more information. -show_error() -============ - -.. php:function:: show_error($message, $status_code, $heading = 'An Error Was Encountered') +.. :noindex: function:: show_error($message, $status_code[, $heading = 'An Error Was Encountered']) :param mixed $message: Error message :param int $status_code: HTTP Response status code :param string $heading: Error page heading - :returns: void - -This function calls ``CI_Exception::show_error()``. For more info, -please see the :doc:`Error Handling <errors>` documentation. + :rtype: void -show_404() -========== + This function calls ``CI_Exception::show_error()``. For more info, + please see the :doc:`Error Handling <errors>` documentation. -.. php:function:: show_404($page = '', $log_error = TRUE) +.. :noindex: function:: show_404([$page = ''[, $log_error = TRUE]]) :param string $page: URI string :param bool $log_error: Whether to log the error - :returns: void + :rtype: void -This function calls ``CI_Exception::show_404()``. For more info, -please see the :doc:`Error Handling <errors>` documentation. + This function calls ``CI_Exception::show_404()``. For more info, + please see the :doc:`Error Handling <errors>` documentation. -log_message() -============= - -.. php:function:: log_message($level, $message, $php_error = FALSE) +.. :noindex: function:: log_message($level, $message) :param string $level: Log level: 'error', 'debug' or 'info' :param string $message: Message to log - :param bool $php_error: Whether we're logging a native PHP error message - :returns: void - -This function is an alias for ``CI_Log::write_log()``. For more info, -please see the :doc:`Error Handling <errors>` documentation. + :rtype: void -set_status_header() -=============================== + This function is an alias for ``CI_Log::write_log()``. For more info, + please see the :doc:`Error Handling <errors>` documentation. -.. php:function:: set_status_header($code, $text = '') +.. function:: set_status_header($code[, $text = '']) :param int $code: HTTP Reponse status code :param string $text: A custom message to set with the status code - :returns: void + :rtype: void -Permits you to manually set a server status header. Example:: + Permits you to manually set a server status header. Example:: - set_status_header(401); - // Sets the header as: Unauthorized + set_status_header(401); + // Sets the header as: Unauthorized -`See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for -a full list of headers. + `See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for + a full list of headers. -remove_invisible_characters() -============================= - -.. php:function:: remove_invisible_characters($str, $url_encoded = TRUE) +.. function:: remove_invisible_characters($str[, $url_encoded = TRUE]) :param string $str: Input string :param bool $url_encoded: Whether to remove URL-encoded characters as well - :returns: string + :returns: Sanitized string + :rtype: string -This function prevents inserting NULL characters between ASCII -characters, like Java\\0script. + This function prevents inserting NULL characters between ASCII + characters, like Java\\0script. -Example:: + Example:: - remove_invisible_characters('Java\\0script'); - // Returns: 'Javascript' + remove_invisible_characters('Java\\0script'); + // Returns: 'Javascript' -html_escape() -============= +.. function:: html_escape($var) -.. php:function:: html_escape($var) + :param mixed $var: Variable to escape (string or array) + :returns: HTML escaped string(s) + :rtype: mixed - :param mixed $var: Variable to escape - (string or array) - :returns: mixed + This function acts as an alias for PHP's native ``htmlspecialchars()`` + function, with the advantage of being able to accept an array of strings. -This function acts as an alias for PHP's native ``htmlspecialchars()`` -function, with the advantage of being able to accept an array of strings. + It is useful in preventing Cross Site Scripting (XSS). -It is useful in preventing Cross Site Scripting (XSS). +.. function:: get_mimes() -get_mimes() -=========== + :returns: An associative array of file types + :rtype: array -.. php:function:: get_mimes() + This function returns a *reference* to the MIMEs array from + *application/config/mimes.php*. - :returns: array +.. function:: is_https() -This function returns a *reference* to the MIMEs array from -*application/config/mimes.php*. + :returns: TRUE if currently using HTTP-over-SSL, FALSE if not + :rtype: bool -is_https() -========== + Returns TRUE if a secure (HTTPS) connection is used and FALSE + in any other case (including non-HTTP requests). -.. php:function:: is_https() +.. function:: is_cli() - :returns: bool + :returns: TRUE if currently running under CLI, FALSE otherwise + :rtype: bool -Returns TRUE if a secure (HTTPS) connection is used and FALSE -in any other case (including non-HTTP requests). + Returns TRUE if the application is run through the command line + and FALSE if not. -function_usable() -================= + .. note:: This function checks both if the ``PHP_SAPI`` value is 'cli' + or if the ``STDIN`` constant is defined. -.. php:function:: function_usable($function_name) +.. function:: function_usable($function_name) :param string $function_name: Function name - :returns: bool + :returns: TRUE if the function can be used, FALSE if not + :rtype: bool + + Returns TRUE if a function exists and is usable, FALSE otherwise. -Returns TRUE if a function exists and is usable, FALSE otherwise. + This function runs a ``function_exists()`` check and if the + `Suhosin extension <http://www.hardened-php.net/suhosin/>` is loaded, + checks if it doesn't disable the function being checked. -This function runs a ``function_exists()`` check and if the -`Suhosin extension <http://www.hardened-php.net/suhosin/>` is loaded, -checks if it doesn't disable the function being checked. + It is useful if you want to check for the availability of functions + such as ``eval()`` and ``exec()``, which are dangerous and might be + disabled on servers with highly restrictive security policies. -It is useful if you want to check for the availability of functions -such as ``eval()`` and ``exec()``, which are dangerous and might be -disabled on servers with highly restrictive security policies.
\ No newline at end of file + .. note:: This function was introduced because Suhosin terminated + script execution, but this turned out to be a bug. A fix + has been available for some time (version 0.9.34), but is + unfortunately not released yet.
\ No newline at end of file diff --git a/user_guide_src/source/general/controllers.rst b/user_guide_src/source/general/controllers.rst index d8ef824fb..bc8319dd8 100644 --- a/user_guide_src/source/general/controllers.rst +++ b/user_guide_src/source/general/controllers.rst @@ -107,7 +107,7 @@ You should see your new message. Passing URI Segments to your methods ==================================== -If your URI contains more then two segments they will be passed to your +If your URI contains more than two segments they will be passed to your method as parameters. For example, let's say you have a URI like this:: diff --git a/user_guide_src/source/general/creating_libraries.rst b/user_guide_src/source/general/creating_libraries.rst index 4beb600da..a1e1b3e78 100644 --- a/user_guide_src/source/general/creating_libraries.rst +++ b/user_guide_src/source/general/creating_libraries.rst @@ -44,7 +44,8 @@ The Class File Classes should have this basic prototype:: - <?php if ( ! defined('BASEPATH')) exit('No direct script access allowed'); + <?php + defined('BASEPATH') OR exit('No direct script access allowed'); class Someclass { diff --git a/user_guide_src/source/general/errors.rst b/user_guide_src/source/general/errors.rst index f12d992f8..26c26bea1 100644 --- a/user_guide_src/source/general/errors.rst +++ b/user_guide_src/source/general/errors.rst @@ -21,23 +21,20 @@ without having to worry about class/function scoping. CodeIgniter also returns a status code whenever a portion of the core calls ``exit()``. This exit status code is separate from the HTTP status code, and serves as a notice to other processes that may be watching of -whether the script completed successfully, or if not, what kind of -problem it encountered that caused it to abort. These values are +whether the script completed successfully, or if not, what kind of +problem it encountered that caused it to abort. These values are defined in *application/config/constants.php*. While exit status codes are most useful in CLI settings, returning the proper code helps server software keep track of your scripts and the health of your application. The following functions let you generate errors: -show_error() -============ - -.. php:function:: show_error($message, $status_code, $heading = 'An Error Was Encountered') +.. function:: show_error($message, $status_code, $heading = 'An Error Was Encountered') :param mixed $message: Error message :param int $status_code: HTTP Response status code :param string $heading: Error page heading - :returns: void + :rtype: void This function will display the error message supplied to it using the following error template:: @@ -49,17 +46,14 @@ code should be sent with the error. If ``$status_code`` is less than 100, the HTTP status code will be set to 500, and the exit status code will be set to ``$status_code + EXIT__AUTO_MIN``. If that value is larger than ``EXIT__AUTO_MAX``, or if ``$status_code`` is 100 or higher, the exit -status code will be set to ``EXIT_ERROR``. You can check in +status code will be set to ``EXIT_ERROR``. You can check in *application/config/constants.php* for more detail. -show_404() -========== - -.. php:function:: show_404($page = '', $log_error = TRUE) +.. function:: show_404($page = '', $log_error = TRUE) :param string $page: URI string :param bool $log_error: Whether to log the error - :returns: void + :rtype: void This function will display the 404 error message supplied to it using the following error template:: @@ -74,15 +68,12 @@ not found. CodeIgniter automatically logs any ``show_404()`` calls. Setting the optional second parameter to FALSE will skip logging. -log_message() -============= - -.. php:function:: log_message($level, $message, $php_error = FALSE) +.. function:: log_message($level, $message, $php_error = FALSE) :param string $level: Log level: 'error', 'debug' or 'info' :param string $message: Message to log :param bool $php_error: Whether we're logging a native PHP error message - :returns: void + :rtype: void This function lets you write messages to your log files. You must supply one of three "levels" in the first parameter, indicating what type of diff --git a/user_guide_src/source/general/hooks.rst b/user_guide_src/source/general/hooks.rst index fc5da5b80..1046c48ae 100644 --- a/user_guide_src/source/general/hooks.rst +++ b/user_guide_src/source/general/hooks.rst @@ -59,7 +59,7 @@ defined in your associative hook array: Multiple Calls to the Same Hook =============================== -If want to use the same hook point with more then one script, simply +If want to use the same hook point with more than one script, simply make your array declaration multi-dimensional, like this:: $hook['pre_controller'][] = array( diff --git a/user_guide_src/source/general/profiling.rst b/user_guide_src/source/general/profiling.rst index 6dbd0be16..f29af8102 100644 --- a/user_guide_src/source/general/profiling.rst +++ b/user_guide_src/source/general/profiling.rst @@ -80,4 +80,8 @@ Key Description **session_data** Data stored in the current session TRUE **query_toggle_count** The number of queries after which the query block will default to 25 hidden. -======================= =================================================================== ========
\ No newline at end of file +======================= =================================================================== ======== + +.. note:: Disabling the **save_queries** setting in your database configuration + will also effectively disable profiling for database queries and render + the 'queries' setting above useless.
\ No newline at end of file diff --git a/user_guide_src/source/general/requirements.rst b/user_guide_src/source/general/requirements.rst index 104923625..0b67e8e3a 100644 --- a/user_guide_src/source/general/requirements.rst +++ b/user_guide_src/source/general/requirements.rst @@ -2,14 +2,15 @@ Server Requirements ################### -- `PHP <http://www.php.net/>`_ version 5.2.4 or newer. -- A Database is required for most web application programming. - Currently supported databases are: - - MySQL (5.1+) via the *mysql* (deprecated), *mysqli* and *pdo* drivers - - Oracle via the *oci8* and *pdo* drivers - - PostgreSQL via the *postgre* and *pdo* drivers - - MS SQL via the *mssql*, *sqlsrv* (version 2005 and above only) and *pdo* drivers - - SQLite via the *sqlite* (version 2), *sqlite3* (version 3) and *pdo* drivers - - CUBRID via the *cubrid* and *pdo* drivers - - Interbase/Firebird via the *ibase* and *pdo* drivers - - ODBC via the *odbc* and *pdo* drivers (you should know that ODBC is actually an abstraction layer)
\ No newline at end of file +- `PHP <http://www.php.net/>`_ version 5.2.4 or newer. +- A Database is required for most web application programming. + + Currently supported databases are: + - MySQL (5.1+) via the *mysql* (deprecated), *mysqli* and *pdo* drivers + - Oracle via the *oci8* and *pdo* drivers + - PostgreSQL via the *postgre* and *pdo* drivers + - MS SQL via the *mssql*, *sqlsrv* (version 2005 and above only) and *pdo* drivers + - SQLite via the *sqlite* (version 2), *sqlite3* (version 3) and *pdo* drivers + - CUBRID via the *cubrid* and *pdo* drivers + - Interbase/Firebird via the *ibase* and *pdo* drivers + - ODBC via the *odbc* and *pdo* drivers (you should know that ODBC is actually an abstraction layer)
\ No newline at end of file diff --git a/user_guide_src/source/general/reserved_names.rst b/user_guide_src/source/general/reserved_names.rst index ccc17d61b..81a05ace6 100644 --- a/user_guide_src/source/general/reserved_names.rst +++ b/user_guide_src/source/general/reserved_names.rst @@ -25,22 +25,22 @@ your controller any of these: Functions --------- -- :php:func:`is_php()` -- :php:func:`is_really_writable()` +- :func:`is_php()` +- :func:`is_really_writable()` - ``load_class()`` - ``is_loaded()`` - ``get_config()`` -- :php:func:`config_item()` -- :php:func:`show_error()` -- :php:func:`show_404()` -- :php:func:`log_message()` -- :php:func:`set_status_header()` -- :php:func:`get_mimes()` -- :php:func:`html_escape()` -- :php:func:`remove_invisible_characters()` -- :php:func:`is_https()` -- :php:func:`function_usable()` -- :php:func:`get_instance()` +- :func:`config_item()` +- :func:`show_error()` +- :func:`show_404()` +- :func:`log_message()` +- :func:`set_status_header()` +- :func:`get_mimes()` +- :func:`html_escape()` +- :func:`remove_invisible_characters()` +- :func:`is_https()` +- :func:`function_usable()` +- :func:`get_instance()` - ``_exception_handler()`` - ``_stringify_attributes()`` @@ -61,6 +61,9 @@ Constants - APPPATH - VIEWPATH - CI_VERSION +- MB_ENABLED +- ICONV_ENABLED +- UTF8_ENABLED - FILE_READ_MODE - FILE_WRITE_MODE - DIR_READ_MODE diff --git a/user_guide_src/source/general/routing.rst b/user_guide_src/source/general/routing.rst index 5520f59fe..0b91d3fa9 100644 --- a/user_guide_src/source/general/routing.rst +++ b/user_guide_src/source/general/routing.rst @@ -142,6 +142,29 @@ routing rules to process the back-references. Example:: return 'catalog/product_edit/' . strtolower($product_type) . '/' . $id; }; +Using HTTP verbs in routes +========================== + +It is possible to use HTTP verbs (request method) to define your routing rules. +This is particularly useful when building RESTful applications. You can use standard HTTP +verbs (GET, PUT, POST, DELETE, PATCH) or a custom one such (e.g. PURGE). HTTP verb rules +are case-insensitive. All you need to do is to add the verb as an array key to your route. +Example:: + + $route['products']['put'] = 'product/insert'; + +In the above example, a PUT request to URI "products" would call the ``Product::insert()`` +controller method. + +:: + + $route['products/(:num)']['DELETE'] = 'product/delete/$1'; + +A DELETE request to URL with "products" as first the segment and a number in the second will be +mapped to the ``Product::delete()`` method, passing the numeric value as the first parameter. + +Using HTTP verbs is of course, optional. + Reserved Routes =============== diff --git a/user_guide_src/source/general/styleguide.rst b/user_guide_src/source/general/styleguide.rst index 5613eabec..6718bc342 100644 --- a/user_guide_src/source/general/styleguide.rst +++ b/user_guide_src/source/general/styleguide.rst @@ -565,7 +565,7 @@ the ability to change this in the php.ini, you can often enable it with:: ini_set('display_errors', 1); .. note:: Setting the `display_errors - <http://php.net/manual/en/ref.errorfunc.php#ini.display-errors>`_ + <http://php.net/manual/en/errorfunc.configuration.php#ini.display-errors>`_ setting with ``ini_set()`` at runtime is not identical to having it enabled in the PHP environment. Namely, it will not have any effect if the script has fatal errors. |