WordPress powers over 40% of all websites, making it the world’s most popular content management system. This widespread use stems largely from WordPress’ flexibility and extensibility through plugins. Plugins allow developers to expand functionality without editing core code.
However, plugins have historically lacked standards for consistent structure, organization, and code quality. This results in complex plugins that become burdensome to maintain long-term.
The WordPress Plugin Boilerplate aims to solve these issues by providing an optimized framework for developing modern plugins. This comprehensive boilerplate offers conventions for file/folder structure, hook management, and logical segmentation of functionality.
In this guide, we’ll walk through the boilerplate components and how to configure them for your next plugin build.
Key Benefits
Integrating the boilerplate provides four major advantages:
Standardization – Plugins share consistent organization for easier collaboration and maintenance. Structure mirrors WordPress coding standards.
Code Quality – Established best practices are baked in, promoting reusable, reliable code right from the start.
Organization – Files and assets are logically grouped based on functionality into frontend, backend, shared resources, etc.
Easier Maintenance – Abstracted code and standardized hooks streamline updating and troubleshooting down the road.
Now let’s explore the boilerplate elements enabling these benefits.
File Structure Walkthrough
The GitHub repository organizes files for straightforward customization. Main folders and contents include:
Core Repository Files – Standard GitHub docs like README and CHANGELOG help onboard developers.
Plugin Folder – Trunk holds the actual plugin code and follows WordPress conventions.
Assets Folder – Stores screenshots and marketing assets for the WordPress directory listing.
Source Code – Found in the “/trunk” folder, segmented into public and admin groups. Shared functions kept in separate includes folder.
This structured foundation establishes defined locations for certain resources right from initialization.
Initial Setup
With files downloaded from GitHub, integrating the boilerplate consists of two key steps:
1. Local Environment – Create a local WordPress installation for development and testing. Options like MAMP, LocalWP, or DesktopServer.
2. Symlink Plugin – Symlink your local clone folder to enable edits without affecting the live site.
Following installation guide best practices helps avoid initial roadblocks. Consider enabling WP_DEBUG for extra insights.
Customization Process
Now for tailoring boilerplate to your particular project goals:
Plugin Details – Modify names, descriptions, and author details in the plugin header docblock.
Demo Content – Swap out or delete any demo element under “/trunk” for your own work.
Core Plugin Files – Main edits will happen in class-plugin-name.php and the public/admin specific files.
Carefully renaming and removing demo content eliminates potential confusion down the road.
Hooks and Filters
A primary strength of boilerplate is streamlined hooks and filters management under “/trunk/Includes”. Defined methods enable properly adding actions and filters in either public or admin contexts.
For example, to add a hook in the public side:
// Inside class-plugin-name-public.php
public function register_hooks() {
add_filter( 'the_content', array( $this, 'modify_content' ) );
}
public function modify_content( $content ) {
// Modify post content
return $modified_content;
}Review included hook examples to understand suggested implementation.
Frontend vs Backend
The boilerplate promotes separating public and admin facing code – utilizing class files dedicated for each.
Public – Handles frontend content, scripts, styles, and hooks.
Admin – Manages dashboard pages, settings, metaboxes, and other admin actions.
Keeping these concerns segmented improves organization and long-term maintenance.
Admin Dashboard Integration
For building out custom plugin pages and settings in the WordPress dashboard:
1. Register Menu – Load admin menu with add_menu_page() in class-plugin-name-admin.php.
2. Settings API – Leverage Settings API for saved options under the registered page.
3. Assets – Enqueue admin specific CSS/JS files.
See the admin class file code examples for implementation details.
Managing External Dependencies
Third party code dependencies are placed in the “/trunk/Includes/Vendors” folder. A primary example is TGM Plugin Activation for suggesting other plugins.
To add TGM, first download the latest TGM class file and include it under “/trunk/Includes”. Then instantiate and configure it by following the examples in class-plugin-name.php.
Best Practices for Development
When building out plugins backed by boilerplate, keep these development practices in mind:
Logical Segmentation – Group shared functions under includes, admin under /admin, etc.
Inline Documentation – Use docblocks and comments liberally for ongoing understanding.
Namespacing – Namespace classes and method names appropriately based on functionality and hierarchy.
Hook Management – Follow defined hook patterns in admin and public class files for consistency.
Active Testing – Continuously test during development to catch issues early.
Tight adherence to boilerplate conventions ensures clean and maintainable code over time.
Migrating Existing Plugins
For plugins created outside boilerplate, migration is straightforward:
- Integrate folder structure by creating /admin, /public, /includes folders.
- Shift existing files to appropriate new locations.
- Include main class files and instantiate public/admin classes.
- Standardize hooks by moving to public/admin class methods.
Even partially integrating some boilerplate conventions can improve legacy code.
Comparing Boilerplate Alternatives
While this boilerplate is very full-featured, developers may want to evaluate other similar projects like:
- WPPB – A more barebones starter alternative.
- WP Skeleton – Another basic framework for rapid building.
- Plugin Factory – Heavier on built in tools and settings panels.
Consider complexity required and personal preferences when selecting.
Conclusion
The WordPress Plugin Boilerplate provides an optimized foundation for plugins of all types to promote quality and consistency. While simple plugins may not require this robust scaffolding, more complex projects can benefit tremendously.
By investing upfront in the standardized structure, hooks management, and segmented architecture – long term maintenance and collaboration is streamlined. Use this guide to get started configuring the boilerplate resources for your next build!
