-
-
Notifications
You must be signed in to change notification settings - Fork 18
Hooks
CE Phoenix uses hooks to allow App writers to insert their own behaviors (i.e. code) into the application flow.
There are several overlapping ways to categorize hooks.
Hooks can be loaded in the admin area or in the shop. Both file and database hooks respect this division. To load a hook in both places requires two entries.
Hooks are grouped together underneath the site. In the admin area, we currently only use siteWide and page groups. But in the shop, we use many more types of group.
For hooks that should run on every page on the site.
For hooks that should only run on a specific page. These hooks are named based on the page name, which is the file name without the .php at the end. For example, we might talk about index, product_info, create_account, or checkout_shipping hooks.
Pipeline hooks group multiple pages into one group. For example, all pages where login is required are in the loginRequired pipeline. And the pages of checkout are in the checkout pipeline.
All the other hook groups are combined into one on the page. System hooks run before that process is started (in fact, starting it is itself a system hook). The system hooks run immediately after the hooks object is instantiated. They load the function files and application segments and instantiate the necessary session and other global objects.
Stage hooks are for pipelines through which one progresses, like checkout. One can meaningfully say, after shipping, payment, or confirmation while progressing through the checkout pipeline. So there are stages for each level during checkout. These are used to enforce different requirements at each stage. For example, after the checkout_shipping_stage, it is required that shipping be set in the session (to false if only virtual products were purchased).
Hooks are put in a specified place. All files are loaded from those places. By default, this includes the includes/hooks directory and the templates/default/includes/hooks directory. The hook class name is determined by the location under the hooks directory. For example, includes/hooks/shop/siteWide/name.php will be expected to have a class named hook_shop_siteWide_name in it.
Some hooks are specific to a particular template. These are always file-based hooks and they appear under the templates/name/includes/hooks directory (replace "name" with the actual name of the template). If a template inherits from another template, it will typically override the parent template's hooks if there are any with the same name. Warning: note that that behavior is set inside the template. A template does not necessarily need to follow it. For example, a template could decide not to inherit from any other templates. It is typical to inherit from default, but it is not required.
Hooks are entered into the database. If a database hook accesses a class that is not loaded, it will be autoloaded. Database hooks will override file hooks with the same name (what is called a hooks_code in the hooks table in the database).
Any instantiation required occurs at registration time. For system hooks, this occurs at the top of the application. The last thing that the core system hooks do is register the siteWide and page hooks. Pipelines are registered on an ad hoc basis. The only extant stage hooks are instantiated by the checkout pipeline.
Most hooks are instantiated as objects of the same name as the class. E.g. $hook_shop_siteWide_name for a file-based hook (all file-based hooks are object hooks).
If there exists a session variable with the same name as the hooks_class of a database hook, then that variable will be used instead of creating a global variable of that class. Intended for use with things like $_SESSION['navigation'] and $_SESSION['cart'].
If the hooks_class of a database hook is empty, then the code will try to call the hooks_method as a function without instantiating anything.
Most hooks echo any output returned, which must be in the form of strings (nulls are converted to empty strings and produce no output).
System hooks load during the initial application_top.php invocation. Currently all system hooks in core are database hooks, but App developers may choose to implement system hooks as file hooks.
The system hooks may return strings or arrays of strings. These are treated as file paths and required. Non-strings are ignored.