Action and filter hooks

• Introduction
• General hooks
  • Enabling debug mode
• Modifying the publication process
  • Run code before or after publication tasks
  • Adding or removing publication tasks
  • Adding or removing crawl URL providers
  • Adding or removing transformers
  • Adding or removing post processors
  • Replacing live URLs
  • Excluding URLs from processing
• Extending the plugin
  • Registering new deployment methods
  • Registering new settings

Introduction

WordPress hooks are places throughout the WordPress core, plugins, and themes that you can hook into and run your own code in order to improve or extend functionalities without having to edit the core source code. There are two types of hooks: action hooks and filter hooks.

• Filter hooks allow you to intercept and modify data while it is processed.
• Action hooks allow you to run code at specific points in a process.

The Staatic for WordPress plugin provides numerous action and filter hooks enabling developers to integrate with or even extend the Staatic plugin.

This page provides an overview of the most commonly used action and filter hooks as well as the arguments they take and their purpose.

General hooks

Enabling debug mode

staatic_debug

Allows the plugin’s debug mode to be enabled. When enabled this results in more detailed error messages as well as additional context information added to publication logs.

Arguments

1. bool $isDebug

Example usage

add_filter( 'staatic_debug', '__return_true' );

Modifying the publication process

Run code before or after publication tasks

staatic_publication_task_before

Triggered during the publication process, before a publication task (e.g. Staatic\WordPress\Publication\Task\CrawlTask) is executed.

Arguments

1. Staatic\WordPress\Publication\Publication $publication
2. Staatic\WordPress\Publication\Task\TaskInterface $task

staatic_publication_task_after

Triggered during the publication process, after a publication task (e.g. Staatic\WordPress\Publication\Task\CrawlTask) is executed.

Arguments

1. Staatic\WordPress\Publication\Publication $publication
2. Staatic\WordPress\Publication\Task\TaskInterface $task

Adding or removing publication tasks

staatic_publication_tasks

Allows additional publication tasks to be added or existing tasks to be removed from the list of publication tasks executed during a publication.

Publication tasks are responsible for a specific part of the publication process. Examples of publication tasks are:

• Staatic\WordPress\Publication\Task\SetupTask which ensures that required directories exist and the chosen deployment method has been configured correctly.
• Staatic\WordPress\Publication\Task\CrawlTask which crawls a set of crawl URLs from the crawl queue.
• Staatic\WordPress\Publication\Task\FinishTask which finalizes the publication process and updates the publication status.

Arguments

1. Staatic\WordPress\Publication\Task\TaskCollection $tasks

Adding or removing crawl URL providers

staatic_crawl_url_providers

Allows additional crawl URL providers to be added or existing providers to be removed from the list of crawl URL providers executed during a publication.

Crawl URL providers are used to provide the initial list of URLs to be crawled to the crawler component. Examples of crawl URL providers are:

• Staatic\Crawler\CrawlUrlProvider\EntryCrawlUrlProvider which provides the homepage URL.
• Staatic\Crawler\CrawlUrlProvider\PageNotFoundCrawlUrlProvider which provides the 404 page not found URL.
• Staatic\Crawler\CrawlUrlProvider\AdditionalUrlCrawlUrlProvider which provides a list of additional URLs.

Arguments

1. Staatic\Crawler\CrawlUrlProvider\CrawlUrlProviderCollection $providers
2. Staatic\WordPress\Publication\Publication $publication

Adding or removing transformers

staatic_transformers

Allows additional transformers to be added or existing transformers to be removed from the list of transformers executed during a publication.

Transformers are used to modify results while they are processed during a publication.

Arguments

1. Staatic\Framework\Transformer\TransformerInterface[] $transformers
2. Staatic\WordPress\Publication\Publication $publication

Adding or removing post processors

staatic_post_processors

Allows additional post-processors to be added or existing post-processors to be removed from the list of post-processors executed during a publication.

Post-processors are used to modify the build after the crawler process has finished crawling the site.

Arguments

1. Staatic\Framework\PostProcessor\PostProcessorInterface[] $postProcessors
2. Staatic\WordPress\Publication\Publication $publication

Replacing live URLs

staatic_replace_live_urls

This filter hook allows you to configure a list of live or production site URLs, which should be treated as if they were part of the current dynamic WordPress site during the publication process.

Arguments

1. array $value – An array of URLs to be treated as part of the current dynamic WordPress site.

Example usage

add_filter( 'staatic_replace_live_urls', function ( $value ) {
    return [
        'https://www.example.com',
        'https://www.otherexample.com',
    ];
} );

Excluding URLs from processing

staatic_should_crawl_url

Determines whether a specific URL should be excluded from being processed or transformed by the crawler based on the given context.

Before using this hook, enable extended URL context information with:

add_filter( 'staatic_extended_url_context', '__return_true' );

This provides extra context information, such as the HTML tag/attribute/surrounding code where the URL was found, allowing for more precise control over which URLs to exclude.

Arguments

1. bool $shouldCrawl
2. Staatic\Vendor\Psr\Http\Message\UriInterface $url
3. array $context

Example usage

add_filter( 'staatic_should_crawl_url' , function ( $value, $url, $context ) {
    if ( ( $context[ 'htmlTagName' ] ?? '' ) === 'link' &&
        ( $context[ 'htmlAttributeName' ] ?? '' ) === 'href' &&
        ( str_contains( $context[ 'htmlElement' ] ?? '', 'canonical' ) ) ) {
        return false;
    }

    return $value;
}, 10, 3 );

Extending the plugin

Registering new deployment methods

In order to register a new deployment method you will need to create a new class that implements Staatic\Framework\DeployStrategy\DeployStrategyInterface. This class can then be registered using the staatic_deployment_strategy hook described below.

staatic_deployment_strategy

Determines the active deployment method that is used during the publication process.

Arguments

1. Staatic\Framework\DeployStrategyInterface $deployStrategy
2. Staatic\WordPress\Publication\Publication $publication

staatic_deployment_strategy_supports_preview

Determines whether the active deployment method supports preview publications.

Arguments

1. bool $supportsPreviewPublications

staatic_deployment_strategy_validate

Returns validation errors related to the the active deployment method that should prevent the publication process from starting.

Arguments

1. string[] $errors
2. Staatic\WordPress\Publication\Publication $publication

Registering new settings

In order to register a new setting to be displayed in the Staatic for WordPress plugin interface, you will need to create a class that implements Staatic\WordPress\Setting\SettingInterface and register it using the staatic_settings hook described below.

staatic_settings

Allows additional settings to be added or existing settings to be removed from the list of registered settings.

Arguments

1. array<string, Staatic\WordPress\Setting\SettingInterface> $settings

staatic_setting_groups

Allows additional setting groups to be added or existing groups to be removed from the list of registered setting groups.

Arguments

1. Staatic\WordPress\SettingGroup\SettingGroup[] $settingGroups