Download the PHP package codemystify/wordforge without Composer

WordForge

A Laravel-inspired routing system for WordPress REST API with PHP 8 compatibility.

Features

• Laravel-style route definitions
• Parameter constraints and validation
• Route groups and middleware
• Resource routing
• Named routes with URL generation

Usage

Basic Routes

Route Groups

Resource Routes

Named Routes

Parameter Conversion

WordForge automatically converts Laravel-style route parameters to WordPress REST API compatible format:

Middleware

Installation

Requirements

• PHP 8.0 or higher
• WordPress 5.5 or higher: An Opinionated SLIM MVC architecture for building WordPress Plugins

WordForge is a simple, opinionated SLIM MVC framework for WordPress that brings structure to plugin development. While WordPress is a powerful platform, plugins often become unwieldy and disorganized as they grow in complexity. WordForge addresses this problem by providing a clear architectural pattern inspired by Laravel, but with zero third-party dependencies.

Table of Contents

• Why WordForge?
• Features
• Installation
• Getting Started
  • Basic Setup
  • Creating Routes
  • Route Parameter Constraints
  • Creating Controllers
  • Form Request Validation
  • Using the Query Builder
  • Middleware
  • Helper Functions
• Advanced Usage
  • Service Providers
  • Service Management
  • Custom Validation Rules
  • Working with Views
  • Assets and URLs
  • Configuration Management
• Project Structure
• Philosophy
• Limitations
• Testing
• License
• Credits

Why WordForge?

WordPress plugin development often lacks structure. As plugins grow, code becomes scattered across files with no clear organization. WordForge addresses this problem by providing:

• Clear Structure: Know exactly where to put your code
• Zero Dependencies: No external packages required beyond WordPress core
• Laravel-inspired Patterns: Familiar patterns for developers who know Laravel
• Maintainable Code: Easier to maintain and extend your plugins
• Focused Simplicity: Intentionally lightweight - just what you need

Features

• Structured MVC Architecture with controllers, views, and a simple model layer
• Laravel-style Routing with named routes, route groups, and resource controllers
• Clean Query Builder for more readable database interactions
• Form Request Validation to simplify data validation
• Service Providers with hook-based initialization, similar to Laravel's service container
• Facades for cleaner static interfaces
• Simple Middleware System for filtering HTTP requests
• WordPress REST API Integration with elegant request/response handling
• Configuration Management with environment-aware settings
• Service Management for organizing dependencies without a full container

Installation

You can install the package via composer:

Getting Started

Basic Setup

After installing the package, you need to initialize WordForge in your plugin with just one line:

That's it! The framework will:

1. Automatically detect if it's running from a vendor directory
2. Load configuration from your plugin's config directory
3. Register service providers from your config
4. Load routes from your routes directory
5. Handle asset URLs, views, and more

Creating Routes

Create a routes/api.php file in your plugin directory:

Important: Using Route Facade vs. Router Class

Always use the Route facade rather than the Router class directly in your route definitions:

Troubleshooting Routes

If your routes aren't working after registering your plugin and service provider:

1. Check Namespace Configuration: Make sure your API namespace is properly set in your config:

2. Route Service Provider: Ensure your RouteServiceProvider is properly registered and sets the namespace before routes are loaded:

3. Bootstrap Timing: Bootstrap WordForge early in your plugin:

4. Debug Mode: To diagnose route issues, enable WordPress debug mode:

5. Access Routes: Routes are available at:

Route Parameter Constraints

WordForge provides a Laravel-inspired way to define route parameter constraints using the where method. When building WordPress REST API endpoints, you should use proper regex patterns to constrain your route parameters for security and validation.

Common Regex Patterns for Route Parameters

While WordPress REST API normally requires complex regex syntax, WordForge simplifies this to be more Laravel-like. Here are the recommended patterns to use with the where method:

WordPress vs WordForge Pattern Syntax

