{{ site.name }}
``` {% endcode %} The stylesheet URL is filterable via `pressgang_stylesheet`. ### MenuContextManager Adds all registered WordPress navigation menus as Timber `Menu` objects, keyed by location. **Context keys:** `menu_{location}` (e.g. `menu_primary`, `menu_footer`) {% code title="views/partials/nav.twig" %} ```twig {% for item in menu_primary.items %} {{ item.title }} {% endfor %} ``` {% endcode %} Each menu is filterable via `pressgang_context_menu_{location}`. ### ThemeModsContextManager Adds all WordPress Customizer theme modifications to the `theme` object. **Context keys:** properties on `theme` (e.g. `theme.header_image`, `theme.custom_logo`) {% code title="views/partials/header.twig" %} ```twig {% if theme.custom_logo %}{{ __('Welcome aboard!', THEMENAME) }}
``` {% endcode %} ### MetaDescriptionExtensionManager **Functions:** * `meta_description()` — generates an SEO-friendly meta description for the current page, via the `MetaDescriptionService`. {% code title="views/layouts/base.twig" %} ```twig ``` {% endcode %} See [SEO](/seo) for details on the meta description fallback chain. ### SinglePostExtensionManager Only active on single post pages. Requires the post to be mapped to `PressGang\Post` via the `timber-class-map` config. **Functions:** * `get_latest_posts(count)` — fetches the latest posts (excluding the current one). * `get_related_posts(count)` — fetches posts related to the current one by shared taxonomy terms. {% code title="views/partials/related-posts.twig" %} ```twig {% for post in get_related_posts(3) %} {{ post.title }} {% endfor %} ``` {% endcode %} ### WidgetExtensionManager Registers a Twig function for rendering WordPress widgets in templates. ### WooCommerceExtensionManager Registers WooCommerce-specific Twig functions when WooCommerce is active. ## Creating a Custom Extension Manager {% stepper %} {% step %} #### Create the class {% code title="src/TwigExtensions/SocialExtensionManager.php" lineNumbers="true" %} ```php namespace MyTheme\TwigExtensions; use PressGang\TwigExtensions\HasNoFilters; use PressGang\TwigExtensions\HasNoGlobals; use PressGang\TwigExtensions\TwigExtensionManagerInterface; use Twig\Environment; use Twig\TwigFunction; class SocialExtensionManager implements TwigExtensionManagerInterface { use HasNoFilters; use HasNoGlobals; public function add_twig_functions(Environment $twig): void { $twig->addFunction(new TwigFunction('share_url', function (string $platform, string $url): string { return match ($platform) { 'twitter' => "https://twitter.com/intent/tweet?url=" . urlencode($url), 'facebook' => "https://www.facebook.com/sharer/sharer.php?u=" . urlencode($url), default => $url, }; })); } } ``` {% endcode %} {% endstep %} {% step %} #### Register in config Add to your child theme's `config/twig-extensions.php`: {% code title="config/twig-extensions.php" %} ```php return [ \PressGang\TwigExtensions\GeneralExtensionManager::class, \PressGang\TwigExtensions\MetaDescriptionExtensionManager::class, \PressGang\TwigExtensions\SinglePostExtensionManager::class, \PressGang\TwigExtensions\WidgetExtensionManager::class, \MyTheme\TwigExtensions\SocialExtensionManager::class, ]; ``` {% endcode %} {% endstep %} {% step %} #### Use in Twig {% code title="views/partials/share-buttons.twig" %} ```twig Share on Twitter ``` {% endcode %} {% endstep %} {% endstepper %} ## Rules for Twig Functions {% hint style="danger" %} Twig is for presentation only. Keep your Twig functions pure and side-effect free! {% endhint %} * **No database queries** — if you need data, provide it via a controller or context manager. * **No writes** — no `update_option()`, `wp_insert_post()`, or similar. * **No remote requests** — no `wp_remote_get()` or API calls. * **Deterministic** — same inputs should always produce the same outputs. * **Pure** — no side effects, no mutation of global state. {% hint style="info" %} The one documented exception is `WooCommerceExtensionManager::timber_set_product()`, which sets `global $product` as required by WooCommerce's template system. {% endhint %} # 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](/template-routing). And you can add your own alongside them. ## How They Work ```mermaid graph LR A["config/service-providers.php"] --> B["pressgang_service_providers filter"] B --> C["PressGang instantiates each class"] C --> D["boot() called on each provider"] ``` {% stepper %} {% step %} ### 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. {% endstep %} {% step %} ### 2. Filter allows modification The list is passed through the `pressgang_service_providers` filter, letting plugins or mu-plugins add or remove providers. {% endstep %} {% step %} ### 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. {% endstep %} {% endstepper %} ## The Interface Every service provider implements `ServiceProviderInterface`, which requires exactly one method: {% code title="src/ServiceProviders/ServiceProviderInterface.php" %} ```php namespace PressGang\ServiceProviders; interface ServiceProviderInterface { public function boot(): void; } ``` {% endcode %} {% hint style="info" %} Providers are instantiated with **no constructor arguments**. If your provider needs configuration, read it from `Config::get()` or WordPress options inside `boot()`. {% endhint %} ## Default Configuration {% code title="config/service-providers.php" lineNumbers="true" %} ```php return [ \PressGang\ServiceProviders\TimberServiceProvider::class, ]; ``` {% endcode %} `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](/context-managers) and [Twig Extensions](/twig-extensions) for details on each. ## Writing a Custom Service Provider {% stepper %} {% step %} ### Create the class {% code title="src/ServiceProviders/SearchServiceProvider.php" lineNumbers="true" %} ```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']); } } ``` {% endcode %} {% endstep %} {% step %} ### Register in config {% code title="config/service-providers.php" lineNumbers="true" %} ```php return [ \PressGang\ServiceProviders\TimberServiceProvider::class, \MyTheme\ServiceProviders\SearchServiceProvider::class, ]; ``` {% endcode %} {% hint style="warning" %} 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. {% endhint %} {% endstep %} {% endstepper %} ## Adding a Provider via Filter Plugins and mu-plugins can add providers without touching config files: {% code title="Plugin or mu-plugin" lineNumbers="true" %} ```php add_filter('pressgang_service_providers', function (array $providers): array { $providers[] = \MyPlugin\ServiceProviders\AnalyticsServiceProvider::class; return $providers; }); ``` {% endcode %} ## Guidelines {% hint style="danger" %} Service providers boot on **every request**. Keep `boot()` lightweight — register hooks and filters only, don't do real work. {% endhint %} * **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 | # Blocks PressGang provides declarative Gutenberg block registration, keeping your block setup clean and your codebase shipshape. Define your blocks in config, and PressGang handles the registration, path resolution, and lifecycle hooks. ## How It Works Blocks are registered via `config/blocks.php`. Each entry points to a directory containing a `block.json` file. PressGang's `Blocks` configuration class: 1. Resolves the block path (checking the child theme first, then the parent theme). 2. Validates and reads the `block.json` file. 3. Registers the block type with WordPress. 4. Invokes any `on_register` callback defined in the block's ACF `renderCallback`. 5. Fires a `pressgang_block_registered_{name}` action for additional setup. ## Directory Structure Each block lives in its own directory under `blocks/`: {% code title="blocks/" %} ``` blocks/ hero/ block.json hero.twig testimonial/ block.json testimonial.twig ``` {% endcode %} The `block.json` file follows the standard [WordPress block.json](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/) format. ## Configuration {% tabs %} {% tab title="Simple Registration" %} List paths to block directories in `config/blocks.php`: {% code title="config/blocks.php" %} ```php return [ '/blocks/hero', '/blocks/testimonial', '/blocks/call-to-action', ]; ``` {% endcode %} {% endtab %} {% tab title="With Additional Arguments" %} Pass extra arguments for `register_block_type()` using an associative array: {% code title="config/blocks.php" %} ```php return [ '/blocks/hero' => [ 'style' => 'hero-styles', ], '/blocks/testimonial', ]; ``` {% endcode %} {% endtab %} {% endtabs %} ## Child/Parent Theme Resolution PressGang automatically checks the child theme directory first when resolving block paths. This means you can override a parent theme's block by creating a block with the same path in your child theme. The resolved paths are cached for performance. {% code title="Resolution order" %} ``` 1. Check: get_stylesheet_directory() . '/blocks/hero' (child theme) 2. Fallback: get_template_directory() . '/blocks/hero' (parent theme) ``` {% endcode %} ## ACF Blocks PressGang has first-class support for [ACF blocks](https://www.advancedcustomfields.com/resources/blocks/). When a block's `block.json` defines an ACF `renderCallback`, PressGang will: 1. Look for the class specified in `acf.renderCallback[0]`. 2. If the class exists and has a static `on_register()` method, call it with the block settings. This allows blocks to perform one-time setup (like registering field groups) at registration time. {% code title="blocks/hero/block.json" %} ```json { "name": "acf/hero", "title": "Hero", "description": "A hero banner block.", "category": "theme", "acf": { "mode": "preview", "renderCallback": ["App\\Blocks\\Hero", "render"] } } ``` {% endcode %} ## Hooks | Hook | Type | Purpose | | ----------------------------------- | ------ | --------------------------------------------------------------------- | | `pressgang_block_registered_{name}` | action | Fired after a block is registered. Receives the block settings array. | The `{name}` placeholder is the block's `name` field from `block.json` (e.g. `pressgang_block_registered_acf/hero`). ## Block Rendering Rules {% hint style="success" %} Block rendering should be a pure function of block context — no side effects, no queries in the render path that aren't cached. {% endhint %} * Keep block templates simple and focused. * Prefer Twig templates over inline PHP render callbacks. * For new UI elements, prefer blocks over shortcodes — they give editors a much better experience. # Snippets Snippets are PressGang's answer to the WordPress `functions.php` junk drawer. Instead of dumping unrelated functionality into a single file — analytics scripts next to image size definitions next to admin tweaks — each concern gets its own class, with its own configuration, that can be enabled or disabled with a single line. Think of snippets as your ship's provisions — pre-packaged, self-contained, ready to be loaded aboard any theme. ## Why Snippets Instead of `functions.php` In a typical WordPress theme, `functions.php` grows into a sprawling file that mixes unrelated concerns: analytics tracking, custom image sizes, admin tweaks, WooCommerce overrides, Customizer settings. This creates problems: * **Hard to find things.** Where's the code that disables emojis? Somewhere in 800 lines. * **Hard to reuse.** Want the same analytics setup on another site? Copy-paste and hope you got everything. * **Hard to disable.** Commenting out blocks of code is error-prone and messy. * **Hard to share.** Distributing a `functions.php` snippet via Composer isn't practical. Snippets solve all of these: | `functions.php` approach | Snippet approach | | --------------------------------- | ----------------------------------------------- | | One file, many concerns | One class per concern | | Enable/disable by commenting code | Enable/disable by adding/removing a config line | | Copy-paste between projects | Install via Composer, share across all themes | | Arguments buried in code | Configuration passed explicitly via `$args` | | No standard structure | Every snippet implements the same interface | | Grows without limit | Each snippet stays small and focused | ## How Snippets Work ### The Interface Every snippet implements `SnippetInterface`, which requires exactly one thing — a constructor that accepts an array of arguments: {% code title="src/Snippets/SnippetInterface.php" %} ```php namespace PressGang\Snippets; interface SnippetInterface { public function __construct(array $args); } ``` {% endcode %} The constructor is where the snippet registers its WordPress hooks. Once constructed, the snippet is fully operational — no additional calls needed. ### The Config File Snippets are activated in your theme's `config/snippets.php`. Each entry maps a snippet class to its arguments: {% code title="config/snippets.php" lineNumbers="true" %} ```php return [ // No configuration needed — pass an empty array 'PressGang\\Snippets\\DisableEmojis' => [], // Configuration passed via the args array 'PressGang\\Snippets\\ImageSizes' => [ 'thumbnail' => ['width' => 150, 'height' => 150, 'crop' => true], 'hero' => ['width' => 1920, 'height' => 600, 'crop' => true], 'hero' => false, // Disable a size ], // Customizer-based snippets configure themselves via the WP Customizer 'PressGang\\Snippets\\GoogleAnalytics' => [], ]; ``` {% endcode %} To disable a snippet, remove or comment out its line. To reconfigure one, change its `$args` array. No code changes needed. ### Namespace Resolution PressGang resolves snippet class names in this order: 1. **Fully qualified** — if the name starts with `PressGang\` or your child theme namespace, it's used directly. 2. **Child theme first** — `YourTheme\Snippets\SnippetName` is checked, allowing you to override a library snippet with your own version. 3. **Parent fallback** — `PressGang\Snippets\SnippetName` is used if no child theme override exists. This means you can reference snippets by short name when they live in a standard namespace: {% code title="config/snippets.php" %} ```php return [ // These are equivalent: 'PressGang\\Snippets\\DisableEmojis' => [], 'DisableEmojis' => [], // Subfolders work too: 'WooCommerce\\ProductColorSwatch' => [], ]; ``` {% endcode %} ### Template Paths PressGang automatically adds the `pressgang-snippets` vendor views directory to Timber's template lookup paths. Twig templates bundled with snippet packages are available to your theme without any manual path configuration. ## Anatomy of a Snippet Here's what a typical snippet looks like — this one adds Google Analytics tracking via the WordPress Customizer: {% code title="src/Snippets/GoogleAnalytics.php" lineNumbers="true" %} ```php namespace PressGang\Snippets; use Timber\Timber; /** * Injects a Google Analytics (gtag.js) tracking script into wp_head. The tracking * ID is managed via the WordPress Customizer under a "Google" section. An optional * toggle controls whether logged-in users are tracked. * * No $args configuration needed — the tracking ID is entered via the Customizer. */ class GoogleAnalytics implements SnippetInterface { public function __construct(array $args) { \add_action('customize_register', [$this, 'add_to_customizer']); \add_action('wp_head', [$this, 'script']); } public function add_to_customizer(\WP_Customize_Manager $wp_customize): void { // Add Customizer section, setting, and control... } public function script(): void { if ($google_analytics_id = \get_theme_mod('google-analytics-id')) { Timber::render('snippets/google-analytics.twig', [ 'google_analytics_id' => $google_analytics_id, ]); } } } ``` {% endcode %} Key things to notice: * **Constructor registers hooks** — `customize_register` for the Customizer UI, `wp_head` for the script output. * **No work in the constructor itself** — it only wires up hooks for WordPress to call later. * **Renders via Timber** — output goes through a Twig template, not inline `echo` statements. * **Guards its output** — checks that a tracking ID exists before rendering anything. ## Writing Your Own Snippets Child themes will often need site-specific snippets that don't belong in the shared library. This is expected and encouraged — it's far better to write a snippet class than to add code to `functions.php`. {% stepper %} {% step %} ### Create the class Place it in your child theme's `src/Snippets/` directory: {% code title="src/Snippets/AdminBarQuoteButton.php" lineNumbers="true" %} ```php namespace YourTheme\Snippets; use PressGang\Snippets\SnippetInterface; /** * Adds a "Request a Quote" button to the admin bar on product pages. * * The button links to a configurable URL passed via $args. Only appears for * users with the 'edit_posts' capability. */ class AdminBarQuoteButton implements SnippetInterface { private string $url; public function __construct(array $args) { $this->url = $args['url'] ?? '/contact'; \add_action('admin_bar_menu', [$this, 'add_button'], 100); } public function add_button(\WP_Admin_Bar $admin_bar): void { if (!\current_user_can('edit_posts') || !\is_singular('product')) { return; } $admin_bar->add_node([ 'id' => 'request-quote', 'title' => \__('Request a Quote', THEMENAME), 'href' => \esc_url($this->url), ]); } } ``` {% endcode %} {% endstep %} {% step %} ### Register in config {% code title="config/snippets.php" %} ```php return [ 'AdminBarQuoteButton' => ['url' => '/request-quote'], ]; ``` {% endcode %} Because your child theme namespace is checked first, you only need the short class name. {% endstep %} {% step %} ### Add a Twig template (if needed) If your snippet renders output, place the template in your child theme's `views/snippets/` directory. Render it via `Timber::render('snippets/your-template.twig', $context)`. {% endstep %} {% endstepper %} ## Common Snippet PatternsCustomizer + Render
Adds a setting to the WordPress Customizer and renders output based on that setting. Used for third-party scripts, tracking pixels, and theme options that need a simple admin UI. {% code title="Pattern" %} ```php public function __construct(array $args) { \add_action('customize_register', [$this, 'add_to_customizer']); \add_action('wp_head', [$this, 'render']); } ``` {% endcode %} **Examples:** `GoogleAnalytics`, `GoogleTagManager`, `FacebookPixel`, `Hotjar`, `GoogleRecaptcha`Hook Filtering
Modifies WordPress behaviour via actions and filters. No UI, no templates — just behavioural changes. {% code title="Pattern" %} ```php public function __construct(array $args) { $this->exclude = $args['exclude'] ?? []; \add_filter('pre_get_posts', [$this, 'modify_query']); } ``` {% endcode %} **Examples:** `DisableEmojis`, `BigImageScaling`, `SearchExcludePostTypes`, `RemovePosts`Config-Driven Registration
Receives structured `$args` and registers WordPress resources. The args array shape mirrors WordPress API conventions. {% code title="Pattern" %} ```php public function __construct(array $args) { $this->args = $args; \add_action('init', [$this, 'setup_image_sizes']); } ``` {% endcode %} **Examples:** `ImageSizes`, `Permalinks`, `AddQueryVars`Admin Features
Adds functionality to the WordPress admin — row actions, admin notices, editor customisation. Always includes capability checks and nonce verification. **Examples:** `DuplicatePost`, `AdminLogo`, `TinyMceBlockFormats`Twig Function Registration
Registers a callable function into the Twig environment, making it available in templates as `{{ function_name() }}`. {% code title="Pattern" %} ```php public function __construct(array $args) { \add_filter('timber/twig', [$this, 'add_to_twig']); } public function add_to_twig(Environment $twig): Environment { $twig->addFunction(new TwigFunction('breadcrumb', [$this, 'render'])); return $twig; } ``` {% endcode %} **Examples:** `Breadcrumb`admin-post"] B --> C["FormSubmission::
handle_form_submission()"] C --> D["Nonce verification"] D --> E["Input flashing"] E --> F["Validator pipeline"] F --> G["process_submission()
(your logic)"] G --> H["Redirect with status"] ``` ## FormSubmission (Base Class) The abstract `FormSubmission` class handles the form lifecycle: 1. **Nonce verification** — rejects requests with invalid or missing nonces. 2. **Input flashing** — sanitises and stores submitted values in the session (via `Flash`), so forms can be repopulated after validation errors. 3. **Validation** — runs all configured validators and collects errors. 4. **Processing** — calls your `process_submission()` implementation on success. 5. **Redirect** — sends the user back to the referring page with success/error flags. ### Creating a Form Handler Extend `FormSubmission` and implement `process_submission()`: {% code title="src/Forms/NewsletterSubmission.php" lineNumbers="true" %} ```php namespace MyTheme\Forms; use PressGang\Forms\FormSubmission; class NewsletterSubmission extends FormSubmission { protected function process_submission(): void { $email = sanitize_email($_POST['email'] ?? ''); // Your newsletter subscription logic here subscribe_to_newsletter($email); } } ``` {% endcode %} ### Initialising and Registering Hooks Form handlers register themselves with WordPress via `admin_post` actions: {% code title="Snippet or functions.php" %} ```php use MyTheme\Forms\NewsletterSubmission; NewsletterSubmission::init([ 'action' => 'newsletter_signup', 'validators' => [ new \PressGang\Forms\Validators\EmailValidator(['email']), ], ]); ``` {% endcode %} This registers handlers for both logged-in (`admin_post_{action}`) and logged-out (`admin_post_nopriv_{action}`) users. ## Built-in: ContactSubmission PressGang ships with a `ContactSubmission` class that handles contact form emails out of the box: * Sends email via `wp_mail()` to the site admin. * Supports optional Twig templates for email formatting. * Configurable success/error messages. * Filterable recipient via `pressgang_contact_to_email`. * Filterable subject via `pressgang_contact_subject`. {% code title="Contact form setup" lineNumbers="true" %} ```php use PressGang\Forms\ContactSubmission; ContactSubmission::init([ 'action' => 'contact_form', 'template' => 'emails/contact.twig', // optional 'success_message' => __("Thanks for your message!", THEMENAME), 'validators' => [ new \PressGang\Forms\Validators\EmailValidator(), new \PressGang\Forms\Validators\MessageValidator(), new \PressGang\Forms\Validators\RecaptchaValidator(), ], ]); ``` {% endcode %} ## Validators Validators implement the `ValidatorInterface`: {% code title="src/Forms/Validators/ValidatorInterface.php" %} ```php namespace PressGang\Forms\Validators; interface ValidatorInterface { public function validate(): array; } ``` {% endcode %} The `validate()` method returns an empty array on success, or an array of error messages on failure. ### Built-in Validators | Validator | Purpose | | -------------------- | ------------------------------------------------------- | | `EmailValidator` | Validates that a submitted email address is well-formed | | `MessageValidator` | Validates that a message field is not empty | | `RecaptchaValidator` | Validates a Google reCAPTCHA response | ### Creating a Custom Validator {% code title="src/Forms/Validators/PhoneValidator.php" lineNumbers="true" %} ```php namespace MyTheme\Forms\Validators; use PressGang\Forms\Validators\ValidatorInterface; class PhoneValidator implements ValidatorInterface { public function validate(): array { $phone = sanitize_text_field($_POST['phone'] ?? ''); if (empty($phone) || !preg_match('/^\+?[\d\s\-()]+$/', $phone)) { return [__('Please provide a valid phone number.', THEMENAME)]; } return []; } } ``` {% endcode %} ## Form Template (Twig) Your Twig form template must include a nonce field and target the `admin_post` endpoint: {% code title="views/forms/contact.twig" lineNumbers="true" %} ```twig ``` {% endcode %} ## Security {% hint style="danger" %} All PressGang forms enforce WordPress security conventions — nonce verification, input sanitisation, and capability checks are mandatory. Never trust raw user input! {% endhint %} * Nonce validation is automatic — handled by `FormSubmission::handle_form_submission()`. * All input should be sanitised using `sanitize_text_field()`, `sanitize_email()`, etc. * Validation logic must live in validators, not in controllers. * Controllers may only consume validated data — they must never process form submissions directly. # SEO PressGang includes a built-in `MetaDescriptionService` that generates smart, cached meta descriptions for every page on your site. No need for a full SEO plugin just to get decent meta tags — PressGang has you covered on this voyage. ## MetaDescriptionService The `MetaDescriptionService` generates a single, authoritative meta description for the current page. It's available in Twig via the `meta_description()` function (registered by the `MetaDescriptionExtensionManager`). ### Usage in Twig {% code title="views/scaffold/head.twig" %} ```twig {{ fn('wp_head') }} ``` {% endcode %} That's it. PressGang's SEO service provider renders its fallback `` tag through `wp_head` only when a dedicated SEO plugin is not detected. ## Fallback Chain The service uses a smart fallback chain to find the best description for each page type:
Posts and Pages
1. **Yoast SEO meta description** (`_yoast_wpseo_metadesc` post meta) — if Yoast is installed and a description is set, it takes priority. 2. **Custom field** (`meta_description` post meta) — a manual override without needing Yoast. 3. **Post excerpt** — the WordPress excerpt field. 4. **Post content** — falls back to the rendered content. 5. **Site tagline** — the default site description from Settings > General.Taxonomy Terms
1. **Yoast SEO taxonomy meta** — if configured in Yoast's taxonomy settings. 2. **Term description** — the description field from the term editor. 3. **Site tagline** — the default fallback.Archives
1. **Archive description** — via `get_the_archive_description()`. 2. **Site tagline** — the default fallback.Front Page
Always uses the **site tagline** (from Settings > General > Tagline).🚢 Bootstrap
| Method | Description | | ------------------------------------ | --------------------------------- | | `Quartermaster::posts($postType?)` | Start a new post query builder | | `Quartermaster::terms($taxonomy?)` | Start a new term query builder | | `Quartermaster::prepare($postType?)` | Compatibility alias for `posts()` |📌 Post Constraints
| Method | Sets | | ------------------------- | ----------------- | | `postType(string\|array)` | `post_type` | | `status(string)` | `post_status` | | `whereId(int)` | `p` | | `whereInIds(array)` | `post__in` | | `excludeIds(array)` | `post__not_in` | | `whereParent(int)` | `post_parent` | | `whereParentIn(array)` | `post_parent__in` | | `whereAuthor(int)` | `author` | | `whereAuthorIn(array)` | `author__in` | | `whereAuthorNotIn(array)` | `author__not_in` |🔎 Meta Queries
| Method | Description | | --------------------------------------------------- | ------------------------------------- | | `whereMeta($key, $value, $compare?, $type?)` | AND meta clause | | `orWhereMeta($key, $value, $compare?, $type?)` | OR meta clause | | `whereMetaNot($key, $value)` | Exclude by value (handles NOT EXISTS) | | `whereMetaDate($key, $operator, $value?, $format?)` | Date comparison (defaults to today) | | `whereMetaExists($key)` | Key exists check | | `whereMetaNotExists($key)` | Key does not exist check | | `wherePageTemplate($template)` | Match pages by `_wp_page_template` | | `whereMetaLikeAny($key, $values)` | Match serialized ACF fields |🏷️ Taxonomy Queries
| Method | Description | | ---------------------------------------------------- | ------------------------------------------ | | `whereTax($taxonomy, $terms, $field?, $operator?)` | Taxonomy query clause (AND) | | `orWhereTax($taxonomy, $terms, $field?, $operator?)` | Taxonomy query clause under an OR relation | Field defaults to `slug`. Operator defaults to `IN`. Multiple `whereTax()` calls produce an AND relation; the first `orWhereTax()` switches it to OR. Null or empty `$terms` leave the builder unchanged, so optional filters can be passed directly (`->whereTax('topic', $topic ?: null)`).📅 Date Queries
| Method | Description | | --------------------------------------------- | -------------------------------- | | `whereDate(array)` | Raw WordPress date\_query clause | | `whereDateAfter(string\|array, $inclusive?)` | Published after date | | `whereDateBefore(string\|array, $inclusive?)` | Published before date |↕️ Ordering
| Method | Description | | -------------------------------------------------------------- | ----------------------------- | | `orderBy($orderby, $order?)` | Set order field and direction | | `orderByAsc($orderby)` / `orderByDesc($orderby)` | Shorthand | | `orderByMeta($key, $order?, $type?)` | Order by meta value | | `orderByMetaAsc($key)` / `orderByMetaDesc($key)` | Shorthand meta ordering | | `orderByMetaNumeric($key, $order?)` | Order by numeric meta | | `orderByMetaNumericAsc($key)` / `orderByMetaNumericDesc($key)` | Shorthand |🔍 Search
| Method | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------ | | `search(string\|null)` | Set search term (`s`); sanitised, null/empty ignored | | `relevanssi(string\|null)` | Search with Relevanssi (`s` + `relevanssi = true`); requires [Relevanssi](https://www.relevanssi.com/) |📄 Pagination and Performance
| Method | Description | | -------------------------- | ------------------------------------------------ | | `paged($perPage?, $page?)` | Paginate (reads current page from query vars) | | `limit(int)` | Fixed result count | | `all()` | Fetch all (`posts_per_page=-1`, `nopaging=true`) | | `noFoundRows()` | Skip `SQL_CALC_FOUND_ROWS` | | `idsOnly()` | Return IDs only (`fields='ids'`) | | `withMetaCache(bool)` | Toggle meta cache priming | | `withTermCache(bool)` | Toggle term cache priming | | `ignoreStickyPosts()` | Prevent sticky posts being prepended |🔀 Conditionals and Hooks
| Method | Description | | ----------------------------------- | --------------------- | | `when($condition, $then, $else?)` | Conditional closure | | `unless($condition, $then, $else?)` | Inverse conditional | | `tap($callback)` | Always-run closure | | `tapArgs($callback)` | Raw args manipulation |🔌 Macros
| Method | Description | | ------------------------- | ----------------------------- | | `macro($name, $callable)` | Register a named macro | | `hasMacro($name)` | Check if macro is registered | | `flushMacros()` | Remove all macros (for tests) |🔗 Query-Var Binding
| Method | Description | | -------------------------------------------- | ------------------------------------------------------------------------------------ | | `bindQueryVars($bindings, $source?)` | Bind URL query vars to query clauses | | `Bind::paged()` | Pagination binding | | `Bind::tax($taxonomy, $field?, $operator?)` | Taxonomy binding | | `Bind::orderBy($default, $dir, $overrides?)` | Order binding with per-field overrides | | `Bind::metaNum($key, $compare)` | Numeric meta binding | | `Bind::search()` | Search term binding | | `Bind::relevanssi()` | Relevanssi-aware search binding (requires [Relevanssi](https://www.relevanssi.com/)) |🔍 Introspection
| Method | Returns | | ----------- | ------------------------------------------- | | `toArgs()` | `array🏁 Terminals
| Method | Returns | | ----------------- | ------------------------------------------------------------------ | | `get()` | `WP_Post[]` — execute and return posts | | `toArray()` | `array` — smart Timber/WP detection | | `first()` | `Timber\Post\|WP_Post\|null` — first match, builder unchanged | | `wpQuery()` | `WP_Query` — full query object | | `timber()` | `Timber\PostQuery` — Timber post collection | | `applyTo($query)` | `void` — modify existing `WP_Query` in place (for `pre_get_posts`) |🏷️ Terms Builder
| Method | Description | | ---------------------------------------------------- | -------------------------------------------------------------- | | `taxonomy(string\|array)` | Set taxonomy | | `objectIds(int\|array)` | Scope to specific post(s) | | `forPostType(string)` | Scope terms to a post type (via `object_ids`) | | `hideEmpty(bool)` | Hide/show empty terms | | `slug(string\|array)` | Filter by slug | | `name(string\|array)` | Filter by name | | `fields(string)` | Control return fields (`ids`, `names`, `slugs`, `count`, etc.) | | `include(array)` / `exclude(array)` | Include/exclude term IDs | | `excludeTree(int\|array)` | Exclude entire term branches | | `parent(int)` | Direct children only | | `childOf(int)` | All descendants | | `childless(bool)` | Leaf terms only | | `search(string)` | Search terms | | `limit(int)` / `offset(int)` | Limit and offset | | `page(int, int)` | Convenience pagination | | `orderBy(string, string)` | Order terms | | `whereMeta()` / `orWhereMeta()` | Term meta queries | | `whereMetaExists($key)` / `whereMetaNotExists($key)` | Valueless term metadata existence checks | | `get()` | Execute and return terms | | `timber()` | Execute and return `Timber\Term[]` || What most teams do today | What it costs |
|---|---|
| Click test content in by hand | Nobody else has your content, and it vanishes on the next reset. The awkward states — a 90-character title, a missing hero image, an empty repeater — are exactly the ones nobody builds by hand. |
| Copy the production database down | Puts real customer data on developer laptops. Gigabytes to move, and stale within a week. |
Share a .sql dump or WXR export | Opaque and unreviewable — nobody can see in a pull request what changed, and it drifts away from the code it exists to support. |
| Work against an empty site | The bugs your editors hit don't appear until an editor hits them. |