Extension hooks

Use these hooks when you are adding a reusable integration or changing one of Staatic’s extension points. If you only need a conditional crawl or URL rewrite decision, start with URL processing hooks instead.

Add crawl URL providers

staatic_crawl_url_providers

Filters the collection of crawl URL providers used to produce the initial crawl queue.

Use a provider when URLs need to be discovered from custom data, external APIs, plugin records, or another source that does not fit the Additional URLs setting.

Arguments:

Example:

use Staatic\Crawler\CrawlUrlProvider\AdditionalUrlCrawlUrlProvider;
use Staatic\Crawler\CrawlUrlProvider\AdditionalUrlCrawlUrlProvider\AdditionalUrl;
use Staatic\Crawler\CrawlUrlProvider\CrawlUrlProviderCollection;
use Staatic\WordPress\Publication\Publication;

add_filter( 'staatic_crawl_url_providers', function ( CrawlUrlProviderCollection $providers, Publication $publication ) {
    $providers->addProvider( new AdditionalUrlCrawlUrlProvider(
        [ new AdditionalUrl( 'https://www.example.com/special-page/' ) ],
        $publication->build()->entryUrl()
    ) );

    return $providers;
}, 10, 2 );

Crawl WordPress REST API links

staatic_exclude_discovered_rest_api_urls

Controls whether Staatic ignores the WordPress REST API links it discovers while crawling. Since 1.15.1, Staatic does not follow the REST API discovery link, the JSON links WordPress prints for posts, pages and terms, oEmbed links, language-prefixed copies such as /nl/wp-json/, and ?rest_route= URLs. REST API URLs listed in Additional URLs are still crawled. See WordPress REST API for why.

Return false to restore the previous behavior and follow these links again (subject to Excluded URLs, which exclude /wp-json/* by default).

Arguments:

Example:

add_filter( 'staatic_exclude_discovered_rest_api_urls', '__return_false' );

Add transformers

staatic_transformers

Filters the list of result transformers used while publication results are processed.

Transformers operate during result processing. Use them for systematic changes to generated resources, not for one-off URL decisions that can be handled by staatic_should_transform_url.

Arguments:

Example shape:

add_filter( 'staatic_transformers', function ( array $transformers, $publication ) {
    // $transformers[] = new MyCustomTransformer();
    return $transformers;
}, 10, 2 );

Add post-processors

staatic_post_processors

Filters the list of post-processors that run after crawling has finished.

Post-processors are a good fit for final build changes such as generated config files, redirects, duplicate cleanup, or deployment-target-specific files.

Arguments:

Example shape:

add_filter( 'staatic_post_processors', function ( array $postProcessors, $publication ) {
    // $postProcessors[] = new MyCustomPostProcessor();
    return $postProcessors;
}, 10, 2 );

Register deployment methods

Custom deployment methods usually need the three hooks in the table below.

For the complete workflow, including settings, validation, strategy lifecycle, preview support, and no-deploy methods, see Custom deployment methods.

Preview support can be enabled with staatic_deployment_strategy_supports_preview.

staatic_deployment_methods

Arguments:

Example:

add_filter( 'staatic_deployment_methods', function ( array $deploymentMethods ) {
    $deploymentMethods['custom'] = 'Custom';
    return $deploymentMethods;
} );

staatic_deployment_strategy

Arguments:

Return false only when deployment tasks are intentionally inactive. Otherwise return an object implementing Staatic\Framework\DeployStrategy\DeployStrategyInterface for the selected deployment method.

Example shape:

use Staatic\WordPress\Publication\Publication;

add_filter( 'staatic_deployment_strategy', function ( $deployStrategy, Publication $publication ) {
    if ( get_option( 'staatic_deployment_method' ) !== 'custom' ) {
        return $deployStrategy;
    }

    // return new MyCustomDeployStrategy( $publication );
    return $deployStrategy;
}, 10, 2 );

staatic_deployment_strategy_validate

Arguments:

Example:

add_filter( 'staatic_deployment_strategy_validate', function ( array $errors, $publication ) {
    if ( get_option( 'staatic_deployment_method' ) === 'custom' && ! get_option( 'staatic_custom_token' ) ) {
        $errors[] = 'Custom deployment token is missing.';
    }

    return $errors;
}, 10, 2 );

staatic_deployment_strategy_supports_preview

Arguments:

Register settings

staatic_settings

Filters the registered settings grouped by setting group name.

Arguments:

Example shape:

add_filter( 'staatic_settings', function ( array $settings ) {
    // $settings['staatic-deployment'][] = new MyCustomSetting();
    return $settings;
} );

staatic_setting_groups

Filters the registered settings groups.

Arguments:

Search integration

staatic_search_item

Filters the record Staatic Search indexes for a post. Use it when pages are built from templates, custom fields or post meta, so post_content is empty or holds editor notes and search cannot find those pages by the text visitors see. You can also add your own display fields under custom, for example a section label to show in the search widget. Requires Premium.

Staatic takes only post_title, post_content, post_excerpt and custom from the returned record. Return plain text in the first three: each value is cast to a string, HTML tags are stripped from post_content, and a missing or non-text value keeps Staatic’s own value. All other fields, such as _id, post_type, permalink, dates, author and thumbnail, stay as Staatic built them, and other fields you add at the top level are ignored. Links to your WordPress site in the returned text are rewritten to your static site, like the rest of the record. post_title and post_content are the searchable fields.

The filter runs when posts are indexed during a publication, so only posts changed since the last index pick it up. After adding or changing it, enable Force reindexing during next publication in Search integration so every record is rebuilt during the next publication.

Arguments:

Example:

add_filter( 'staatic_search_item', function ( array $item, WP_Post $post ) {
    if ( $post->post_type === 'page' ) {
        $item['post_content'] = wp_strip_all_tags( (string) get_post_meta( $post->ID, 'page_text', true ) );
    }

    return $item;
}, 10, 2 );

Custom display fields

Put your own fields in $item['custom'], an array keyed by field name. They are stored with the record and returned with every search result, so the search widget template can show them as {{ custom.label }} and a custom results page can read them from the result. Because they live under custom, they can never replace a field Staatic sets now or adds later.

Anything else is dropped without an error: invalid field names, objects, nested arrays, arrays with named keys inside a field, values that are not valid UTF-8, and list items beyond the limits. When no valid field remains, the record has no custom field. Links to your WordPress site in custom strings are rewritten to your static site.

Custom fields are for display only. They are not searchable, cannot be used to filter results and are not highlighted. Text that visitors should be able to find belongs in post_content.

Warning: Everything in a search record is public. Any visitor can read every field of every indexed record with the public search key that your static site includes. Never put private data in custom fields, such as email addresses, internal notes, prices that are not shown on the site, or anything else you would not publish on the page itself.

Example: show the section a page belongs to.

add_filter( 'staatic_search_item', function ( array $item, WP_Post $post ) {
    $item['custom'] = [
        'label' => $post->post_type === 'page' ? 'Documentation' : 'Blog',
    ];

    return $item;
}, 10, 2 );

To show the label in the search widget, override the suggestion template in your theme and add {{ custom.label }}. See Customizing the search widget. Use double braces: they escape the value, so HTML in a custom field is shown as text.

Related filters: staatic_posts_search_index_query changes the query that selects the posts to index, and staatic_search_indices changes the list of search indices.

Deployment-specific helpers

These hooks are most useful when extending or tuning built-in deployment targets.

Other extension hooks

Example debug toggle:

add_filter( 'staatic_debug', '__return_true' );