WordPress Plugin Boilerplate: The Canonical Scaffold for Serious Plugins

Building a WordPress plugin "from an empty file" works until activation hooks, i18n, admin menus, AJAX handlers, and public assets sprawl across a single 800-line PHP file. WordPress Plugin Boilerplate (~7.8k stars) gives you a battle-tested, object-oriented layout that countless plugins (including commercial ones) still echo. It is not the only scaffold — but it is the one most PHP developers recognize when they open a repo for the first time.

What problem it solves

WordPress plugin tutorials often start with a top-level file and add_action() calls sprinkled like seasoning. That scales poorly when you add:

• Admin settings pages with nonce validation
• Public shortcodes or blocks with separate asset enqueues
• REST API endpoints with permission callbacks
• Internationalization for multiple locales
• Unit tests that need classes you can instantiate without loading all of wp-admin

The Boilerplate enforces separation: a bootstrap file, a loader class that registers hooks, distinct admin and public classes, and includes for each concern. You spend cognitive energy on features, not inventing folder structure.

What you get out of the box

• Clear admin vs public separation (admin/ and public/ directories)
• Loader / hooks pattern instead of spaghetti add_action calls in one file
• i18n-ready text domains with languages/ stub
• A naming convention you can grep six months later
• Deactivation and activation hook stubs
• Uninstall stub reminding you to clean up options and custom tables

Who should use the Boilerplate

• First-time plugin authors who want a map of "where things go"
• Agencies shipping small custom plugins per client
• Developers extracting functionality from a theme into a proper plugin
• Teams that value OOP patterns influenced by PSR-style organization

When NOT to use it

• Block-only plugins — @wordpress/create-block may be a better starting point
• Single-hook mu-plugins — a ten-line must-use plugin does not need the full scaffold
• Composer-first modern plugins — you may prefer a custom PSR-4 layout with PHPStan from day one
• When upstream inactivity matters — verify GitHub activity; treat as structure reference and layer modern tooling yourself

How to start

1. Clone or download the boilerplate from GitHub.
2. Run a project-wide rename of the placeholder plugin slug, class prefixes, and text domain (many teams script this with sed or a custom generator).
3. Drop it into wp-content/plugins/ (or web/app/plugins/ on Bedrock) and activate.
4. Implement features behind service classes — keep the main plugin file thin.
5. Add Composer autoloading if the plugin grows beyond a handful of classes.

Maintenance note: The upstream repo's last push at research time was older than other tools in this series. Still use it as a structure reference, and layer modern tooling (PHPStan, PHPUnit, block.json, GitHub Actions) as needed. Confirm activity on GitHub before treating it as "fresh."

Recommended development workflow

1. Define the plugin's single job — one sentence scope statement.
2. Sketch admin UX (menu location, capabilities required).
3. Identify public surface area (shortcodes, blocks, REST routes, or none).
4. Write activation requirements (dependencies like ACF — see Quickfields below).
5. Debug with Query Monitor during development.
6. Ship updates via WP-CLI on staging before production.

Boilerplate vs create-block vs custom PSR-4

Example of a focused plugin built for one job

Our Quickfields Bulk Editor for ACF is a production example of a plugin that does one thing well: spreadsheet bulk editing of ACF text fields on WordPress pages. Whether you scaffold with the Boilerplate or a custom layout, the principle is the same — narrow scope, clear admin UX, documented requirements (WordPress 5.8+, PHP 7.4+, ACF active). Read the full guide: Quickfields blog post. Pro features: Quickfields Pro.

Gotchas

• Rename everything — leaving placeholder slugs causes activation collisions.
• Capabilities — default to least privilege; do not hang menus on manage_options unless necessary.
• Autoloading — require_once chains get tired; Composer PSR-4 pays off quickly.
• Block editor era — classic admin-only plugins may still need block.json for editor-side features.

FAQ

Is the Boilerplate still best practice? As a mental model, yes. As a copy-paste without modernization, only if it fits your stack.

GPL license? Yes — compatible with WordPress.org distribution if you pursue it.

Works with Bedrock? Yes — install like any other plugin under web/app/plugins/.

How do I test? Add PHPUnit with WordPress test suite bootstrap; the Boilerplate's class structure makes unit testing individual admin/public methods easier than a single procedural file.

Internationalization? The text domain stub is ready — run strings through GlotPress or Poedit before WordPress.org submission if you distribute publicly.

From scaffold to shipped plugin (realistic timeline)

Week one: rename boilerplate, define scope, build admin screen MVP. Week two: public-facing features or REST routes, capability audit, Query Monitor profiling. Week three: documentation, compatibility testing across PHP versions, staging deploy via WP-CLI. The Boilerplate does not shorten feature work — it shortens "where does this file go?" debates. Study Quickfields on GitHub as a reference for focused plugin scope: one admin menu, clear requirements table, honest field-type support matrix, and links to documentation and Pro upsell without dark patterns.

Repo

github.com/DevinVinson/WordPress-Plugin-Boilerplate