diff options
Diffstat (limited to 'user_guide_src/source/general/controllers.rst')
| -rw-r--r-- | user_guide_src/source/general/controllers.rst | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/user_guide_src/source/general/controllers.rst b/user_guide_src/source/general/controllers.rst new file mode 100644 index 000000000..8f02df21f --- /dev/null +++ b/user_guide_src/source/general/controllers.rst @@ -0,0 +1,258 @@ +########### +Controllers +########### + +Controllers are the heart of your application, as they determine how +HTTP requests should be handled. + +- `What is a Controller? <#what>`_ +- `Hello World <#hello>`_ +- `Functions <#functions>`_ +- `Passing URI Segments to Your Functions <#passinguri>`_ +- `Defining a Default Controller <#default>`_ +- `Remapping Function Calls <#remapping>`_ +- `Controlling Output Data <#output>`_ +- `Private Functions <#private>`_ +- `Organizing Controllers into Sub-folders <#subfolders>`_ +- `Class Constructors <#constructors>`_ +- `Reserved Function Names <#reserved>`_ + +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; } + +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. |