🔌Service Providers

Service providers are PressGang's hook for bootstrapping services after the framework has initialised. They run after Timber and the Loader are ready, making them the right place for wiring up filters, registering integrations, or initialising third-party libraries.

PressGang ships with one service provider by default — TimberServiceProvider — which registers context managers, Twig extensions, Twig environment options, and snippet template paths. The framework also provides the opt-in TemplateRoutingServiceProvider for convention-based Template Routing. And you can add your own alongside them.

How They Work

1

1. Config declares providers

Class strings are listed in config/service-providers.php. Child theme config replaces the parent file, so always include TimberServiceProvider unless you're intentionally removing it.

2

2. Filter allows modification

The list is passed through the pressgang_service_providers filter, letting plugins or mu-plugins add or remove providers.

3

3. PressGang boots each one

Each class string is validated: it must be a loadable class implementing ServiceProviderInterface. Invalid entries are skipped silently — no fatal errors from a bad config line.

The Interface

Every service provider implements ServiceProviderInterface, which requires exactly one method:

src/ServiceProviders/ServiceProviderInterface.php

namespace PressGang\ServiceProviders;

interface ServiceProviderInterface {
    public function boot(): void;
}

Providers are instantiated with no constructor arguments. If your provider needs configuration, read it from Config::get() or WordPress options inside boot().

Default Configuration

config/service-providers.php

return [
    \PressGang\ServiceProviders\TimberServiceProvider::class,
];

TimberServiceProvider wires up:

Concern	Config source	Hook
Context managers	config/context-managers.php	timber/context
Twig extensions	config/twig-extensions.php	timber/twig
Twig environment options	config/timber.php	timber/twig/environment/options
Snippet template paths	vendor directory	timber/locations

See Context Managers and Twig Extensions for details on each.

Writing a Custom Service Provider

1

Create the class

src/ServiceProviders/SearchServiceProvider.php

namespace MyTheme\ServiceProviders;

use PressGang\ServiceProviders\ServiceProviderInterface;

/**
 * Customises the main search query to exclude specific post types
 * and boost exact title matches.
 */
class SearchServiceProvider implements ServiceProviderInterface {

    public function boot(): void {
        \add_action('pre_get_posts', [$this, 'customise_search']);
    }

    public function customise_search(\WP_Query $query): void {
        if (! $query->is_main_query() || ! $query->is_search() || \is_admin()) {
            return;
        }

        $query->set('post_type', ['post', 'page', 'event']);
    }
}

2

Register in config

config/service-providers.php

return [
    \PressGang\ServiceProviders\TimberServiceProvider::class,
    \MyTheme\ServiceProviders\SearchServiceProvider::class,
];

A child theme's config/service-providers.php replaces the parent file entirely. Always include TimberServiceProvider unless you are intentionally removing PressGang's default Timber integration.

Adding a Provider via Filter

Plugins and mu-plugins can add providers without touching config files:

Plugin or mu-plugin

add_filter('pressgang_service_providers', function (array $providers): array {
    $providers[] = \MyPlugin\ServiceProviders\AnalyticsServiceProvider::class;
    return $providers;
});

Guidelines

Service providers boot on every request. Keep boot() lightweight — register hooks and filters only, don't do real work.

• Register hooks in boot(), execute work in callbacks. The boot() method should only call add_action() / add_filter() — not perform queries, remote requests, or heavy computation.

• One concern per provider. If your provider handles both search customisation and email configuration, split it into two providers.

• Guard for dependencies. If your provider depends on a plugin (ACF, WooCommerce, etc.), check class_exists() or function_exists() before registering hooks.

• No constructor arguments. PressGang instantiates providers with new $class(). Use Config::get() or WordPress options for configuration.

Hooks

Hook	Type	Purpose
pressgang_service_providers	filter	Modify the list of service provider class strings before boot