summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/general/hooks.rst
diff options
context:
space:
mode:
authorEric Barnes <eric@ericlbarnes.com>2011-11-27 06:30:22 +0100
committerEric Barnes <eric@ericlbarnes.com>2011-11-27 06:30:22 +0100
commit7e66dda705743cbfe1d522ddb73e5694006ec42c (patch)
treec08b63deb28c09ec49d9173280f1ca234debfe50 /user_guide_src/source/general/hooks.rst
parent7eceb03f083643254c7393c6b5ebe539e344a1ba (diff)
parente101593561a10632c1d63180436b19f1d7115046 (diff)
Merge branch 'refs/heads/develop' into feature/unit-tests
Conflicts: user_guide/helpers/number_helper.html
Diffstat (limited to 'user_guide_src/source/general/hooks.rst')
-rw-r--r--user_guide_src/source/general/hooks.rst118
1 files changed, 118 insertions, 0 deletions
diff --git a/user_guide_src/source/general/hooks.rst b/user_guide_src/source/general/hooks.rst
new file mode 100644
index 000000000..65696f6c7
--- /dev/null
+++ b/user_guide_src/source/general/hooks.rst
@@ -0,0 +1,118 @@
+####################################
+Hooks - Extending the Framework Core
+####################################
+
+CodeIgniter's Hooks feature provides a means to tap into and modify the
+inner workings of the framework without hacking the core files. When
+CodeIgniter runs it follows a specific execution process, diagramed in
+the :doc:`Application Flow <../overview/appflow>` page. There may be
+instances, however, where you'd like to cause some action to take place
+at a particular stage in the execution process. For example, you might
+want to run a script right before your controllers get loaded, or right
+after, or you might want to trigger one of your own scripts in some
+other location.
+
+Enabling Hooks
+==============
+
+The hooks feature can be globally enabled/disabled by setting the
+following item in the application/config/config.php file::
+
+ $config['enable_hooks'] = TRUE;
+
+Defining a Hook
+===============
+
+Hooks are defined in application/config/hooks.php file. Each hook is
+specified as an array with this prototype::
+
+ $hook['pre_controller'] = array(
+ 'class' => 'MyClass',
+ 'function' => 'Myfunction',
+ 'filename' => 'Myclass.php',
+ 'filepath' => 'hooks',
+ 'params' => array('beer', 'wine', 'snacks')
+ );
+
+**Notes:**
+The array index correlates to the name of the particular hook point you
+want to use. In the above example the hook point is pre_controller. A
+list of hook points is found below. The following items should be
+defined in your associative hook array:
+
+- **class** The name of the class you wish to invoke. If you prefer to
+ use a procedural function instead of a class, leave this item blank.
+- **function** The function name you wish to call.
+- **filename** The file name containing your class/function.
+- **filepath** The name of the directory containing your script. Note:
+ Your script must be located in a directory INSIDE your application
+ folder, so the file path is relative to that folder. For example, if
+ your script is located in application/hooks, you will simply use
+ hooks as your filepath. If your script is located in
+ application/hooks/utilities you will use hooks/utilities as your
+ filepath. No trailing slash.
+- **params** Any parameters you wish to pass to your script. This item
+ is optional.
+
+Multiple Calls to the Same Hook
+===============================
+
+If want to use the same hook point with more then one script, simply
+make your array declaration multi-dimensional, like this::
+
+ $hook['pre_controller'][] = array(
+ 'class' => 'MyClass',
+ 'function' => 'Myfunction',
+ 'filename' => 'Myclass.php',
+ 'filepath' => 'hooks',
+ 'params' => array('beer', 'wine', 'snacks')
+ );
+
+ $hook['pre_controller'][] = array(
+ 'class' => 'MyOtherClass',
+ 'function' => 'MyOtherfunction',
+ 'filename' => 'Myotherclass.php',
+ 'filepath' => 'hooks',
+ 'params' => array('red', 'yellow', 'blue')
+ );
+
+Notice the brackets after each array index::
+
+ $hook['pre_controller'][]
+
+This permits you to have the same hook point with multiple scripts. The
+order you define your array will be the execution order.
+
+Hook Points
+===========
+
+The following is a list of available hook points.
+
+- **pre_system**
+ Called very early during system execution. Only the benchmark and
+ hooks class have been loaded at this point. No routing or other
+ processes have happened.
+- **pre_controller**
+ Called immediately prior to any of your controllers being called.
+ All base classes, routing, and security checks have been done.
+- **post_controller_constructor**
+ Called immediately after your controller is instantiated, but prior
+ to any method calls happening.
+- **post_controller**
+ Called immediately after your controller is fully executed.
+- **display_override**
+ Overrides the _display() function, used to send the finalized page
+ to the web browser at the end of system execution. This permits you
+ to use your own display methodology. Note that you will need to
+ reference the CI superobject with $this->CI =& get_instance() and
+ then the finalized data will be available by calling
+ $this->CI->output->get_output()
+- **cache_override**
+ Enables you to call your own function instead of the
+ _display_cache() function in the output class. This permits you to
+ use your own cache display mechanism.
+- **post_system**
+ Called after the final rendered page is sent to the browser, at the
+ end of system execution after the finalized data is sent to the
+ browser.
+