Download the PHP package webmoves/plugin-base without Composer

Web Moves Plugin Base

⚠️Please Note: This library is currently in early development and is NOT suitable for production use.

It is not advised to deploy plugins built with this library to production WordPress sites until a stable version is released.

A modern WordPress plugin base that provides a solid foundation for creating well-structured, maintainable WordPress plugins. This library uses a service-based architecture with dependency injection, organized hook management, and clean separation of concerns.

Overview

Web Moves Plugin Base is designed to help developers create WordPress plugins with:

• Clean Architecture: Separation of concerns and modular design
• Modern PHP Practices: Type safety, dependency injection, and PSR standards
• Developer Experience: Streamlined workflows and reduced boilerplate code
• Testability: Easy unit testing with PHPUnit

Requirements

• PHP 8.3 or higher
• WordPress 6.0 or higher
• Composer

Installation

1. Clone the repository to your WordPress plugins directory:

2. Install dependencies using Composer:

3. Activate the plugin in the WordPress admin panel.

Architecture

The Plugin Base follows a service-based architecture with several key components:

1. PluginBase

Base class for plugins, providing core functionality:

• Singleton pattern with init_plugin and get_instance methods
• Manages plugin core
• Can be extended by subclasses that override initialize() and get_services()

2. PluginCore

Manages the plugin's core functionality:

• Loads configuration
• Provides service container functionality
• Handles plugin lifecycle events
• Manages components
• Provides access to plugin metadata

3. Plugin Metadata

The Plugin Base has a PluginMetadata interface and DefaultPluginMetadata implementation for managing plugin metadata:

• Separates plugin metadata from the plugin core
• Provides methods for accessing plugin information:
  • Name, version, text domain
  • Description, author, URIs
  • Required WordPress and PHP versions
  • Required plugins
  • Plugin file paths and slugs
• Makes it easier to access plugin information throughout the codebase
• Available for dependency injection

4. Configuration System

The Plugin Base has a robust configuration system:

• Loads configuration from the plugin.config.php file
• Supports dot notation for accessing configuration values
• Provides methods for getting, setting, and checking configuration values
• Has specific methods for retrieving common configuration sections:
  • Required plugins
  • Services
  • Components
  • Logging configuration

Example configuration file structure:

Example configuration usage:

5. Settings

Manages plugin settings:

• SettingsProvider: Interface for providing settings configurations
• SettingsManager: Interface for managing settings operations
• AbstractSettingsProvider: Base class for settings providers

6. Components

Modular functionality via traits:

• HasAction: WordPress action hooks
• HasAdminMenu: Admin menu functionality
• HasAjax: AJAX functionality
• HasAssets: Asset management
• HasCli: WP-CLI commands
• HasFilter: WordPress filter hooks
• HasMetaBox: Meta box functionality
• HasPostType: Custom post type functionality
• HasRestApi: REST API functionality
• HasSchedule: Scheduled tasks
• HasShortcode: Shortcode functionality
• HasWidget: Widget functionality

7. Lifecycle Management

The Plugin Base has a Lifecycle enum that defines different plugin lifecycle events:

1. Plugin management events:

   • INSTALL: When the plugin is first installed
   • ACTIVATE: When the plugin is activated
   • DEACTIVATE: When the plugin is deactivated
   • UNINSTALL: When the plugin is uninstalled/deleted
2. Runtime lifecycle events:
   • BOOTSTRAP: Very early, before WordPress fully loads (plugins_loaded hook)
   • INIT: Standard init hook
   • ADMIN_INIT: Admin-specific initialization
   • READY: After everything is loaded (wp_loaded hook)

Components are registered for specific lifecycle events by implementing the register_on() method.

8. Component Registration

The Plugin Base uses a component-based architecture where functionality is encapsulated in classes that implement the Component interface. This interface defines four key methods:

Component Interface Methods

• register(): This method is called when a component is being registered. It's where the component should set up its WordPress hooks, filters, and other initialization code. This is the main entry point for a component's functionality.

• can_register(): This method acts as a conditional gate that determines whether a component should be registered. It allows components to check conditions (like user roles, plugin settings, or environment variables) before registering. If this method returns false, the component will not be registered, even if it's added to the component manager.

• get_priority(): This method determines the order in which components are registered. Components with lower priority values are registered first. This is useful when certain components depend on others being registered first.

