This class is a major part of SnowCMS, it allows plugins (or flakes) to use hooks in various places which allow the plugins to add new features, or change how current features work as well.
| API | This class is a major part of SnowCMS, it allows plugins (or flakes) to use hooks in various places which allow the plugins to add new features, or change how current features work as well. |
| Variables | |
| hooks | Contains all the registered hooks to the specified actions. |
| filters | Contains all the registered filters to the specified tags. |
| count | Keeps track of how many hooks and filters are registered. |
| events | All query string events are kept here. |
| groups | All the registered groups reside here. |
| menu | |
| classes | Holds registered classes, which are not located within the core directory. |
| objects | |
| plugins | Currently enabled plugins are held in this array. |
| resources | A resource is something such as an image, style sheet, or anything, really. |
| context | An array containing information which is used within the context of the current page. |
| linktree | An array which contains the current link tree. |
| Functions | |
| __construct | Sets all attributes to empty arrays and what not. |
| add_hook | Adds a hook to be ran once the specified action occurs. |
| remove_hook | Removes the hook from the specified action. |
| run_hooks | Runs the hooks which are registered to the specified action. |
| hook_exists | Checks to see if the (or there are) hook(s) is registered for the specified action. |
| sort | Sorts the supplied array by the importance key, using the insertion using the insertion sort algorithm. |
| add_filter | Adds a filter to the specified tag, which when the tag is ran, the filter callback is passed the tag value. |
| remove_filter | Removes the filter from the specified tag. |
| apply_filters | Applies all the filters registered to the specified tag. |
| filter_exists | Checks to see if the filter is registered with the specified tag. |
| add_event | Adds a query string event with a callback to be executed once the event occurs. |
| remove_event | Removes the specified event. |
| return_event | Returns a registered events information according to the query string supplied. |
| event_exists | Checks to see if the specified event exists. |
| parse_query | Parses the specified query into an array. |
| return_linktree | Returns an array containing event identifiers. |
| add_group | Adds a group which can be assigned to members, which can be used by plugins for permission checking with member()->is_a(‘group_identifier’); |
| remove_group | Removes the specified group from the list of registered groups. |
| group_exists | Checks to see if the specified group exists. |
| return_group | Returns either the group name, or an array of all the registered groups. |
| add_menu_item | Adds a link to the menu. |
| remove_menu_item | Removes the specified menu item(s) by key. |
| return_menu_items | Returns the menu items requested. |
| add_class | Registers a class in the API to allow the class to be loaded with API::load_class without needing to specify the classes file location if the class file is not located within the core directory. |
| remove_class | Removes the specified class from the list of registered classes. |
| class_exists | Checks to see whether or not the specified class is registered. |
| load_class | Loads the specified class and returns the object. |
| add_plugin | Adds an enabled plugin to the list of, you guessed it, enabled plugins! |
| remove_plugin | Removes the specified plugin from the list of enabled plugins. |
| plugin_exists | Checks to see if the specified plugin is enabled. |
| return_plugins | Returns an array of the plugin GUID’s which are currently enabled and have been loaded. |
| add_resource | Adds a resource which will then become accessible to those browsing the current website. |
| remove_resource | Removes the supplied resource. |
| resource_exists | Checks to see if the specified resource (or resource handler) exists. |
| return_resource | Returns the resource information. |
| load_api | Instantiates an instance of the API class, and also loads all enabled plugins. |
| api_catch_fatal | Just incase somethings goes horribly wrong with a plugin (a fatal error), this function will handle the disabling of the plugin, and refreshing the page so it appears as it never happened! |
| api_handle_resource | Handles the displaying of registered resources. |
| api | Returns the API object. |
| hooks | Contains all the registered hooks to the specified actions. |
| filters | Contains all the registered filters to the specified tags. |
| count | Keeps track of how many hooks and filters are registered. |
| events | All query string events are kept here. |
| groups | All the registered groups reside here. |
| menu | |
| classes | Holds registered classes, which are not located within the core directory. |
| objects | |
| plugins | Currently enabled plugins are held in this array. |
| resources | A resource is something such as an image, style sheet, or anything, really. |
| context | An array containing information which is used within the context of the current page. |
| linktree | An array which contains the current link tree. |
| __construct | Sets all attributes to empty arrays and what not. |
| add_hook | Adds a hook to be ran once the specified action occurs. |
| remove_hook | Removes the hook from the specified action. |
| run_hooks | Runs the hooks which are registered to the specified action. |
| hook_exists | Checks to see if the (or there are) hook(s) is registered for the specified action. |
| sort | Sorts the supplied array by the importance key, using the insertion using the insertion sort algorithm. |
| add_filter | Adds a filter to the specified tag, which when the tag is ran, the filter callback is passed the tag value. |
| remove_filter | Removes the filter from the specified tag. |
| apply_filters | Applies all the filters registered to the specified tag. |
| filter_exists | Checks to see if the filter is registered with the specified tag. |
| add_event | Adds a query string event with a callback to be executed once the event occurs. |
| remove_event | Removes the specified event. |
| return_event | Returns a registered events information according to the query string supplied. |
| event_exists | Checks to see if the specified event exists. |
| parse_query | Parses the specified query into an array. |
| return_linktree | Returns an array containing event identifiers. |
| add_group | Adds a group which can be assigned to members, which can be used by plugins for permission checking with member()->is_a(‘group_identifier’); |
| remove_group | Removes the specified group from the list of registered groups. |
| group_exists | Checks to see if the specified group exists. |
| return_group | Returns either the group name, or an array of all the registered groups. |
| add_menu_item | Adds a link to the menu. |
| remove_menu_item | Removes the specified menu item(s) by key. |
| return_menu_items | Returns the menu items requested. |
| add_class | Registers a class in the API to allow the class to be loaded with API::load_class without needing to specify the classes file location if the class file is not located within the core directory. |
| remove_class | Removes the specified class from the list of registered classes. |
| class_exists | Checks to see whether or not the specified class is registered. |
| load_class | Loads the specified class and returns the object. |
| add_plugin | Adds an enabled plugin to the list of, you guessed it, enabled plugins! |
| remove_plugin | Removes the specified plugin from the list of enabled plugins. |
| plugin_exists | Checks to see if the specified plugin is enabled. |
| return_plugins | Returns an array of the plugin GUID’s which are currently enabled and have been loaded. |
| add_resource | Adds a resource which will then become accessible to those browsing the current website. |
| remove_resource | Removes the supplied resource. |
| resource_exists | Checks to see if the specified resource (or resource handler) exists. |
| return_resource | Returns the resource information. |
| load_api | Instantiates an instance of the API class, and also loads all enabled plugins. |
| api_catch_fatal | Just incase somethings goes horribly wrong with a plugin (a fatal error), this function will handle the disabling of the plugin, and refreshing the page so it appears as it never happened! |
| api_handle_resource | Handles the displaying of registered resources. |
| api | Returns the API object. |
public function add_hook( $action_name, $callback, $importance = 10, $accepted_args = null )
Adds a hook to be ran once the specified action occurs.
| string $action_name | The action to attach the hook to. |
| callback $callback | The callback to have ran once the action occurs. |
| int $importance | Allows you to set when your hook is ran, compared to others hooks added to the same action. The smaller the number the more important the hook is. |
| int $accepted_args | The number of arguments your hook expects to receive from the action, if any. If you keep this to the default (null), all available arguments will be passed. |
| bool | Returns true if the hook was added successfully, false if the hook already exists, or if the callback was not callable. |
If you supply accepted args as a large number than is actually passed by the specified action, the parameters that are “out of range” will receive null.
public function remove_hook( $action_name, $callback )
Removes the hook from the specified action.
| string $action_name | The name of the action to remove the hook from. |
| callback $callback | The callback of the hook to remove from the action. |
| bool | Returns true if the hook was removed successfully, false if the hook was not found. |
public function run_hooks( $action_name, $args = null )
Runs the hooks which are registered to the specified action.
| string $action_name | The action to run. |
| mixed $args | Either a single argument, or an array of arguments. |
| void | Nothing is returned by this method. |
If you want to allow hooks to change the value of a variable, you must pass the variable as a reference inside an array, otherwise you will receive an E_DEPRECATED error!
public function hook_exists( $action_name, $callback = null )
Checks to see if the (or there are) hook(s) is registered for the specified action.
| string $action_name | The action to search for the hook. |
| callback $callback | The callback to find (optional). |
| bool | If callback is set it returns true if the hook is registered to the specified action, false if the hook was not found. Otherwise the method will return true if there are hooks registered for the specified action and false if not. |
private function sort( & $array )
Sorts the supplied array by the importance key, using the insertion using the insertion sort algorithm. Used to sort hooks and filters.
| array &$array | The array to sort by the importance key. |
| void | Nothing is returned by this method. |
Original function available at http://www.todayinwindows.com
public function add_filter( $tag_name, $callback, $importance = 10 )
Adds a filter to the specified tag, which when the tag is ran, the filter callback is passed the tag value.
| string $tag_name | The tag to add the filter to. |
| mixed $callback | The filter callback, however, this can also be a string, integer, double, etc. That way if you do not need to receive the value of the filter, and you just want to set a new value regardless! |
| int $importance | The importance of this filter compared to other filters added to the same tag. The lower the number, the sooner the filter is ran. |
| bool | Returns true if the filter is added successfully, false if not. |
public function add_event( $query_string, $callback, $identifier, $filename = null )
Adds a query string event with a callback to be executed once the event occurs.
| string $query_string | The query string that should be matched in order to execute the supplied callback. |
| callback $callback | The callback to associate with the event. |
| mixed $identifier | An identifier used when generating a link tree, which can either be a string or a callback which will return a string. |
| string $filename | The file which is included before the callback is executed. Not required unless the callback is not currently callable. |
| bool | Returns true if the event was added successfully, false if the event already exists. |
What is an event? Say you want to have doMyAwesomeThing function called when someone accesses $base_url/index.php?action=awesome, you would supply action=awesome as the query string. Previously, SnowCMS had separate methods to do such a thing with actions, sub actions, and request parameters, but now all of that is handled via events.
You can also specify wild cards, say you want to have blog_view_article called when $base_url/index.php?blog={Some ID}, your query string would be blog=* and whatever the value of blog is, it will be passed as a parameter, as is.
This also allows the ability to do such things as action=someExisting&another=action, what will occur is if the whole query string is not found, the last part of the query string is chopped off (in this case, &another=action) and another check would occur with just action=someExisting, and if it was found, the callback would be executed.
All callbacks are expected to return a boolean value, true if everything was done as should, false, if for some reason, everything was not properly executed. If the function does return false, the next callback (the one below it, with the last bit of the query string chopped off) would be executed.
Also note that you cannot add an event such as blog=* and then add another event called blog=help, this would cause an already exists error. Same goes for the other way around, if blog=help were added, then blog=* were added, an error would occur.
DO NOT URL encode the query string, and also DO NOT use & as a separator, you must use just &.
Query strings are CASE SENSITIVE! so action=something is not the same as Action=something!
public function return_event( $query_string, $generate_link_tree = false )
Returns a registered events information according to the query string supplied. The best matching event will be returned.
| string $query_string | The query string to get the event of. |
| bool $generate_link_tree | Whether to generate a link tree while parsing the query string. |
| array | Returns an array containing the callback, false on failure to find a match. |
public function add_group( $group_identifier, $group_name )
Adds a group which can be assigned to members, which can be used by plugins for permission checking with member()->is_a(‘group_identifier’);
| string $group_identifier | The groups identifier, which is stored in the members database, an example for a page manager would be page_manager. |
| string $group_name | The label for the group. Such as Page manager, which should be passed through the l() function before using it in this method. |
| bool | Returns true if the group was added successfully, false if not. |
public function return_group( $group_identifier = null )
Returns either the group name, or an array of all the registered groups.
| string $group_identifier | The group identifier to have the name returned. |
| mixed | Returns a string containing the groups name if the group identifier was specified, and false if the group identifier was not found. If the group identifier was omitted, then all groups, in an associative array (group_identifier => group_name) is returned. |
public function add_menu_item( $category, $options )
Adds a link to the menu.
| string $category | The category of where the link will be in. |
| array $options | An array containing the links options. |
| bool | Returns true if the link is added successfully, false if not. |
The following indexes are supported for the $options parameter: href - The destination (URL) of the link.
| name | The name of the anchor to link to (if href supplied, this is ignored, and vice versa). |
| rel | Specifies the relationship between the current document and the one it is linking to. For example, if nofollow was supplied, then bots (Google, Bing, etc.) will not follow the link (well, they will, but it won’t help them). |
| class | Specifies a CSS class name(s) for the link. |
| id | A unique HTML id for the tag. |
| style | Inline styling. |
| title | A mouseover text. |
| content | The actual content between the tags which is linked. |
| extra | Any extra information (which could be a string, array, etc). |
| position | A number (starting at zero), specifying at which position the link should be inserted at in the list. If 0 is supplied, the link will be placed in the front, if none supplied, the link will be added to the end. Please note that when links are retrieved they are not sorted by this number, they are sorted once it is added. So if you add two links at position 0, the first link will be second and the next will be first. |
By the way. In order to add a link to the admin menu, simply set the category as action=admin. To put the link into a category, simply supply the categories label in the extra field as a string, if it doesn’t exist, it will be created.
public function remove_menu_item( $search, $category = null, $index = 'content', $case_sensitive = false )
Removes the specified menu item(s) by key.
| string $search | The value of which you are searching for, if found, it will be deleted. |
| string $category | The category to search. If none supplied, all categories will be searched. |
| string $index | The index you want to search by, either href, name, rel, class, id, style, title or content. Defaults to content. |
| bool $case_sensitive | Whether or not the search is case sensitive. |
| int | Returns the number of menu items removed. |
public function return_menu_items( $category = null )
Returns the menu items requested.
| string $category | The category of links to return, if any. |
| array | Returns an array containing the links, false if the category does not exist. |
If the $category parameter is not supplied (null), then the whole menu attribute is returned, containing an array who’s initial indexes specify the category the links are in, however, if false, all the links will be congregated into one array.
public function add_class( $class, $filename )
Registers a class in the API to allow the class to be loaded with API::load_class without needing to specify the classes file location if the class file is not located within the core directory.
| string $class | The name of the class in the file. |
| string $filename | The name of the file the class is located in. |
| bool | Returns true on success, false if the class already exists. |
public function load_class( $class_name, $params = array(), $filename = null, $new = false )
Loads the specified class and returns the object. If the new parameter is set to false, then the same object can be obtained through loading the same class by calling on this method again.
| string $class_name | The name of the class to load. |
| array $params | An array of parameters you want to pass to the __construct method once the class has been instantiated. |
| string $filename | The name of the where the class is defined, if the file is not specified, then coredir/lower($class_name).class.php is assumed. |
| bool $new | If set to true, a new and private object will be returned, if false, a reference will be stored in the API class which can be obtained later by loading the same class. |
| object | Returns the instantiated object of the specified class, however, if the file was not found or the class did not exist, false is returned. |
public function add_resource( $area_name, $resource_id, $location )
Adds a resource which will then become accessible to those browsing the current website. The idea of a resource is to allow plugins to have images, style sheets, JavaScript files, etc. and then instead of the plugins needing to figure out their location on the server in order to serve that resource directly, the API can handle that for them.
| string $area_name | The area under which to add the resource to, so say your plugin is a blog, you would, ideally, supply the area name as blog, or something close to that. |
| string $resource_id | An identifier for the resource, for example, if you are adding an icon which symbolizes adding a new blog post, ideally, the resource identifier would be blog_add or so. This can be left blank only if the location parameter is a callback, which would allow you to handle resource viewing yourself. |
| mixed $location | This can either be a callback, in which case the viewing of resources will be handled by the callback, and the callback will be invoked when the area is requested. However, this can also be a path to a file, of any kind, such as an image. The supplied path must exist, otherwise adding the resource will fail. |
| bool | Returns true if the resource was added successfully, false if not. |
Resources can be accessed via:
{$base_url}/index.php?action=resource&area={$area_name}&id={$resource_id}
That is of course if a resource identifier is supplied, if not then the “&id={$resource_id}” can be changed to anything.
Also note that area names are internally lowercased, however resource identifiers are not!
public function remove_resource( $area_name, $resource_id = null )
Removes the supplied resource.
| string $area_name | The area to remove the resource from. |
| string $resource_id | The resource to remove, if you want to remove all resources from the supplied area, or if the area is a callback, leave this set to null. |
| bool | Returns true on success, false on failure. |
public function resource_exists( $area_name, $resource_id )
Checks to see if the specified resource (or resource handler) exists.
| string $area_name | The name of the area to check. |
| string $resource_id | The resources identifier to check the existence of. |
| bool | Returns true if the resource exists, false if not. |
public function return_resource( $area_name, $resource_id = null )
Returns the resource information.
| string $area_name | The name of the area which contains the resource. |
| string $resource_id | The identifier for the specific resource. |
| mixed | Returns a string containing the path to the resource, or a callback which will handle the entire resource area, or an array containing all the resources in the specified area if the area is not handled by a callback OR false if the area or resource identifier does not exist. |
Contains all the registered hooks to the specified actions.
private $hooks
Contains all the registered filters to the specified tags.
private $filters
Keeps track of how many hooks and filters are registered.
private $count
All query string events are kept here.
private $events
All the registered groups reside here.
private $groups
private $menu
Holds registered classes, which are not located within the core directory.
private $classes
private $objects
Currently enabled plugins are held in this array.
private $plugins
A resource is something such as an image, style sheet, or anything, really.
private $resources
An array containing information which is used within the context of the current page.
public $context
An array which contains the current link tree.
private $linktree
Sets all attributes to empty arrays and what not.
public function __construct()
Adds a hook to be ran once the specified action occurs.
public function add_hook( $action_name, $callback, $importance = 10, $accepted_args = null )
Removes the hook from the specified action.
public function remove_hook( $action_name, $callback )
Runs the hooks which are registered to the specified action.
public function run_hooks( $action_name, $args = null )
Checks to see if the (or there are) hook(s) is registered for the specified action.
public function hook_exists( $action_name, $callback = null )
Sorts the supplied array by the importance key, using the insertion using the insertion sort algorithm.
private function sort( & $array )
Adds a filter to the specified tag, which when the tag is ran, the filter callback is passed the tag value.
public function add_filter( $tag_name, $callback, $importance = 10 )
Removes the filter from the specified tag.
public function remove_filter( $tag_name, $callback )
Applies all the filters registered to the specified tag.
public function apply_filters( $tag_name, $value )
Checks to see if the filter is registered with the specified tag.
public function filter_exists( $tag_name, $callback )
Adds a query string event with a callback to be executed once the event occurs.
public function add_event( $query_string, $callback, $identifier, $filename = null )
Removes the specified event.
public function remove_event( $query_string )
Returns a registered events information according to the query string supplied.
public function return_event( $query_string, $generate_link_tree = false )
Checks to see if the specified event exists.
public function event_exists( $query_string )
Parses the specified query into an array.
private function parse_query( $query_string )
Returns an array containing event identifiers.
public function return_linktree()
Adds a group which can be assigned to members, which can be used by plugins for permission checking with member()->is_a(‘group_identifier’);
public function add_group( $group_identifier, $group_name )
Removes the specified group from the list of registered groups.
public function remove_group( $group_identifier )
Checks to see if the specified group exists.
public function group_exists( $group_identifier )
Returns either the group name, or an array of all the registered groups.
public function return_group( $group_identifier = null )
Adds a link to the menu.
public function add_menu_item( $category, $options )
Removes the specified menu item(s) by key.
public function remove_menu_item( $search, $category = null, $index = 'content', $case_sensitive = false )
Returns the menu items requested.
public function return_menu_items( $category = null )
Registers a class in the API to allow the class to be loaded with API::load_class without needing to specify the classes file location if the class file is not located within the core directory.
public function add_class( $class, $filename )
Loads the specified class and returns the object.
public function load_class( $class_name, $params = array(), $filename = null, $new = false )
Removes the specified class from the list of registered classes.
public function remove_class( $class )
Checks to see whether or not the specified class is registered.
public function class_exists( $class )
Adds an enabled plugin to the list of, you guessed it, enabled plugins!
public function add_plugin( $guid )
Removes the specified plugin from the list of enabled plugins.
public function remove_plugin( $guid )
Checks to see if the specified plugin is enabled.
public function plugin_exists( $guid )
Returns an array of the plugin GUID’s which are currently enabled and have been loaded.
public function return_plugins()
Adds a resource which will then become accessible to those browsing the current website.
public function add_resource( $area_name, $resource_id, $location )
Removes the supplied resource.
public function remove_resource( $area_name, $resource_id = null )
Checks to see if the specified resource (or resource handler) exists.
public function resource_exists( $area_name, $resource_id )
Returns the resource information.
public function return_resource( $area_name, $resource_id = null )
Instantiates an instance of the API class, and also loads all enabled plugins.
function load_api()
Just incase somethings goes horribly wrong with a plugin (a fatal error), this function will handle the disabling of the plugin, and refreshing the page so it appears as it never happened!
function api_catch_fatal()
Handles the displaying of registered resources.
function api_handle_resource()
Returns the API object.
function api()