The problem and introducing WPPF
If you've built more than a few WordPress plugins, you've probably run into the same pattern.
A plugin starts clean, but as features grow it slowly becomes a mix of
- scattered
add_actioncalls, - copied boilerplate code,
- and an
includes/folder full of dissimilar items.
After dealing with this enough times while building client plugins, I decided to standardize how I structure my projects.
That eventually became the WordPress Plugin Framework (WPPF).
Table of contents
- Why this happens
- My solution
- The core idea: Modules
- CLI scaffolding
- Versioned namespaces
- Who this framework is for
- Try it out
Why this happens
One of the strengths of WordPress plugin development is also one of its biggest challenges: flexibility.
WordPress doesn’t impose a strict project structure on plugin developers. In many ways that’s a good thing, since it lowers the barrier to entry and lets developers solve problems however they want.
But along with that freedom has come little guidance around how plugins should be organized.
WordPress gives you incredible flexibility, but large plugins benefit from a little structure.
As plugins grow, it can be common to see things like
- hooks scattered across files top to bottom,
- features implemented wherever it was convenient at the time,
- utility functions copied between projects,
- or folders like
includes/slowly becoming a "stuff drawer".
None of this is necessarily wrong, but over time it can make a plugin harder to understand and maintain.
After running into this pattern repeatedly, I started wondering:
"What would a consistent, feature-oriented structure for WordPress plugins look like?"
That question eventually led to the framework described in the rest of this article.
My solution
After running into these problems repeatedly, I started standardizing how I structured my own plugins.
Instead of organizing code primarily by what it is (classes, templates, utilities, etc.), I started organizing plugins by what they do.
In other words, a feature-based architecture.
A plugin might contain things like
- a REST API,
- admin UI screens,
- custom post types,
- scheduled tasks,
- or integrations with other platforms/plugins.
Each of these areas can be treated as a feature module that owns its own hooks, logic, and supporting code.
That approach turned out to make plugins significantly easier to reason about.
Instead of asking,
"Where is the code that registers this feature?",
you can usually find it directly inside the module responsible for that behavior.
Over time, this approach evolved into a small framework while working at DesignInk Digital that I now call the WordPress Plugin Framework.
The framework focuses on a few practical goals:
- Organizing plugin code around feature modules.
- Keeping WordPress hooks close to the feature they belong to.
- Using a custom PSR-4 autoloader for predictable project structure.
- Providing CLI scaffolding for common plugin components.
The result is a structure that still feels very “WordPress”, but scales better as plugins grow.
The core idea: Modules
The central concept in WPPF is the module.
A module represents a single feature area within a plugin and acts as the place where that feature connects to WordPress.
Instead of scattering hooks across multiple files, a module becomes the entry point for a feature's behavior.
For example, if a plugin exposes a REST API, the module responsible for that feature might look like this:
class My_API extends Module {
public static function construct(): void {
add_action('rest_api_init', [__CLASS__, 'init']);
}
public static function init(): void {
// Register routes, controllers, permissions, etc.
}
}
When the plugin loads, the framework automatically calls each module's construct() method and registers the hooks needed for that feature.
This approach keeps the WordPress wiring close to the feature itself.
Instead of searching through multiple files for where a hook is registered, you can usually find it directly inside the module responsible for that functionality.
As plugins grow, this makes it much easier to reason about how different parts of the plugin interact with WordPress.
Modules help keep plugins organized around behavior instead of file types.
Scaffolding common plugin components
One of the most repetitive parts of plugin development is creating the same structural pieces over and over.
Things like
- bootstrapping plugin files,
- registering custom post types,
- creating meta boxes,
- and configuring admin screens.
Even with a good architecture in place, these components still require a fair amount of setup.
To reduce that friction, WPPF includes a CLI tool that can scaffold common plugin components.
For example, creating a new plugin can be done with:
vendor/bin/wppf make:plugin
The CLI generates the basic structure needed to start building a plugin using the framework.
The other commands can generate other components such as
- custom post types,
- meta boxes,
- admin modules,
- and other common plugin scaffolding.
This helps eliminate a lot of the repetitive setup work that tends to happen when starting a new plugin or adding a new feature.
Instead of copying code from previous projects, you can generate a consistent starting point and focus on the actual functionality you want to build.
The goal is to remove as much boilerplate as possible while keeping plugin code predictable and organized.
Versioned namespaces
One of the challenges of building reusable libraries in the WordPress ecosystem is that multiple plugins can exist in the same runtime environment.
Unlike many modern PHP applications where dependencies are centrally managed, WordPress sites often load many independent plugins at once. If two plugins include different versions of the same framework or library, conflicts can occur.
To help avoid this problem, WPPF uses versioned namespaces.
Instead of a static namespace like
WPPF\Plugin,
each framework release is namespaced with its version. For example,
WPPF\v1_2_2\Plugin.
This means different plugins can safely ship with different versions of the framework without creating conflicts.
In practice, this allows plugin developers to
- upgrade framework versions gradually,
- avoid dependency conflicts across plugins,
- and maintain stability on sites running multiple custom plugins.
The goal is to make the framework easier to adopt without forcing every plugin on a site to upgrade at the same time.
This design helps keep plugins isolated from each other while still allowing developers to benefit from shared framework improvements.
Versioned namespaces
One of the challenges of building reusable libraries in the WordPress ecosystem is that multiple plugins can exist in the same runtime environment.
Unlike many modern PHP applications where dependencies are centrally managed, WordPress sites often load many independent plugins at once. If two plugins include different versions of the same framework or library, conflicts can occur.
To help avoid this problem, WPPF uses versioned namespaces.
Instead of a static namespace like
WPPF\Plugin,
each framework release is namespaced with its version. For example,
WPPF\v1_2_2\Plugin.
This means different plugins can safely ship with different versions of the framework without creating conflicts.
In practice, this allows plugin developers to
- upgrade framework versions gradually,
- avoid dependency conflicts across plugins,
- and maintain stability on sites running multiple custom plugins.
The goal is to make the framework easier to adopt without forcing every plugin on a site to upgrade at the same time.
This design helps keep plugins isolated from each other while still allowing developers to benefit from shared framework improvements.
Try it out
If you're interested in exploring the framework or trying it in your own projects, you can find the documentation and source code here:
Documentation
https://wp-plugin-framework.codeflower.io/
GitHub Repository
https://github.com/kyle-niemiec/wp-plugin-framework/
The project is open source, and feedback from other plugin developers is always welcome.
I'm particularly interested in hearing how other developers structure larger plugins and what kinds of tooling would make plugin development easier.
If you end up trying the framework or have ideas for improving it, feel free to open an issue or start a discussion on GitHub.
WordPress plugin development is incredibly flexible and this framework is simply an attempt to add a little more structure where it helps.
Top comments (1)
If anyone wants to explore the framework structure quickly, the docs walk through a simple plugin setup.
wp-plugin-framework.codeflower.io/