Download the PHP package pressgang-wp/quartermaster without Composer

cl

⚓ Quartermaster

Quartermaster is a fluent, args-first builder for WP_Query.

It helps you build complex query arrays in readable, composable steps, while staying 100% WordPress-native under the hood. It ships as a standalone package in the pressgang-wp ecosystem, but it does not depend on the PressGang theme framework.

Think of it as a reliable quartermaster for your query cargo: you decide what goes aboard, nothing gets smuggled in. 🧭

📦 Install

Requirements: PHP 8.3+.

🗺️ Quick Reference Method Index

🤔 Why Fluent?

WP_Query arrays are powerful, but as they grow they become harder to scan, review, and refactor.

Quartermaster gives you:

• ✨ Better readability — query intent is expressed step-by-step
• 🧩 Better composability — add or remove clauses without rewriting a large array
• 🛡️ Better safety — methods are explicit about which WP args they set
• 🔍 Better debugging — inspect exact output with toArgs() and explain()

You still end up with plain WordPress args.
No ORM. No hidden query engine. No lock-in. Just well-organised cargo. ⚓

Sometimes raw WP_Query is fine — if your query is short and static, use it.
Quartermaster shines when queries evolve, branch, or need to be composed without losing your bearings. 🧭

🧠 Design Philosophy

Quartermaster is intentionally light-touch:

• 🧱 WordPress-native — every fluent method maps directly to real WP_Query keys
• 🫙 Zero side effects by default — Quartermaster::posts()->toArgs() is empty
• 🎯 Opt-in only — nothing changes unless you call a method
• 🔌 Loosely coupled — no mutation of WordPress internals, no global state changes
• 🌲 Timber-agnostic core — Timber support is optional and runtime-guarded
• 🧭 Explicit over magic — sharp WP edges are documented, not hidden

Steady hands on the wheel, predictable seas ahead. 🚢

🚫 Non-Goals (Read Before Boarding)

Quartermaster deliberately does not aim to:

• Replace WP_Query or abstract it away
• Act as an ORM or ActiveRecord layer
• Hide WordPress limitations (e.g. tax/meta OR logic)
• Automatically infer defaults or “best practices”
• Replace WordPress term query APIs

If WordPress requires a specific argument shape, Quartermaster expects you to be explicit.
No fog, no illusions, no siren songs. 🧜‍♀️

🚀 Quick Start

posts('event') is a convenience seed only. It only sets post_type and does not infer any other query args.

prepare() remains available as a low-level backwards-compatible alias.

Run the query and get posts:

When you need the full WP_Query object (pagination metadata, found rows, loop state):

🌿 Terms Quick Start

Filter by slug, get just IDs, or scope to a specific post:

Inspect generated args:

🔗 Binding Query Vars (Two Styles)

Nothing reads query vars unless you explicitly call bindQueryVars().

Map style with Bind::*:

Fluent binder style with Binder:

If no taxonomy is provided, Binder assumes the taxonomy name matches the query var key.

Both styles are explicit and compile to the same binding map. No smuggling, no hidden defaults.

🗓️ Common Pattern: Meta Date vs Today

Filtering by a meta date (e.g. upcoming vs past events) is a very common WordPress pattern.

This keeps intent explicit:

• whereMetaDate(...) adds a meta_query DATE clause
• orderByMeta(...) controls ordering separately

No hidden assumptions. No barnacles. ⚓

🔌 Macros (Project-Level Sugar)

Macros let you register project-specific fluent methods without bloating the core API. They are opt-in, not part of core — use them for patterns that repeat across your project.

Macros should call existing Quartermaster methods — avoid mutating internal args directly. Macro invocations are recorded in explain() as macro:<name> for debuggability.

Register macros in your theme's functions.php or a service provider. Both builders (Quartermaster and TermsBuilder) support macros independently.

🔀 Conditional Queries & Hooks

when(), unless(), and tap() keep fluent chains readable without introducing magic or hidden state. None of them read globals or add defaults.

when() — runs a closure when the condition is true:

Or with an else clause:

unless() — inverse of when() (unless($x) is when(!$x)):

tap() — always runs a closure, for builder-level logic without breaking the chain:

All three are recorded in explain() for debuggability. No magic, no hidden state. ⚓

🪝 Query Hooks (pre_get_posts)

applyTo() modifies an existing WP_Query in place instead of creating a new one — designed for WordPress pre_get_posts hooks:

When multiple hooks call applyTo(), clause arrays (tax_query, meta_query, date_query) are merged with existing clauses — not overwritten — so hooks compose safely.

applyTo() is a void terminal: it does not return the builder. If you need to inspect the applied args, hold a reference to the builder and call explain() separately.

🌲 Optional Timber Terminal

If Timber is unavailable, Quartermaster throws a clear runtime exception rather than hard-coupling Timber into core.

🔍 Debugging & Introspection

Ordering direction is explicit: Quartermaster accepts only ASC/DESC; invalid values are normalized to method defaults and surfaced in explain() warnings.

Inspect generated args:

Inspect args plus applied calls and warnings:

Perfect for reviews, debugging, and keeping junior crew out of trouble. 🧭

Smooth seas and predictable queries.
Happy sailing. ⚓🚢