• register_on(): This method determines which lifecycle event the component should be registered on. It returns a Lifecycle enum value.

Component Registration Process

1. Components are added to the ComponentManager via the add() method, either:

   • Manually through PluginCoreInterface::get_component_manager()->add() method
   • Automatically when a service implementing Component is added to the container with PluginCore::set()
   • Through configuration in the plugin.config.php file
2. When a lifecycle event occurs, the ComponentManager:
   • Gets all components for that specific lifecycle
   • Sorts them by priority
   • For each component, checks if it can be registered using can_register()
   • If can_register() returns true, calls the component's register() method

The ComponentRegistration Trait

The Plugin Base includes a ComponentRegistration trait that simplifies component implementation:

1. Automatic Registration: The trait provides a final implementation of the register() method required by Component, so you don't need to implement it yourself.

2. Trait Discovery: It automatically discovers all capability traits used by the component (like HasAction, HasFilter, etc.) and calls their registration methods.

3. Registration Hooks: It provides hooks for customizing the registration process:

   • before_register(): Called before trait registration, useful for setup tasks
   • after_register(): Called after trait registration, useful for adding additional hooks
4. One-time Registration: It ensures traits are only initialized once with an internal flag.

When using capability traits like HasAction or HasFilter, you must also use the ComponentRegistration trait. Each capability trait requires you to implement specific methods:

This approach allows you to create components by combining traits for different WordPress functionalities without writing boilerplate code.

Example Component

Example Component Using Traits

Here's a more creative example that uses multiple traits to create a component for displaying customizable notices in WordPress. This demonstrates how to build reusable components:

To use this component, you would define it in your plugin. The key benefit is that you can create multiple instances with different configurations:

Note: Components returned as services in the get_services() method are automatically registered with the plugin core. There's no need to call add() explicitly for these components.

This approach demonstrates the reusability of components:

1. Each instance displays a different type of notice (info, warning, error)
2. Each instance shows a different message
3. Some instances are dismissible, others are not
4. Different instances can hook into different admin hooks
5. All instances share the same registration logic through the traits

The power of this design is that you can easily create multiple notice types with different configurations without modifying the component's code. This promotes reusability and makes your components more flexible and maintainable.

Configuration

The plugin uses a configuration system for various settings:

Configuration Files

Configuration files are stored in the /config directory:

• Main Configuration:

  • /config/plugin.config.php - Main configuration file
• Configuration Structure:

Accessing Configuration

You can access configuration values using dot notation:

Creating a New Plugin

To create a new plugin using this Plugin Base:

1. Create a new class that extends Plugin
2. Implement the initialize() method to set up your plugin
3. Implement the get_services() method to register your services
4. Call YourPlugin::init_plugin(__FILE__) in your main plugin file

Example:

Your plugin class:

Features

Dependency Injection

The Plugin Base uses PHP-DI for dependency injection. Services can be registered in three ways:

1. In the get_services() method of your plugin class:

2. In the configuration file:

3. At runtime using the set() method:

Settings Management

Type-safe settings with automatic prefixing and validation:

Admin Pages

The Plugin Base provides a flexible system for creating admin pages in the WordPress dashboard:

Types of Admin Pages

1. Menu Admin Pages: Top-level menu items in the WordPress admin
2. Settings Pages: Pages that display and manage plugin settings
3. Custom Admin Pages: Custom pages with specialized functionality

Creating a Menu Admin Page

To create a top-level menu page:

This creates a top-level menu item in the WordPress admin. You can customize the menu by passing additional parameters to the constructor:

Creating a Settings Page

To create a settings page that displays and manages plugin settings:

Creating a Custom Admin Page

To create a custom admin page with specialized functionality:

Admin Page Registration Process

Admin pages implement the Component interface and use the HasAdminMenu trait, which:

1. Registers the page with WordPress during the admin_menu action
2. Handles the rendering process with pre-render setup
3. Manages page hooks and capabilities

The can_register() method ensures pages are only registered in the admin area and when the user has the required capability.

Claude Code Integration

This framework includes Claude Code skills for scaffolding new components. To use them in your plugin project:

Available Skills

• /scaffold - Scaffolds new components (post types, taxonomies, services, commands, controllers, admin pages)

The skill automatically detects your namespace from composer.json and generates properly structured code.

See .claude/README.md for detailed usage instructions.

License

This project is licensed under the GPL v2 or later.