PHPackages golchha/wp-plugin-boilerplate - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. golchha/wp-plugin-boilerplate ActiveWordpress-plugin[Framework](/categories/framework) golchha/wp-plugin-boilerplate ============================= An opinionated WordPress plugin boilerplate for building long-lived plugins with explicit structure and predictable lifecycle behavior. 1.6.4(1mo ago)1101GPL-2.0-or-laterPHPPHP ^8.3 Since Feb 3Pushed 1mo agoCompare [ Source](https://github.com/golchha21/wp-plugin-boilerplate)[ Packagist](https://packagist.org/packages/golchha/wp-plugin-boilerplate)[ Docs](https://github.com/golchha21/wp-plugin-boilerplate)[ RSS](/packages/golchha-wp-plugin-boilerplate/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)DependenciesVersions (23)Used By (0) WP Plugin Boilerplate ===================== [](#wp-plugin-boilerplate) > A structured WordPress plugin boilerplate with a schema-driven field engine, MetaBox system, and deterministic plugin architecture. [![PHP](https://camo.githubusercontent.com/1ace9cc73d1b7852b328ddf28db57e9c8b0a8b4879604efe0511e8e8da052976/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e332d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/1ace9cc73d1b7852b328ddf28db57e9c8b0a8b4879604efe0511e8e8da052976/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e332d3737374242343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)[![Version](https://camo.githubusercontent.com/c57c9dc4795d9667ec99b57aad9af99cef151ddf254b5cbbf12a1d5213ce3c89/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f7461672f676f6c6368686132312f77702d706c7567696e2d626f696c6572706c617465)](https://camo.githubusercontent.com/c57c9dc4795d9667ec99b57aad9af99cef151ddf254b5cbbf12a1d5213ce3c89/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f7461672f676f6c6368686132312f77702d706c7567696e2d626f696c6572706c617465)[![Downloads](https://camo.githubusercontent.com/c81d2e9175e340dfc7bcda7ea0a587d32fd919caf379789a365deddf890b8368/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f646f776e6c6f6164732f676f6c6368686132312f77702d706c7567696e2d626f696c6572706c6174652f746f74616c)](https://camo.githubusercontent.com/c81d2e9175e340dfc7bcda7ea0a587d32fd919caf379789a365deddf890b8368/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f646f776e6c6f6164732f676f6c6368686132312f77702d706c7567696e2d626f696c6572706c6174652f746f74616c) --- An opinionated WordPress plugin boilerplate for building long-lived plugins with explicit structure and predictable lifecycle behavior. This project does not provide user-facing features and does not try to replace WordPress conventions, Git workflows, or existing development practices. It exists to provide a constrained starting point for plugins that are expected to grow over time - where admin configuration, settings, frontend behavior, and lifecycle concerns tend to blur and accumulate accidental complexity. --- Documentation ------------- [](#documentation) GoalDocumentBuild a plugin from this boilerplate[HOW-TO-USE.md](HOW-TO-USE.md)Look up a field type or schema key[FIELDS.md](FIELDS.md)Understand architectural decisions[ADVANCED-TOPICS.md](ADVANCED-TOPICS.md)Contribute a change[CONTRIBUTING.md](CONTRIBUTING.md)See what changed[CHANGELOG.md](CHANGELOG.md)--- Built-in Examples ----------------- [](#built-in-examples) The repository includes working reference implementations demonstrating how the field engine, settings system, and MetaBox integration are intended to be used. Examples demonstrate: - Settings tab definitions - Field schema structure - Repeater field usage - Conditional field visibility - Media field configuration - MetaBox field integration See the example modules in: - `src/Settings/Tabs` - `src/MetaBox/Boxes` These examples are intentionally simple and serve as a baseline for building more complex plugins. --- Core Principles --------------- [](#core-principles) - Clear separation between admin, settings, and public runtime - Settings treated as a domain boundary - Predictable lifecycle behavior - Minimal magic and no hidden side effects - Constraints designed for long-term maintainability --- Hook Registration (v1.6.3+) --------------------------- [](#hook-registration-v163) The boilerplate uses a centralized Loader to register WordPress hooks. Feature classes do not call `add_action()` or `add_filter()` directly. Instead, hooks can be declared using one of two approaches. ### Declarative Hooks [](#declarative-hooks) Classes may define a `hooks()` method. Example: ``` public function hooks(): array { return [ 'action' => [ ['admin_init', 'boot'], ['admin_menu', 'register_menus'], ], 'filter' => [ ['plugin_action_links_' . plugin_basename(Plugin::file()), 'add_settings_link'], ], ]; } ``` The Loader reads this method and registers the hooks automatically. ### Manual Wiring [](#manual-wiring) For dynamic hooks or external handlers, classes may still register hooks explicitly: ``` public function register(Loader $loader): void { $loader->action("admin_post_{$prefix}reset", [new ResetSettings(), 'handle']); } ``` Both approaches can be used together. --- Design Goals ------------ [](#design-goals) This boilerplate is intentionally opinionated. It is designed to help developers build long-lived plugins without accumulating architectural debt. The project prioritizes: - deterministic behavior over convenience - explicit configuration over hidden automation - long-term maintainability over rapid prototyping - stable storage structures over dynamic schemas The goal is not to replace WordPress patterns, but to provide a structured starting point for plugins that are expected to evolve over time. --- Settings System (v1.3+) ----------------------- [](#settings-system-v13) The settings layer is now a structured, extensible system. ### Field Architecture [](#field-architecture) - Schema-driven `FieldDefinition` - Centralized `FieldRenderer` - Deterministic sanitization per field - Nested option handling - Extensible field pattern ### MetaBox Support (v1.3+) [](#metabox-support-v13) The field engine now powers both Settings and MetaBox modules. - Shared rendering layer - Shared sanitization pipeline - Field-type-aware save logic - Stable nested meta structure - Repeater fully supported in MetaBox context - Deterministic meta key namespacing per MetaBox - Registry-level ID validation - Template-scoped MetaBox registration Meta and Settings use the same core field abstraction. ### MetaBoxRepository (v1.5+) [](#metaboxrepository-v15) MetaBox persistence must go through `MetaBoxRepository`. Direct use of `get_post_meta()` or manual meta key construction is not supported. Meta keys are automatically namespaced as: *{PREFIX}{BOX\_ID}*{FIELD\_KEY} Repository guarantees deterministic key ownership and collision safety. ### Supported Fields [](#supported-fields) **Text-based** - text, email, url, password, hidden - textarea - date, time, datetime-local - editor (wp\_editor powered) **Numeric & Boolean** - number - range - checkbox **Choice** - select - multiselect - radio **Rich** - color (WP Color Picker) - media / image / file / document / audio / video / archive - media with `multiple: true` (ordered gallery — drag sort, per-item remove) - repeater (nested structured fields, all types) ### Editor Field [](#editor-field) The `editor` field is powered by WordPress `wp_editor()`. As of v1.6.4 the editor field is supported inside repeater rows. The field engine automatically manages TinyMCE lifecycle events to ensure: - unique editor IDs per repeater row - safe initialization when rows are created or duplicated - stable behavior during drag sorting --- Repeater Field -------------- [](#repeater-field) The repeater allows structured, sortable nested data. ### Features [](#features) - Collapsible rows (collapsed by default) - Drag & drop sorting with order persistence - Duplicate row support - Min / max limits - Independent row sanitization - Template-based rendering - Dashicon controls - Conditional field support Repeaters always store ordered arrays and never leak template markup into the runtime DOM. ### Storage Guarantees (v1.3+) [](#storage-guarantees-v13) - Template placeholder rows (`__index__`) are never persisted - Completely empty rows are removed automatically - Rows are reindexed numerically before persistence - Nested data structure remains deterministic and stable --- Media Field ----------- [](#media-field) Stores attachment IDs only. Supports: - Single selection (integer) - Multiple selection (ordered array) - Drag sorting (multiple mode) - Per-item removal (multiple mode) - Duplicate prevention in multiple mode - MIME type restriction support - Square preview layout Behavior adapts automatically based on `multiple: true`. Admin validation uses WordPress core notice styles to report duplicate selections or invalid file types. Storage format remains unchanged. --- Admin UI System --------------- [](#admin-ui-system) The admin interface is: - Fully scoped under `.wppb-admin` - Built on a 12-column CSS Grid layout - Powered by semantic design tokens - Safe from wp-admin style conflicts - Field type is injected as a CSS class on field wrappers Example: ``` 'class' => 'width-6', ``` Available widths: - width-1 → width-12 - Default: `width-4` for most fields; `width` (full) for editor, media, and repeater --- Folder Responsibilities ----------------------- [](#folder-responsibilities) DirectoryResponsibility`src/Admin`Admin UI, menus, and admin-only modules`src/Settings`Settings tabs and option persistence`src/MetaBox`MetaBox definitions, registry, and repository`src/Frontend`Frontend/runtime behavior`src/Core`Field engine, definitions, rendering, and support utilities`src/Lifecycle`Activation and deactivation logic`assets`CSS, JavaScript, and static assets`vendor`Bundled Composer dependenciesEach directory represents a deliberate architectural boundary. --- Stability Guarantees -------------------- [](#stability-guarantees) Starting with v1.0: - Public behavior is registered unconditionally - Admin configuration flows cleanly into runtime - Lifecycle behavior is predictable - Uninstall cleans up plugin-owned data - Plugin renaming does not break behavior - Distributed as a self-contained package Breaking these guarantees requires a major version bump. --- Versioning ---------- [](#versioning) Semantic Versioning is followed: - Patch → internal fixes - Minor → new features or backward-compatible structural improvements - Major → breaking changes to storage, APIs, or architectural guarantees --- Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on recent changes. --- Security -------- [](#security) If you discover any security-related issues, please email **** instead of using the issue tracker. --- Credits ------- [](#credits) - [Ulhas Vardhan Golchha](https://github.com/golchha21) --- *Initial work* See also the list of [contributors](https://github.com/golchha21/wp-plugin-boilerplate/graphs/contributors). --- License ------- [](#license) This project is licensed under the **GNU General Public License v2.0 or later (GPL-2.0-or-later)**. WordPress is licensed under the GPL, and any plugin that runs within WordPress and uses its APIs is required to be GPL-compatible. You are free to use, modify, and distribute this software under the terms of the GPL. See the [LICENSE](LICENSE) file for details. --- If this boilerplate has been useful to you, you can support its development here: [Buy me a coffee](https://www.buymeacoffee.com/golchha21) ### Health Score 43 — FairBetter than 91% of packages Maintenance89 Actively maintained with recent releases Popularity8 Limited adoption so far Community7 Small or concentrated contributor base Maturity58 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 22 Last Release 54d ago Major Versions 0.9.6 → 1.0.02026-02-06 ### Community Maintainers ![](https://www.gravatar.com/avatar/10a2b0e3d55aa79297b82f029d5340e34ee8aa3c29db57bb31780bcc4af947d0?d=identicon)[golchha21](/maintainers/golchha21) --- Top Contributors [![golchha21](https://avatars.githubusercontent.com/u/772400?v=4)](https://github.com/golchha21 "golchha21 (32 commits)") --- Tags boilerplatemetaboxphpplugin-boilerplatewordpresswordpress-developmentwordpress-plugin ### Embed Badge ![Health badge](/badges/golchha-wp-plugin-boilerplate/health.svg) ``` [![Health](https://phpackages.com/badges/golchha-wp-plugin-boilerplate/health.svg)](https://phpackages.com/packages/golchha-wp-plugin-boilerplate) ``` ### Alternatives [laravel/telescope An elegant debug assistant for the Laravel framework. 5.2k67.8M190](/packages/laravel-telescope)[laravel/passport Laravel Passport provides OAuth2 server support to Laravel. 3.4k85.0M529](/packages/laravel-passport)[spiral/roadrunner RoadRunner: High-performance PHP application server and process manager written in Go and powered with plugins 8.4k12.2M84](/packages/spiral-roadrunner)[nolimits4web/swiper Most modern mobile touch slider and framework with hardware accelerated transitions 41.8k177.2k1](/packages/nolimits4web-swiper)[laravel/dusk Laravel Dusk provides simple end-to-end testing and browser automation. 1.9k36.7M255](/packages/laravel-dusk)[laravel/prompts Add beautiful and user-friendly forms to your command-line applications. 708181.8M591](/packages/laravel-prompts) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)