Community Documentation

v3 Knowledgebase

Primer on Hooks/Plugins

What is a Hook?
A hook is a way to execute your code without editing the source files. Internally the script uses eval() to run your code.
When you edit the script's source files you are hindering the update process and voiding the support right.

What is a Plugin?
A plug in is a piece of software that uses a hook. You can make a plug in for whatever (service, controller, library...) that there is a hook. Plugins extend functionalities.

How do I find the best hook for my Plugin
This really depends on every specific case, we have another article that shows how to find specific pieces of code in the script and its worth honing these skills. Once you found the exact function, controller or block you can start looking for a hook, there is usually at least one that will stand out and strike you as a good enough one but in some cases there may not be a hook near by, or the ones that you find are not suitable to your project, in those cases we encourage you to contact us via Feature Request, Support Ticket or to Purefan directly. We will add the hook where you need it and it will be available in the next version (which given our new development cycle shouldn't be more than a couple of months away).

Considerations when writing a Plugin
You have to remember that a plug in is going to be eval()'ed, this means that if you are coding a plug in for a hook inside a function in a Service (like the "add" function in the service user.process -> /module/user/include/service/process.class.php) and you want to return an error, you cannot do this in your plug in:
return Phpfox_Error::set('Any error'); 

This is due to a restriction in the PHP language (not the phpfox script), so for those cases the same applies, contact us and we will add a special case for this hook, so if a variable is defined then it would return your error.

Its also useful to know what you have at your disposal when coding a plug in, for example in Services you dont need to instantiate the Database library because its inherited from Phpfox_Service, so:
$oDb Phpfox::getLib('database');
$aRows $oDb->select... 

can be replaced for:
$aRows $this->database()->select... 

when the hook is inside a Service.

How to make a plugin
There are two ways, from the AdminCP and from a direct file.
If you go to the AdminCP -> Extensions -> Plug in -> Create New Plugin, you get fields for your product, the module and a list of hooks right from there. Creating a plugin from the adminCP lets site administrators disable specific hooks, and since they are tied to your Product you can also update plug ins as needed. This is the preferred method.

The second method (direct file) is a much rawer one, every module can have a plugins folder (/include/plugin/) and hold files that act like plugins, these files would be named after the hook, for example /module/mymodule/include/plugin/user.component_controller_photo_3.php
The code inside these files is direct PHP.
If you are coding a hook for a template you need to use "echo" or direct printing. This can however be paired to a special template, where the display logic is added to the template file and the control logic added from the Controller (via another hook).

Example Plugin
Lets suppose that you want to increase the views of a blog every time someone (no matter who) views a blog. For this you dig a little and you find the controller blog.view (/module/blog/include/component/controller/view.class.php).
You look at the code and see that it calls the service Blog (/module/blog/include/service/blog.class.php) to get the blog, so you open that Service and find the getBlog function, in here you find a couple of hooks but the last one in this function seems to be the better one because it already got the blog from the database:

You could then write a plugin similar to this:
if (isset($aRow['total_view']))
$this->database()->update($this->_sTable, array('total_view' => $aRow['total_view']+1), 'blog_id = ' $aRow['blog_id']);

(if you use a direct file make sure to include the <?php and ?> tags).
This would increase the view count no matter who is viewing the blog.