You can extend IceBear's behaviour by adding PHP scripts to this directory. Actions can be performed before or after a
"create", "update" or "delete" API call.

Files
-----

Hook files are PHP files and hence must begin <?php

Filenames are in the format objecttype_when_action.php, where

* objecttype is the class name, typically the part after /api/ in the URL
* when is either "before" or "after"
* action is "create", "update" or "delete"

for example, dropimage_after_update.php

You can have multiple hook files. They will be executed in the following order:

- dropimage_after_update.php
- dropimage_after_update_1.php
- dropimage_after_update_2.php
- dropimage_after_update_3.php
...etc.

Note that the numbering must start from 1 and must be consecutive. If there is a gap in the numbering, all files after
that gap will be ignored.

Arguments
---------
Within hook files, you have access to the $args variable, which contains arguments relevant to the action being
performed:

For before-create hooks,
    $args['request'] is the array of HTTP POST parameters
For after-create hooks,
    $args['created'] is the created item
    $args['id'] is the ID of the created item
For before-update hooks,
    $args['request'] is the array of HTTP PATCH parameters
    $args['id'] is the ID of the item to update
For after-update hooks,
    $args['updated'] is the updated item
    $args['id'] is the ID of the updated item
For before-delete hooks:
    $args['toDelete'] is the item that will be deleted
    $args['id'] is the ID of the item to delete
For after-delete hooks:
    $args['deleted'] is the item that was deleted
    $args['id'] is the ID of the deleted item

Note that, in the case of after-delete hooks, the 'deleted' argument may well contain related IDs that no longer exist.

Linux permissions
-----------------

Hook files are included by PHP include() and hence run with the permissions of the webserver user. Ensure that this
user has the correct permissions for any filesystem actions performed within the hook file.

IceBear permissions
-------------------

Because the API class/method call is mostly responsible for authorisation, it is recommended to use the "after" hooks
wherever possible. If the action is not authorised, an exception will be thrown and the "after" hook will not be run -
but the "before" hook WILL be run. Consider the possible consequences of this when using "before" hooks.

By default, the hooks run with the permissions of the currently logged-in IceBear user. Judicious use of the
session::becomeAdmin() and session::revertAdmin() methods allows you to override these permissions. Ensure that you
call session::revertAdmin() as soon as you no longer require the admin permissions.

Errors/rollback
---------------

Should you need to throw an exception, throw a ServerException. This will result in an HTTP 500 status code being
returned to the user.

Should the hook files or the API call throw an exception, the database transaction will be aborted and rolled back.
However, other actions (filesystem, etc.) will NOT be rolled back automatically.