WordForge simplifies WordPress's complex regex parameter handling:

1. WordPress REST API requires patterns in the format: '(?P<parameter_name>pattern)'
2. WordForge uses a Laravel-inspired syntax: ->where('parameter_name', 'pattern')

Behind the scenes, WordForge transforms your simple constraints into the complex WordPress format, making your routes more readable and maintainable.

Default Parameter Patterns

WordForge provides sensible defaults for common parameter names:

• id parameters: matches digits (\d+)
• slug parameters: matches lowercase alphanumeric characters and dashes ([a-z0-9-]+)
• uuid parameters: matches UUID format
• Other parameters: matches anything except for slashes ([^/]+)

Best Practices

For consistency and security, we recommend following these patterns:

• For ID fields: \d+ or [0-9]+
• For slug fields: [a-z0-9-]+
• For alphanumeric fields: [a-zA-Z0-9]+
• For named parameters: always apply appropriate constraints with the where method

Using these patterns helps ensure your routes work correctly and securely with both WordForge and the WordPress REST API.

Creating Controllers

Create a controller in your plugin:

Form Request Validation

Create a form request for validation:

And use it in your controller:

Using the Query Builder

WordForge includes a powerful query builder inspired by Laravel's Eloquent:

Available Query Methods

The query builder provides many methods for constructing queries:

• Selection: select(), selectRaw(), distinct()
• Joins: join(), leftJoin(), rightJoin()
• Where Clauses: where(), orWhere(), whereIn(), whereNotIn(), whereNull(), whereNotNull(), whereBetween(), whereNotBetween(), whereLike()
• Ordering: orderBy(), orderByDesc(), orderByRaw()
• Grouping: groupBy(), having()
• Limiting: limit(), offset(), take(), skip(), paginate()
• Aggregates: count(), max(), min(), avg(), sum()
• Transactions: transaction(), beginTransaction(), commit(), rollback()

Middleware

Create middleware to filter requests:

Register middleware in your routes:

Helper Functions

WordForge provides several helper functions to simplify common tasks:

Advanced Usage

Service Providers

Service providers in WordForge are now even more powerful with hook-based initialization:

Register the service provider in your config file:

Service Management

WordForge includes a lightweight service manager for managing dependencies:

Creating Custom Validation Rules

Create a custom validation rule:

Use the custom rule in a form request:

Working with Views

Create view files in your plugin's views directory:

Render views in your controller:

Assets and URLs

Generate URLs to assets in your plugin:

Configuration Management

Create configuration files in your plugin's config directory:

Access configuration values:

Project Structure

Here's a recommended project structure for a WordForge-based plugin:

Philosophy

WordForge is built on several key principles:

1. Structure Over Convention: WordPress often relies on loosely structured code. WordForge provides clear patterns for organizing your code.

2. Simplicity First: The framework intentionally avoids complex features and dependencies. It's designed to be easy to understand and modify.

3. WordPress Native: While bringing Laravel-inspired patterns, WordForge remains true to WordPress at its core, working with WordPress hooks and APIs rather than against them.

4. Build Only What You Need: The framework provides a foundation, but you're encouraged to extend only the parts you need for your specific project.

5. No Magic: WordForge avoids "magical" behaviors that hide implementation details. The code is straightforward and traceable.

Limitations

WordForge is intentionally lightweight and doesn't try to solve every problem:

• It's not a full replacement for complex WordPress plugin architectures
• It doesn't introduce ORM or complex database abstraction
• It doesn't modify WordPress core behavior
• It's focused on backend structure rather than frontend rendering

Testing

WordForge includes a testing setup that makes it easier to test your plugin:

1. Set up PHPUnit in your plugin:

2. Create a PHPUnit configuration file:

3. Create a bootstrap file for your tests:

4. Write your tests:

5. Run your tests:

License

The MIT License (MIT). Please see License File for more information.

Credits

• CodeMystify Team