Publication lifecycle hooks

Use these hooks when you need to observe, tune, or customize the publication process itself. If your change is about which URLs Staatic should crawl or rewrite, start with URL processing hooks instead.

Publication task sequence

A normal publication moves through named tasks. Some tasks can run more than once internally because crawling and deployment are processed in batches.

Run code around tasks

Use these hooks for logging, notifications, metrics, cache invalidation, or other side effects around task execution.

staatic_publication_task_any

Runs before a task execution attempt.

In the background publisher this can run more than once for restartable tasks such as crawling and deployment, because those tasks can resume across requests. Make callbacks idempotent.

Arguments:

Example:

add_action( 'staatic_publication_task_any', function ( $publication, $task, $isBackground ) {
    error_log( sprintf(
        'Staatic task attempt: %s for publication %s (%s)',
        $task::name(),
        $publication->id(),
        $isBackground ? 'background' : 'cli'
    ) );
}, 10, 3 );

staatic_publication_task_before

Runs before a publication task starts.

For background publishing, this action runs when the current task changes, not on every restarted batch of the same task. Use staatic_publication_task_any if you need every execution attempt.

Arguments:

Example:

use Staatic\WordPress\Publication\Publication;
use Staatic\WordPress\Publication\Task\TaskInterface;

add_action( 'staatic_publication_task_before', function ( Publication $publication, TaskInterface $task ) {
    if ( $task::name() !== 'crawl' ) {
        return;
    }

    error_log( 'Starting crawl for publication: ' . $publication->id() );
}, 10, 2 );

staatic_publication_task_after

Runs after a publication task has finished.

Use this hook when a side effect should happen only after a full task has completed. For example, send a notification after deployment has finished.

Arguments:

Example:

add_action( 'staatic_publication_task_after', function ( Publication $publication, TaskInterface $task ) {
    if ( $task::name() !== 'finish_deployment' ) {
        return;
    }

    wp_mail(
        'admin@example.com',
        'Staatic deployment complete',
        'Publication ' . $publication->id() . ' has been deployed successfully.'
    );
}, 10, 2 );

Change publication tasks

Use staatic_publication_tasks only when the publication process itself needs a new step or a removed step. For most integrations, adding a crawl URL provider, transformer, or post-processor is safer than changing the task sequence.

staatic_publication_tasks

Allows publication tasks to be added, reordered, or removed before a publication starts.

Arguments:

The task collection supports add(), addBefore(), addAfter(), has(), get(), and forget().

Example:

use Staatic\WordPress\Publication\Task\TaskCollection;

add_filter( 'staatic_publication_tasks', function ( TaskCollection $tasks ) {
    if ( defined( 'STAATIC_SKIP_DEPLOYMENT' ) && STAATIC_SKIP_DEPLOYMENT ) {
        $tasks->forget( [
            'initiate_deployment',
            'deploy',
            'finish_deployment',
        ] );
    }

    return $tasks;
} );

Tune batch sizes and timeouts

These filters change how much work Staatic attempts in each publication step. Larger values can improve throughput on capable servers, but they also increase memory use and the risk of request timeouts.

staatic_crawl_batch_size

Filters the maximum number of crawl operations Staatic schedules for a crawl batch.

Arguments:

Example:

add_filter( 'staatic_crawl_batch_size', function ( $batchSize ) {
    return min( $batchSize, 20 );
} );

staatic_deploy_batch_size

Filters the maximum number of results Staatic deploys in a deployment batch.

Arguments:

staatic_publication_timeout

Filters the maximum publication age, in hours, before Staatic treats the publication as timed out.

Arguments:

Example:

add_filter( 'staatic_publication_timeout', function () {
    return 12;
} );

Adjust cleanup retention

Staatic periodically removes old publication and log data. These hooks control retention windows in days.

Example:

add_filter( 'staatic_publication_cleanup_num_days', function () {
    return 30;
} );

add_filter( 'staatic_log_cleanup_num_days', function () {
    return 30;
} );

Add publication inputs

These filters are useful when settings alone are too static, but you do not need a full custom crawl URL provider.

Example:

use Staatic\Crawler\CrawlUrlProvider\AdditionalUrlCrawlUrlProvider\AdditionalUrl;

add_filter( 'staatic_additional_urls', function ( array $urls ) {
    $urls[] = new AdditionalUrl( 'https://www.example.com/landing-page/' );
    return $urls;
} );

Use extension hooks when additional URLs must be produced by a reusable provider class.