Lifecycle Hooks Schema

Via metadata lifecycle hooks, you can attach custom scripts to specific stages of Fusion's workflow. Each hook accepts a single PHP file reference. The path must be relative to the package root and start with a leading forward slash, for example:

{
    "lifecycle": {
        "<hook>": "</path/to/script.php>"
    }
}

Depending on the hook, the script is triggered either in the current state, which is the active set of packages used by the project, or in the next state, which Fusion builds in the operating system’s state directory before replacing the current state.

In addition to custom logic, the script can echo debug messages, trigger_error, and must return true if it performed any action, or false if nothing was done, such as:

// visible with debug threshold
echo "<debug log message>";

// abort if whatever and
// drop loggable error
if ($whatever)
    trigger_error("<message>", E_USER_ERROR);

// nothing done
return false;

After Copy Hook

The optional copy hook is triggered after Fusion has built the next common state in the operating system's state directory and the package has been recycled into that state (same package and version). To hook at this stage, specify in your metadata a PHP script relative to the package root with a leading slash, such as:

{
    "lifecycle": {
        "copy": "/lifecycle/copy.php"
    }
}

After Download Hook

The optional download hook is triggered after Fusion has built the next common state in the operating system's state directory and the package has been downloaded into that state, whether it is a new package or a new version. To hook at this stage, specify in your metadata a PHP script relative to the package root with a leading slash, such as:

{
    "lifecycle": {
        "download": "/lifecycle/download.php"
    }
}

After Install Hook

The optional install hook is triggered after Fusion has shifted the next common state from the operating system's state directory to the root package directory and the package has been downloaded into that state (new package or new version of a package). To hook at this stage, specify in your metadata a PHP script relative to the package root with a leading slash, such as:

{
    "lifecycle": {
        "install": "/lifecycle/install.php"
    }
}

After Update Hook

The optional update hook is triggered after Fusion has shifted the next common state from the operating system's state directory to the root package directory and the package has been recycled into that state with regenerated stateful files, or when these files were regenerated in the current state. To hook at this stage, specify in your metadata a PHP script relative to the package root with a leading slash, such as:

{
    "lifecycle": {
        "update": "/lifecycle/update.php"
    }
}

Before Migrate Hook

The optional migrate hook is triggered before Fusion stacks individual packages in the operating system's state directory into the next common state, when the current state contains the same package but a different version. To hook at this stage, specify in your metadata a PHP script relative to the package root with a leading slash, such as:

{
    "lifecycle": {
        "migrate": "/lifecycle/migrate.php"
    }
}

Fusion executes the script of the higher package version and passes variables containing information about the lower version:

$dir: absolute package directory in the next or current state
$version: lower inline version

During an upgrade, the higher package in its individual state (not yet merged into the next common state) in the operating system's state directory handles the migration. During a downgrade, the higher package in the current state handles the migration.

Before Delete Hook

The optional delete hook is triggered before Fusion removes a package from the current state. This occurs during cleanup when Fusion shifts the next common state from the operating system's state directory to the root package directory, or when a package has been removed from the metadata and Fusion regenerates the same state. To hook at this stage, specify in your metadata a PHP script relative to the package root with a leading slash, such as:

{
    "lifecycle": {
        "delete": "/lifecycle/delete.php"
    }
}