summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/general/common_functions.rst
blob: 2ca7478ec47d5c9e8c900ceb93f0f1cdd908aa2e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
################
Common Functions
################

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.

.. contents::
  :local:

.. raw:: html

  <div class="custom-index container"></div>

.. function:: is_php([$version = '5.3.0'])

	:param	string	$version: Version number
	:returns:	TRUE if the running PHP version is at least the one specified or FALSE if not
	:rtype:	bool

	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);
		}

	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.

.. function:: is_really_writable($file)

	:param	string	$file: File path
	: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.

	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";
		}
		else
		{
			echo "File is not writable";
		}

	.. note:: See also `PHP bug #54709 <https://bugs.php.net/bug.php?id=54709>`_ for more info.

.. function:: config_item($key)

	:param	string	$key: Config item key
	: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.

.. :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
	:rtype:	void

	This function calls ``CI_Exception::show_error()``. For more info,
	please see the :doc:`Error Handling <errors>` documentation.

.. :noindex: function:: show_404([$page = ''[, $log_error = TRUE]])

	:param	string	$page: URI string
	:param	bool	$log_error: Whether to log the error
	:rtype:	void

	This function calls ``CI_Exception::show_404()``. For more info,
	please see the :doc:`Error Handling <errors>` documentation.

.. :noindex: function:: log_message($level, $message)

	:param	string	$level: Log level: 'error', 'debug' or 'info'
	:param	string	$message: Message to log
	:rtype:	void

	This function is an alias for ``CI_Log::write_log()``. For more info,
	please see the :doc:`Error Handling <errors>` documentation.

.. 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
	:rtype:	void

	Permits you to manually set a server status header. Example::

		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.

.. 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:	Sanitized string
	:rtype:	string

	This function prevents inserting NULL characters between ASCII
	characters, like Java\\0script.

	Example::

		remove_invisible_characters('Java\\0script');
		// Returns: 'Javascript'

.. function:: html_escape($var)

	:param	mixed	$var: Variable to escape (string or array)
	:returns:	HTML escaped string(s)
	:rtype:	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).

.. function:: get_mimes()

	:returns:	An associative array of file types
	:rtype:	array

	This function returns a *reference* to the MIMEs array from
	*application/config/mimes.php*.

.. function:: is_https()

	:returns:	TRUE if currently using HTTP-over-SSL, FALSE if not
	:rtype:	bool

	Returns TRUE if a secure (HTTPS) connection is used and FALSE
	in any other case (including non-HTTP requests).

.. function:: is_cli()

	:returns:	TRUE if currently running under CLI, FALSE otherwise
	:rtype:	bool

	Returns TRUE if the application is run through the command line
	and FALSE if not.

	.. note:: This function checks both if the ``PHP_SAPI`` value is 'cli'
		or if the ``STDIN`` constant is defined.

.. function:: function_usable($function_name)

	:param	string	$function_name: Function name
	:returns:	TRUE if the function can be used, FALSE if not
	:rtype:	bool

	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.

	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.

	.. 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.