Browse files

Polish the Common functions documentation

  • Loading branch information...
1 parent 08f0f8b commit 1bc30260d8bd35a958f3d7b899f68c95d69c9e75 @narfbg narfbg committed Nov 9, 2012
Showing with 124 additions and 36 deletions.
  1. +5 −5 user_guide_src/source/changelog.rst
  2. +119 −31 user_guide_src/source/general/common_functions.rst
View
10 user_guide_src/source/changelog.rst
@@ -273,12 +273,12 @@ Release Date: Not Released
- Changed internal method ``_sanitize_globals()`` to skip enforcing reversal of *register_globals* in PHP 5.4+, where this functionality no longer exists.
- Changed methods ``get()``, ``post()``, ``get_post()``, ``cookie()``, ``server()``, ``user_agent()`` to return NULL instead of FALSE when no value is found.
- :doc:`Common functions <general/common_functions>` changes include:
- - Added function ``get_mimes()`` to return the *config/mimes.php* array.
- - Added support for HTTP code 303 ("See Other") in ``set_status_header()``.
- - Removed redundant conditional to determine HTTP server protocol in ``set_status_header()``.
+ - Added function :php:func:`get_mimes()` to return the *application/config/mimes.php* array.
+ - Added support for HTTP code 303 ("See Other") in :php:func:`set_status_header()`.
+ - Removed redundant conditional to determine HTTP server protocol in :php:func:`set_status_header()`.
- Changed ``_exception_handler()`` to respect php.ini *display_errors* setting.
- - Added function ``is_https()`` to check if a secure connection is used.
- - Added function ``function_usable()`` to check if a function exists and is not disabled by `Suhosin <http://www.hardened-php.net/suhosin/>`.
+ - Added function :php:func:`is_https()` to check if a secure connection is used.
+ - Added function :php:func:`function_usable()` to check if a function exists and is not disabled by `Suhosin <http://www.hardened-php.net/suhosin/>`.
- Added support for HTTP-Only cookies with new config option *cookie_httponly* (default FALSE).
- Renamed method ``_call_hook()`` to ``call_hook()`` in the :doc:`Hooks Library <general/hooks>`.
- :doc:`Output Library <libraries/output>` changes include:
View
150 user_guide_src/source/general/common_functions.rst
@@ -6,45 +6,62 @@ 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('version_number')
-========================
+is_php()
+========
-is_php() determines of the PHP version being used is greater than the
-supplied version_number.
+.. php:function:: is_php($version = '5.3.0')
-::
+ :param string $version: Version number
+ :returns: bool
- if (is_php('5.3.0'))
+Determines of the PHP version being used is greater than the
+supplied version number.
+
+Example::
+
+ if (is_php('5.3'))
{
- $str = quoted_printable_encode($str);
+ $str = quoted_printable_encode($str);
}
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.
-is_really_writable('path/to/file')
-==================================
+is_really_writable()
+====================
+
+.. php:function:: is_really_writeable($file)
-is_writable() returns TRUE on Windows servers when you really can't
+ :param string $file: File path
+ :returns: 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. 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.
+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.
-::
+Example::
if (is_really_writable('file.txt'))
{
- echo "I could write to this if I wanted to";
+ echo "I could write to this if I wanted to";
}
else
{
- echo "File is not writable";
+ echo "File is not writable";
}
-config_item('item_key')
-=======================
+config_item()
+=============
+
+.. php:function:: config_item($key)
+
+ :param string $key: Config item key
+ :returns: mixed
The :doc:`Config Library <../libraries/config>` is the preferred way of
accessing configuration information, however ``config_item()`` can be used
@@ -55,14 +72,53 @@ documentation for more information.
files. It does not take into account config values that are
dynamically set at runtime.
-show_error('message'), show_404('page'), log_message('level', 'message')
-========================================================================
+show_error()
+============
+
+.. php: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.
+
+show_404()
+==========
+
+.. php:function:: show_404($page = '', $log_error = TRUE)
+
+ :param string $page: URI string
+ :param bool $log_error: Whether to log the error
+ :returns: void
+
+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 = 'error', $message, $php_error = FALSE)
-These are each outlined on the :doc:`Error Handling <errors>` page.
+ :param string $level: Log level
+ :param string $message: Message to log
+ :param bool $php_error: Whether we're loggin a native PHP error message
+ :returns: void
-set_status_header(code, 'text')
+This function is an alias for ``CI_Log::write_log()``. For more info,
+please see the :doc:`Error Handling <errors>` documentation.
+
+set_status_header()
===============================
+.. php: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
+
Permits you to manually set a server status header. Example::
set_status_header(401);
@@ -71,33 +127,65 @@ Permits you to manually set a server status header. Example::
`See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for
a full list of headers.
-remove_invisible_characters($str)
-=================================
+remove_invisible_characters()
+=============================
+
+.. php:function:: remove_invisible_characters($str, $url_encoded = TRUE)
-This function prevents inserting null characters between ascii
+ :param string $str: Input string
+ :param bool $url_encoded: Whether to remove URL-encoded characters as well
+ :returns: string
+
+This function prevents inserting NULL characters between ASCII
characters, like Java\\0script.
-html_escape($mixed)
-===================
+Example::
+
+ remove_invisible_characters('Java\\0script');
+ // Returns: 'Javascript'
+
+html_escape()
+=============
+
+.. php:function:: html_escape($var)
-This function provides short cut for ``htmlspecialchars()`` function. It
-accepts string and array. To prevent Cross Site Scripting (XSS), it is
-very useful.
+ :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.
+
+It is useful in preventing Cross Site Scripting (XSS).
get_mimes()
===========
-This function returns the MIMEs array *from config/mimes.php*.
+.. php:function:: get_mimes()
+
+ :returns: array
+
+This function returns a *reference* to the MIMEs array from
+*application/config/mimes.php*.
is_https()
==========
+.. php:function:: is_https()
+
+ :returns: bool
+
Returns TRUE if a secure (HTTPS) connection is used and FALSE
in any other case (including non-HTTP requests).
function_usable($function_name)
===============================
+.. php:function:: function_usable($function_name)
+
+ :param string $function_name: Function name
+ :returns: bool
+
Returns TRUE if a function exists and is usable, FALSE otherwise.
This function runs a ``function_exists()`` check and if the

0 comments on commit 1bc3026

Please sign in to comment.