blob: e085ef80847232fb1885f60db6bbd8dbdfa57f14 [file] [log] [blame]
Derek Jones8ede1a22011-10-05 13:34:52 -05001################
2Common Functions
3################
4
5CodeIgniter uses a few functions for its operation that are globally
6defined, and are available to you at any point. These do not require
7loading any libraries or helpers.
8
Andrey Andreev1bc30262012-11-09 11:30:51 +02009is_php()
10========
Derek Jones8ede1a22011-10-05 13:34:52 -050011
Andrey Andreev1bc30262012-11-09 11:30:51 +020012.. php:function:: is_php($version = '5.3.0')
Derek Jones8ede1a22011-10-05 13:34:52 -050013
Andrey Andreev1bc30262012-11-09 11:30:51 +020014 :param string $version: Version number
15 :returns: bool
Derek Jones8ede1a22011-10-05 13:34:52 -050016
Andrey Andreev1bc30262012-11-09 11:30:51 +020017Determines of the PHP version being used is greater than the
18supplied version number.
19
20Example::
21
22 if (is_php('5.3'))
Derek Jones46715e52011-10-05 17:36:22 -050023 {
Andrey Andreev1bc30262012-11-09 11:30:51 +020024 $str = quoted_printable_encode($str);
Derek Jones46715e52011-10-05 17:36:22 -050025 }
Derek Jones8ede1a22011-10-05 13:34:52 -050026
27Returns boolean TRUE if the installed version of PHP is equal to or
28greater than the supplied version number. Returns FALSE if the installed
29version of PHP is lower than the supplied version number.
30
Andrey Andreev1bc30262012-11-09 11:30:51 +020031is_really_writable()
32====================
Derek Jones8ede1a22011-10-05 13:34:52 -050033
vlakoff9a6032d2013-03-05 23:03:12 +010034.. php:function:: is_really_writable($file)
Andrey Andreev1bc30262012-11-09 11:30:51 +020035
36 :param string $file: File path
37 :returns: bool
38
39``is_writable()`` returns TRUE on Windows servers when you really can't
Derek Jones8ede1a22011-10-05 13:34:52 -050040write to the file as the OS reports to PHP as FALSE only if the
Andrey Andreev1bc30262012-11-09 11:30:51 +020041read-only attribute is marked.
Derek Jones8ede1a22011-10-05 13:34:52 -050042
Andrey Andreev1bc30262012-11-09 11:30:51 +020043This function determines if a file is actually writable by attempting
44to write to it first. Generally only recommended on platforms where
45this information may be unreliable.
46
47Example::
Derek Jones8ede1a22011-10-05 13:34:52 -050048
Derek Jones46715e52011-10-05 17:36:22 -050049 if (is_really_writable('file.txt'))
50 {
Andrey Andreev1bc30262012-11-09 11:30:51 +020051 echo "I could write to this if I wanted to";
Derek Jones46715e52011-10-05 17:36:22 -050052 }
53 else
54 {
Andrey Andreev1bc30262012-11-09 11:30:51 +020055 echo "File is not writable";
Derek Jones46715e52011-10-05 17:36:22 -050056 }
Derek Jones8ede1a22011-10-05 13:34:52 -050057
Andrey Andreev1bc30262012-11-09 11:30:51 +020058config_item()
59=============
60
61.. php:function:: config_item($key)
62
63 :param string $key: Config item key
64 :returns: mixed
Derek Jones8ede1a22011-10-05 13:34:52 -050065
Andrey Andreev7b18a3f2012-11-04 20:27:35 +020066The :doc:`Config Library <../libraries/config>` is the preferred way of
67accessing configuration information, however ``config_item()`` can be used
68to retrieve single keys. See :doc:`Config Library <../libraries/config>`
69documentation for more information.
70
Andrey Andreev1bc30262012-11-09 11:30:51 +020071show_error()
72============
Derek Jones8ede1a22011-10-05 13:34:52 -050073
Andrey Andreev1bc30262012-11-09 11:30:51 +020074.. php:function:: show_error($message, $status_code, $heading = 'An Error Was Encountered')
Derek Jones8ede1a22011-10-05 13:34:52 -050075
Andrey Andreev1bc30262012-11-09 11:30:51 +020076 :param mixed $message: Error message
77 :param int $status_code: HTTP Response status code
78 :param string $heading: Error page heading
79 :returns: void
80
81This function calls ``CI_Exception::show_error()``. For more info,
82please see the :doc:`Error Handling <errors>` documentation.
83
84show_404()
85==========
86
87.. php:function:: show_404($page = '', $log_error = TRUE)
88
89 :param string $page: URI string
90 :param bool $log_error: Whether to log the error
91 :returns: void
92
93This function calls ``CI_Exception::show_404()``. For more info,
94please see the :doc:`Error Handling <errors>` documentation.
95
96log_message()
97=============
98
Andrey Andreev838c9a92013-09-13 14:05:13 +030099.. php:function:: log_message($level, $message)
Andrey Andreev1bc30262012-11-09 11:30:51 +0200100
vlakoffd0c30ab2013-05-07 07:49:23 +0200101 :param string $level: Log level: 'error', 'debug' or 'info'
Andrey Andreev1bc30262012-11-09 11:30:51 +0200102 :param string $message: Message to log
Andrey Andreev1bc30262012-11-09 11:30:51 +0200103 :returns: void
104
105This function is an alias for ``CI_Log::write_log()``. For more info,
106please see the :doc:`Error Handling <errors>` documentation.
107
108set_status_header()
Andrey Andreev3fb02672012-10-22 16:48:01 +0300109===============================
Derek Jones8ede1a22011-10-05 13:34:52 -0500110
Andrey Andreev1bc30262012-11-09 11:30:51 +0200111.. php:function:: set_status_header($code, $text = '')
112
113 :param int $code: HTTP Reponse status code
114 :param string $text: A custom message to set with the status code
115 :returns: void
116
Derek Jones8ede1a22011-10-05 13:34:52 -0500117Permits you to manually set a server status header. Example::
118
Derek Jones46715e52011-10-05 17:36:22 -0500119 set_status_header(401);
120 // Sets the header as: Unauthorized
Derek Jones8ede1a22011-10-05 13:34:52 -0500121
122`See here <http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html>`_ for
123a full list of headers.
124
Andrey Andreev1bc30262012-11-09 11:30:51 +0200125remove_invisible_characters()
126=============================
Derek Jones8ede1a22011-10-05 13:34:52 -0500127
Andrey Andreev1bc30262012-11-09 11:30:51 +0200128.. php:function:: remove_invisible_characters($str, $url_encoded = TRUE)
129
130 :param string $str: Input string
131 :param bool $url_encoded: Whether to remove URL-encoded characters as well
132 :returns: string
133
134This function prevents inserting NULL characters between ASCII
Derek Jones8ede1a22011-10-05 13:34:52 -0500135characters, like Java\\0script.
136
Andrey Andreev1bc30262012-11-09 11:30:51 +0200137Example::
Derek Jones8ede1a22011-10-05 13:34:52 -0500138
Andrey Andreev1bc30262012-11-09 11:30:51 +0200139 remove_invisible_characters('Java\\0script');
140 // Returns: 'Javascript'
141
142html_escape()
143=============
144
145.. php:function:: html_escape($var)
146
147 :param mixed $var: Variable to escape
148 (string or array)
149 :returns: mixed
150
151This function acts as an alias for PHP's native ``htmlspecialchars()``
152function, with the advantage of being able to accept an array of strings.
153
154It is useful in preventing Cross Site Scripting (XSS).
Andrey Andreev6ef498b2012-06-05 22:01:58 +0300155
156get_mimes()
Andrey Andreev3fb02672012-10-22 16:48:01 +0300157===========
Andrey Andreev6ef498b2012-06-05 22:01:58 +0300158
Andrey Andreev1bc30262012-11-09 11:30:51 +0200159.. php:function:: get_mimes()
160
161 :returns: array
162
163This function returns a *reference* to the MIMEs array from
164*application/config/mimes.php*.
Andrey Andreev3fb02672012-10-22 16:48:01 +0300165
166is_https()
167==========
168
Andrey Andreev1bc30262012-11-09 11:30:51 +0200169.. php:function:: is_https()
170
171 :returns: bool
172
Andrey Andreev3fb02672012-10-22 16:48:01 +0300173Returns TRUE if a secure (HTTPS) connection is used and FALSE
Andrey Andreeve9d2dc82012-11-07 14:23:29 +0200174in any other case (including non-HTTP requests).
175
Andrey Andreev838a9d62012-12-03 14:37:47 +0200176function_usable()
177=================
Andrey Andreeve9d2dc82012-11-07 14:23:29 +0200178
Andrey Andreev1bc30262012-11-09 11:30:51 +0200179.. php:function:: function_usable($function_name)
180
181 :param string $function_name: Function name
182 :returns: bool
183
Andrey Andreeve9d2dc82012-11-07 14:23:29 +0200184Returns TRUE if a function exists and is usable, FALSE otherwise.
185
186This function runs a ``function_exists()`` check and if the
187`Suhosin extension <http://www.hardened-php.net/suhosin/>` is loaded,
188checks if it doesn't disable the function being checked.
189
190It is useful if you want to check for the availability of functions
191such as ``eval()`` and ``exec()``, which are dangerous and might be
192disabled on servers with highly restrictive security policies.