Information for: DEVELOPERS   PARTNERS

Hooks in Acquia Cloud Site Factory

ADVANCED – Invalid or poorly-tested hook scripts can cause data loss or downtime.

As you develop your Acquia Cloud Site Factory websites, you may have functions to perform during runtime, such as using Drupal core’s Fast 404 capabilities when your website begins to load. You may also want to perform actions after certain events, such as a theme deployment or website installation. You can achieve these goals by triggering code execution through Acquia Cloud Site Factory hooks.

Using Acquia Cloud hooks

Acquia Cloud Site Factory hooks differ from Acquia Cloud hooks. Because Acquia Cloud hooks are not designed for use with multisites, Acquia Cloud Site Factory does not support their use.

Acquia Cloud Site Factory supports only the hooks described on this page.

Available Acquia Cloud Site Factory hooks

Acquia Cloud Site Factory uses hooks of the following types to help you complete actions with your websites.

Hooks triggered after website actions

The following hooks are typically script files containing Drush commands, and can be any kind of executable script (including Bash or Ruby). For instructions on where to place hook scripts, see Executing your commands with a hook.

Acquia Cloud Site Factory does not provide hooks for website duplication, website staging, or website backups.

Hooks executed on every page load

When building standalone Drupal websites, you can alter your website’s sites.php or settings.php files. You cannot modify these files in Acquia Cloud Site Factory, so we have created hooks at the beginning and end of these files to check specific directories for custom code to run during your website’s bootstrap process:

  • sites.php
    • pre-sites-php – At the beginning of the file, before executing any instructions in sites.php
    • post-sites-php – At the end of the file
  • settings.php
    • pre-settings-php – At the beginning of the file, before executing any instructions in settings.php
    • post-settings-php – At the end of the file

For more information about pre-settings-php and post-settings-php hooks, including a script for monitoring website performance with New Relic, see Altering values in settings.php with hooks.

Important

  • Files executed by the settings.php and sites.php hooks must have a .php extension.
  • Because commands executed by these hooks run for every request for the web node, commands in the hook files must be lightweight (for example, setting variables) and must not read or write to either databases or files. Accessing databases or files using the hook file can greatly impair your website’s performance. If you must access databases or files, create modules instead.

Creating good hook scripts

You must thoroughly test all hook scripts before use, as a failed hook script will cause hosting tasks to fail for your entire environment, not only the individual website the hook script was executed against. Note the following factors when you create and name your custom hook scripts:

  • Hook scripts must take responsibility for their own errors
    Hook scripts must log failures internally and return a SUCCESS (exit code 0) status, even if portions of the script fail, unless you want the failure of your hook script to trigger failures on all hosting tasks, such as website staging and code deployments.
  • Hook scripts must be multisite-aware
    Any hook script executed on Acquia Cloud Site Factory must take into account the implications of execution in a multisite environment.
  • Hook scripts run in alphabetical order
    Hook scripts run in ASCII alphabetical order (the numbers 0 through 9, followed by a through z) by file name. Acquia recommends you prefix your hook scripts with a two-digit number (such as 03) to control the execution order of your hook scripts.

Executing your commands with a hook

After you have created one or more files with the commands you want to run, complete the following steps:

  1. Ensure you have created a directory called factory-hooks at the root of your code repository.

    Note

    The factory-hooks directory and your docroot are separate directories at the same level in your code repository.

  2. In the factory-hooks directory, ensure you have created a directory for the Acquia Cloud Site Factory hook you want to use (for example, post-settings-php or post-install).

  3. In the directory for the hook you want to use, add one or more of the previously created files which contain the required commands. Hook scripts will run in alphabetical order.

    For example, to execute a PHP file named action.php using the post-settings-php hook, using the following path and file name:

    factory-hooks/post-settings-php/action.php
    
  4. For hooks triggered after website actions, ensure any scripts you create have the executable bit set when you add them to your code repository. To set the executable bit for files already in your code repository, execute commands like the following from a command prompt window (where my-hook.sh is the file for which you want to set the executable bit):

    chmod a+x ./my-hook.sh
    git add ./my-hook.sh
    git commit -m 'Add executable bit to my-hook.sh'
    git push
    

Directory structure example

Code repository contents

+ docroot
+ factory-hooks
  + db-update
  + pre-sites-php
  + post-sites-php
  + pre-settings-php
  + post-settings-php
    + action.php
  + post-staging-update
  + post-theme-deploy
  + post-install