API / Hooks / addHook

Adding hooks to jCore is pretty easy and you can do that to 90%+ methods of all the classes found in jCore. There are different ways of adding hooks to the system and each gives you even more control of the whole system.

Simple Hook (API_HOOK_AFTER)

This hook will be called on the end of a function so you can append content to them or return a different result on functions like adding a new post and even make changes to the newly added post and so on.

api::addHook((string)$method, (string|object|array)$hook);

  • $method is a string like 'posts::display' or any other method that can be accessed from the API
  • $hook can be or a simple string of a function like 'testing_the_api' or 'class::static_method', it can also be an object like $obj = new MyNewClass(); and then $obj would be used as parameter, and it can be array too to call non static methods like array($obj, 'NonStaticClass')

Example 1

function my_api_function() {
    echo "Hello World!";
}

api::addHook('pages::display', 'my_api_function');

This will print out "Hello World!" on the bottom of every page.

Example 2

function my_api_function(&$env, &$post) {
    echo $post['Title'];
}

api::addHook('posts::displayOne', 'my_api_function');

This will print out the posts' title again on the bottom of the post.
$env is always referring to the class the hooked to method is in (for e.g. in this case to posts) and on static methods $env will be the value of $_ENV

Example 3

class myApiClass {
    static function helloOne() {
        echo "Hello One!";
    }
}

api::addHook('pages::display', 'myApiClass::helloOne');

Example 4

class myApiClass {
    function display() {
        echo "Hello Two!";
    }
}

$myapiclass = new myApiClass();
api::addHook('pages::display', $myapiclass);
unset($myapiclass);
 

In cases where you only define the object for the hook the default "display()" method will be called.

Example 5

class myApiClass {
    function helloTwo() {
        echo "Hello Two!";
    }
}

$myapiclass = new myApiClass();
api::addHook('pages::display', array($myapiclass, 'helloTwo'));
unset($myapiclass);
 

Hook Before (API_HOOK_BEFORE)

This type of hook will allow you to run your code before the hooked to method is run so it gives you the possibility to update the methods arguments or echo out your own content before the original content.

api::addHook(API_HOOK_BEFORE, (string)$method, (string|object|array)$hook);

  • $method and $hook arguments are the same as in normal hooks
  • if your hook returns non null value the hooked to method won't continue and return with your result

Example 1

function my_api_function() {
    echo "Hello World!";
}

api::addHook(API_HOOK_BEFORE, 'pages::display', 'my_api_function');

This will display "Hello World!" on the top of every page.

Example 2

function my_api_function() {
    echo "Hello World!";
    return true;
}

api::addHook(API_HOOK_BEFORE, 'pages::display', 'my_api_function');

This will not just simply echo out "Hello World!" on the top of every page but it will replace every page with the "Hello World!" content. The reason for this is that this way you can implement your own way of displaying the pages without having the original pages::display to run it's content so you save resources and your page will load a lot faster.

Example 3

function my_api_function(&$env, &$post) {
    $post['Title'] = "Hello World! - ".$post['Title'];
}

api::addHook(API_HOOK_BEFORE, 'posts::displayOne', 'my_api_function');

All hooks will receive the same function arguments as the hooked to method receives this way allowing you to change the variables to your needs. For e.g. this example will add "Hello World!" to the front of every post title.

Example 4

function my_api_function(&$env) {
    $env->limit = 1;
}

api::addHook(API_HOOK_BEFORE, 'posts::display', 'my_api_function');

This example uses the $env variable to poing to the hooked to methods class and this way it can access all it's variables for e.g. in this case it will limit the posts to display one per page.

Hook Return (API_HOOK_RETURN)

This type of hook allows you to retrive the content of a method (as string) and then replace a part of it with your own content for e.g. by using str_replace or preg_replace.

api::addHook(API_HOOK_RETURN, (string)$method, (string|object|array)$hook);

  • $method and $hook arguments are the same as usuall
  • IMPORTANT: in your hooks the first argument will be the $content generated by the method and the $env will be the second argument

Example 1

function my_api_function($content, &$env, &$post) {
    $content = preg_replace('/<img.*?>/i'. '', $content);
    echo $content;
}

api::addHook(API_HOOK_RETURN, 'posts::displayOne', 'my_api_function');

This example will strip out all img tags from a post this way removing all images from a post. As you can see it is up to you to echo out the content once you have handled it and also you can use the $post too for your needs.

With this hook you can also totally rewrite one methods content but in those cases it is really recommended to use the API_HOOK_BEFORE with return in your hook.