Site Factory
Hooks in Site Factory
ADVANCED: Invalid or poorly tested hook scripts can cause data loss or downtime.
As you develop your 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 deploying a theme or installing a website. You can achieve these goals by triggering code execution through Site Factory hooks.
Site Factory hooks differ from Cloud Platform hooks. Cloud Platform hooks aren’t designed for use with multisites, and Site Factory doesn’t support their use.
Site Factory supports only the hooks described on this page.
Site Factory uses hooks of the following types to help you complete actions with your websites.
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.
db-update: Executes scripts before and after the drush updatedb
command. For more information, see
Overriding the Drush updatedb command.
post-site-install: Executes scripts after a website has completed
installation. The post-site-install hook implementations have the
following arguments: sitegroup, environment, database role, and
domain. For more information, see Hook arguments. All scripts
are run once.
post-site-duplication: Executes scripts after a website has completed
duplication. The post-site-duplication hook implementations have the
following arguments: sitegroup, environment,
destination database role, destination domain,
source database role, and source domain. For more information,
see Hook arguments.
post-staging-update: Executes scripts after .
For more information, see
.
Site Factory doesn’t provide hooks for website staging or website backups.
When building standalone Drupal websites, you can alter your website’s
sites.php or settings.php files, but you can’t change these files in
Site Factory. Acquia has 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.
Files executed by the settings.php and sites.php hooks must have
a .php extension.
Commands executed by these hooks run for every request, so 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.
The hook implementations have the following arguments:
Sitegroup: Acquia’s hosting sitegroup/application.
Environment: Acquia’s hosting environment, for example, 01live.
Database role: A unique identifier for Site Factory websites.
Domain: Represents (Acquia managed) domain name of the website. For
example, in the URL mysite.demo.acsitefactory.com, the first part mysite
represents the name that’s unique for each installed website.
If you delete a website and recreate it with the same name, it get’s a different database role (unique identifier).
You must thoroughly test all hook scripts before use. 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 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.
After you have created one or more files with the commands you want to run, complete the following steps:
Ensure you have created a directory called factory-hooks at the root of
your code repository.
The factory-hooks directory and your docroot directory are separate directories at
the same level in your code repository.
In the factory-hooks directory, ensure you have created a directory for
the Site Factory hook you want to use (for example,
post-settings-php or post-site-install).
In the directory for the hook you want to use, add one or more of the files containing 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:
Site Factoryfactory-hooks/post-settings-php/action.phpFor 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):
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-theme-deploy-failure
+ post-site-installpost-theme-deploy: Executes code when you refresh a theme from an
external repository. For more information, see Refreshing your theme.
post-theme-deploy-failure: Executes code when a theme refresh from an
external repository has failed.
post-site-update: Executes scripts for each site after a site update
occurs. This hook is available only for Site Studio users. For most
use cases, the db-update hook
is the preferred way to extend the deployment process. For more information,
see post-site-update hook in Site Factory.
chmod a+x ./my-hook.sh
git add ./my-hook.sh
git commit -m 'Add executable bit to my-hook.sh'
git pushIf this content did not answer your questions, try searching or contacting our support team for further assistance.
post-theme-deploy: Executes code when you refresh a theme from an
external repository. For more information, see Refreshing your theme.
post-theme-deploy-failure: Executes code when a theme refresh from an
external repository has failed.
post-site-update: Executes scripts for each site after a site update
occurs. This hook is available only for Site Studio users. For most
use cases, the db-update hook
is the preferred way to extend the deployment process. For more information,
see post-site-update hook in Site Factory.
chmod a+x ./my-hook.sh
git add ./my-hook.sh
git commit -m 'Add executable bit to my-hook.sh'
git pushIf this content did not answer your questions, try searching or contacting our support team for further assistance.