diff options
Diffstat (limited to 'user_guide_src/source/general/hooks.rst')
| -rw-r--r-- | user_guide_src/source/general/hooks.rst | 118 |
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. + |