summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/general/controllers.rst
blob: c3c19cc620070ace27d19eeae74e6fe91e39af31 (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
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
###########
Controllers
###########

Controllers are the heart of your application, as they determine how
HTTP requests should be handled.

.. contents:: Page Contents

What is a Controller?
=====================

A Controller is simply a class file that is named in a way that can be
associated with a URI.

Consider this URI::

	example.com/index.php/blog/

In the above example, CodeIgniter would attempt to find a controller
named blog.php and load it.

**When a controller's name matches the first segment of a URI, it will
be loaded.**

Let's try it: Hello World!
==========================

Let's create a simple controller so you can see it in action. Using your
text editor, create a file called blog.php, and put the following code
in it::

	<?php
	class Blog extends CI_Controller {

		public function index()
		{
			echo 'Hello World!';
		}
	}
	?>

Then save the file to your application/controllers/ folder.

Now visit the your site using a URL similar to this::

	example.com/index.php/blog/

If you did it right, you should see Hello World!.

Note: Class names must start with an uppercase letter. In other words,
this is valid::

	<?php
	class Blog extends CI_Controller {

	}
	?>
	

This is **not** valid::

	<?php
	class blog extends CI_Controller {

	}
	?>

Also, always make sure your controller extends the parent controller
class so that it can inherit all its functions.

Functions
=========

In the above example the function name is index(). The "index" function
is always loaded by default if the **second segment** of the URI is
empty. Another way to show your "Hello World" message would be this::

	example.com/index.php/blog/index/

**The second segment of the URI determines which function in the
controller gets called.**

Let's try it. Add a new function to your controller::

	<?php
	class Blog extends CI_Controller {

		public function index()
		{
			echo 'Hello World!';
		}

		public function comments()
		{
			echo 'Look at this!';
		}
	}
	?>

Now load the following URL to see the comment function::

	example.com/index.php/blog/comments/

You should see your new message.

Passing URI Segments to your Functions
======================================

If your URI contains more then two segments they will be passed to your
function as parameters.

For example, lets say you have a URI like this::

	example.com/index.php/products/shoes/sandals/123

Your function will be passed URI segments 3 and 4 ("sandals" and "123")::

	<?php
	class Products extends CI_Controller {

	    public function shoes($sandals, $id)
	    {
	        echo $sandals;
	        echo $id;
	    }
	}
	?>

.. important:: If you are using the :doc:`URI Routing <routing>`
	feature, the segments passed to your function will be the re-routed
	ones.

Defining a Default Controller
=============================

CodeIgniter can be told to load a default controller when a URI is not
present, as will be the case when only your site root URL is requested.
To specify a default controller, open your application/config/routes.php
file and set this variable::

	$route['default_controller'] = 'Blog';

Where Blog is the name of the controller class you want used. If you now
load your main index.php file without specifying any URI segments you'll
see your Hello World message by default.

Remapping Function Calls
========================

As noted above, the second segment of the URI typically determines which
function in the controller gets called. CodeIgniter permits you to
override this behavior through the use of the _remap() function::

	public function _remap()
	{
	    // Some code here...
	}

.. important:: If your controller contains a function named _remap(),
	it will **always** get called regardless of what your URI contains. It
	overrides the normal behavior in which the URI determines which function
	is called, allowing you to define your own function routing rules.

The overridden function call (typically the second segment of the URI)
will be passed as a parameter to the _remap() function::

	public function _remap($method)
	{
	    if ($method == 'some_method')
	    {
	        $this->$method();
	    }
	    else
	    {
	        $this->default_method();
	    }
	}

Any extra segments after the method name are passed into _remap() as an
optional second parameter. This array can be used in combination with
PHP's `call_user_func_array <http://php.net/call_user_func_array>`_
to emulate CodeIgniter's default behavior.

::

	public function _remap($method, $params = array())
	{
	    $method = 'process_'.$method;
	    if (method_exists($this, $method))
	    {
	        return call_user_func_array(array($this, $method), $params);
	    }
	    show_404();
	}

Processing Output
=================

CodeIgniter has an output class that takes care of sending your final
rendered data to the web browser automatically. More information on this
can be found in the :doc::doc:`Views <views>` and `Output
class <../libraries/output>` pages. In some cases, however, you
might want to post-process the finalized data in some way and send it to
the browser yourself. CodeIgniter permits you to add a function named
_output() to your controller that will receive the finalized output
data.

.. important:: If your controller contains a function named _output(),
	it will **always** be called by the output class instead of echoing the
	finalized data directly. The first parameter of the function will
	contain the finalized output.

Here is an example::

	public function _output($output)
	{
	    echo $output;
	}

.. note:: Please note that your _output() function will receive the data in its
	finalized state. Benchmark and memory usage data will be rendered, cache
	files written (if you have caching enabled), and headers will be sent
	(if you use that :doc:`feature <../libraries/output>`) before it is
	handed off to the _output() function.
	To have your controller's output cached properly, its _output() method
	can use::

		if ($this->output->cache_expiration > 0)
		{
		    $this->output->_write_cache($output);
		}

	If you are using this feature the page execution timer and memory usage
	stats might not be perfectly accurate since they will not take into
	acccount any further processing you do. For an alternate way to control
	output *before* any of the final processing is done, please see the
	available methods in the :doc:`Output Class <../libraries/output>`.

Private Functions
=================

In some cases you may want certain functions hidden from public access.
To make a function private, simply add an underscore as the name prefix
and it will not be served via a URL request. For example, if you were to
have a function like this::

	private function _utility()
	{
	  // some code
	}

Trying to access it via the URL, like this, will not work::

	example.com/index.php/blog/_utility/

Organizing Your Controllers into Sub-folders
============================================

If you are building a large application you might find it convenient to
organize your controllers into sub-folders. CodeIgniter permits you to
do this.

Simply create folders within your application/controllers directory and
place your controller classes within them.

.. note:: When using this feature the first segment of your URI must
	specify the folder. For example, lets say you have a controller located
	here::

		application/controllers/products/shoes.php

	To call the above controller your URI will look something like this::

		example.com/index.php/products/shoes/show/123

Each of your sub-folders may contain a default controller which will be
called if the URL contains only the sub-folder. Simply name your default
controller as specified in your application/config/routes.php file

CodeIgniter also permits you to remap your URIs using its :doc:`URI
Routing <routing>` feature.

Class Constructors
==================

If you intend to use a constructor in any of your Controllers, you
**MUST** place the following line of code in it::

	parent::__construct();

The reason this line is necessary is because your local constructor will
be overriding the one in the parent controller class so we need to
manually call it.

::

	<?php
	class Blog extends CI_Controller {

	       public function __construct()
	       {
	            parent::__construct();
	            // Your own constructor code
	       }
	}
	?>

Constructors are useful if you need to set some default values, or run a
default process when your class is instantiated. Constructors can't
return a value, but they can do some default work.

Reserved Function Names
=======================

Since your controller classes will extend the main application
controller you must be careful not to name your functions identically to
the ones used by that class, otherwise your local functions will
override them. See :doc:`Reserved Names <reserved_names>` for a full
list.

That's it!
==========

That, in a nutshell, is all there is to know about controllers.