$icon = $meta->get_extension('my-plugin:icon');
$data = $meta->to_array(); // Serializable array for REST
}
```
This works for both callback-based and class-based actions uniformly.
## Common Pitfalls
### Don't Modify Context Expecting Persistence
```php
// ❌ Wrong - context changes don't persist between rules
Rules::register_action('bad_action', function($args, Context $context) {
$context->set('custom_value', 'modified');
// This change is lost after the action completes!
});
// ✅ Correct - use external state
Rules::register_action('good_action', function($args, Context $context) {
update_option('custom_value', 'modified');
// Or use globals, database, cache, etc.
});
```
### Don't Perform Heavy Operations Without Caching
```php
// ❌ Bad - runs on every execution
Rules::register_action('slow_action', function($args, Context $context) {
$data = expensive_api_call();
process_data($data);
});
// ✅ Good - cache expensive operations
Rules::register_action('cached_action', function($args, Context $context) {
$data = get_transient('cached_data');
if (false === $data) {
$data = expensive_api_call();
set_transient('cached_data', $data, HOUR_IN_SECONDS);
}
process_data($data);
});
```
## Next Steps
- **[Custom Conditions](/docs/millirules/03-customization/01-custom-conditions)** - Create conditional logic
- **[Built-in Actions Reference](/docs/millirules/05-reference/02-actions)** - See available actions
- **[Placeholder System](/docs/millirules/02-core-concepts/05-placeholders)** - Dynamic value resolution
- **[API Reference](/docs/millirules/05-reference/03-api)** - Complete API documentation
---
Canonical: https://www.millipress.com/docs/millirules/03-customization/03-custom-packages
---
title: 'Creating Custom Packages'
description: 'Bundle custom conditions, actions, context providers, and placeholder resolvers into reusable MilliRules packages, with a complete PHP membership example.'
menu_order: 30
---
# Creating Custom Packages
Custom packages are the ultimate way to extend MilliRules. They let you bundle conditions, actions, context data, and placeholder resolvers into reusable, self-contained modules. This guide shows you how to create packages that integrate seamlessly with MilliRules.
## Why Create Custom Packages?
Custom packages enable you to:
- **Bundle related functionality** - Group conditions and actions by domain
- **Provide context data** - Make data available to all rules
- **Add placeholder resolvers** - Enable dynamic values in rules
- **Integrate third-party services** - Connect external APIs and systems
- **Create reusable libraries** - Share packages across projects
- **Maintain clean separation** - Keep code organized by concern
## Package Structure
A complete custom package includes:
```
MyCustomPackage/
├── MyCustomPackage.php # Package class (implements PackageInterface)
├── Conditions/ # Condition classes
│ ├── CustomCondition1.php
│ └── CustomCondition2.php
├── Actions/ # Action classes
│ ├── CustomAction1.php
│ └── CustomAction2.php
└── PlaceholderResolver.php # Optional placeholder resolver
```
---
## Implementing PackageInterface
All packages must implement `PackageInterface`:
```php
namespace MilliRules\Packages;
use MilliRules\Context;
interface PackageInterface {
public function get_name(): string;
public function get_namespaces(): array;
public function is_available(): bool;
public function get_required_packages(): array;
public function register_providers(Context $context): void;
public function get_placeholder_resolver(Context $context);
public function register_rule(array $rule, array $metadata);
public function execute_rules(array $rules, Context $context): array;
}
```
---
## Basic Custom Package
### Minimal Package Implementation
```php
namespace MyPlugin\Packages;
use MilliRules\Packages\BasePackage;
class MyCustomPackage extends BasePackage {
/**
* Package name (must be unique)
*/
public function get_name(): string {
return 'MyCustom';
}
/**
* Namespaces for conditions and actions
*/
public function get_namespaces(): array {
return [
'MyPlugin\Packages\MyCustom\Conditions',
'MyPlugin\Packages\MyCustom\Actions',
];
}
/**
* Check if package can be used in current environment
*/
public function is_available(): bool {
// Example: check if required functions exist
return function_exists('my_required_function');
}
}
```
### Registering the Package
```php
use MilliRules\MilliRules;
use MyPlugin\Packages\MyCustomPackage;
// Register custom package
$custom_package = new MyCustomPackage();
MilliRules::init(null, [$custom_package]);
// Or let MilliRules auto-discover (if registered globally)
MilliRules::init();
```
---
## Registering Context Providers
Packages register context providers that load data lazily when needed. This improves performance by only loading data that rules actually use.
### Simple Context Provider
```php
use MilliRules\Context;
public function register_providers(Context $context): void {
// Register a simple provider that loads on-demand
$context->register_provider('my_custom', function() {
return [
'my_custom' => [
'value1' => get_option('my_option_1'),
'value2' => get_option('my_option_2'),
'timestamp' => time(),
],
];
});
}
```
**Benefit**: Data is only retrieved when `$context->get('my_custom.value1')` is called.
### Class-Based Context Provider
A context placed in your package's `Contexts` namespace is discovered automatically, and — unlike a closure — it can describe itself to the placeholder catalog returned by `Rules::get_all_placeholder_metas()`.
```php
namespace MyPlugin\Contexts;
use MilliRules\Contexts\BaseContext;
class Tenant extends BaseContext {
public function get_key(): string {
return 'tenant';
}
// Shown in rule-builder UIs. Defaults to the key.
public function get_label(): string {
return 'Tenant';
}
// One sentence naming a concrete {category.key}. Read by a person picking
// a placeholder and by AI clients choosing one. Defaults to ''.
public function get_description(): string {
return 'The current tenant, for example {tenant.plan}.';
}
// The keys {tenant.*} accepts. Return an empty array (the default) when
// the key is chosen by the caller, as with a cookie name.
public function get_keys(): array {
return ['id', 'plan', 'seats'];
}
// Skipped everywhere if the environment can't answer it.
public function is_available(): bool {
return function_exists('my_plugin_current_tenant');
}
protected function build(): array {
$tenant = my_plugin_current_tenant();
return [
'tenant' => [
'id' => $tenant->id,
'plan' => $tenant->plan,
'seats' => $tenant->seats,
],
];
}
}
```
**Declare `get_keys()` whenever the set is closed.** An unresolvable placeholder is left in the value verbatim rather than raising an error, so `{tenant.pln}` would silently become the literal string `{tenant.pln}` instead of the plan. Declaring the keys lets a rule builder reject the typo before the rule is stored.
Return keys as a **fixed list**, not one derived from `build()`, unless `build()` returns the same shape unconditionally — a catalog whose shape changed with the current request would be useless for validating a stored rule.
### Dynamic Context Provider
```php
use MilliRules\Context;
public function register_providers(Context $context): void {
// Register provider that loads complex data on-demand
$context->register_provider('my_custom', function() {
$user_data = [];
if (is_user_logged_in()) {
$user_id = get_current_user_id();
$user_data = [
'id' => $user_id,
'meta' => get_user_meta($user_id),
'purchases' => $this->get_user_purchases($user_id),
];
}
return [
'my_custom' => [
'user' => $user_data,
'site' => [
'name' => get_bloginfo('name'),
'url' => home_url(),
],
'stats' => [
'total_posts' => wp_count_posts()->publish,
'total_users' => count_users()['total_users'],
],
],
];
});
}
private function get_user_purchases($user_id) {
global $wpdb;
return $wpdb->get_results($wpdb->prepare(
"SELECT * FROM {$wpdb->prefix}purchases WHERE user_id = %d",
$user_id
));
}
```
**Benefit**: Expensive database queries and WordPress functions only execute when needed.
### Context Provider with External API
```php
use MilliRules\Context;
public function register_providers(Context $context): void {
// Register provider that loads API data on-demand
$context->register_provider('my_custom', function() {
// Cache expensive API calls
$api_data = get_transient('my_custom_api_data');
if ($api_data === false) {
$response = wp_remote_get('https://api.example.com/data', [
'timeout' => 10,
'headers' => ['Authorization' => 'Bearer ' . $this->get_api_key()],
]);
if (!is_wp_error($response)) {
$api_data = json_decode(wp_remote_retrieve_body($response), true);
set_transient('my_custom_api_data', $api_data, 300); // Cache 5 minutes
} else {
$api_data = [];
}
}
return [
'my_custom' => [
'api' => $api_data,
'cached_at' => get_transient('my_custom_api_data_time') ?: time(),
],
];
});
}
```
**Benefit**: API calls only execute if a rule actually needs the API data.
---
## Creating Package Conditions
Package conditions extend the available condition types.
### Simple Package Condition
```php
namespace MyPlugin\Packages\MyCustom\Conditions;
use MilliRules\Conditions\BaseCondition;
use MilliRules\Context;
class UserLevelCondition extends BaseCondition {
protected function get_actual_value(Context $context) {
$context->load('user');
$user_id = $context->get('user.id', 0);
if (!$user_id) {
return 0;
}
// Get custom user level
return (int) get_user_meta($user_id, 'user_level', true);
}
public function get_type(): string {
return 'user_level';
}
}
```
**Usage**:
```php
Rules::create('premium_users')
->when()
->custom('user_level', ['value' => 5, 'operator' => '>='])
->then()
->custom('show_premium_content')
->register();
```
### Condition Using Package Context
```php
namespace MyPlugin\Packages\MyCustom\Conditions;
use MilliRules\Conditions\BaseCondition;
use MilliRules\Context;
class PurchaseCountCondition extends BaseCondition {
protected function get_actual_value(Context $context) {
// Load package context data
$context->load('my_custom');
// Use data from package context
$purchases = $context->get('my_custom.user.purchases', []);
return count($purchases);
}
public function get_type(): string {
return 'purchase_count';
}
}
```
---
## Creating Package Actions
Package actions provide functionality specific to your package's domain.
### Simple Package Action
```php
namespace MyPlugin\Packages\MyCustom\Actions;
use MilliRules\Actions\BaseAction;
use MilliRules\Context;
class UpdateUserLevelAction extends BaseAction {
public function execute(Context $context): void {
$context->load('user');
$user_id = $context->get('user.id', 0);
$level = $this->config['level'] ?? 1;
if (!$user_id) {
error_log('UpdateUserLevelAction: No user logged in');
return;
}
update_user_meta($user_id, 'user_level', $level);
error_log("Updated user {$user_id} to level {$level}");
}
public function get_type(): string {
return 'update_user_level';
}
}
```
### Action with Placeholder Support
```php
namespace MyPlugin\Packages\MyCustom\Actions;
use MilliRules\Actions\BaseAction;
use MilliRules\Context;
class SendNotificationAction extends BaseAction {
public function execute(Context $context): void {
// Resolve placeholders
$message = $this->resolve_value($this->config['message'] ?? '');
$recipient = $this->resolve_value($this->config['to'] ?? '');
// Send notification
$this->send_notification($recipient, $message);
}
private function send_notification($to, $message) {
// Implementation...
wp_mail($to, 'Notification', $message);
}
public function get_type(): string {
return 'send_notification';
}
}
```
---
## Adding Placeholder Resolvers
Placeholder resolvers enable dynamic values in rules.
### Basic Placeholder Resolver
```php
use MilliRules\Context;
public function get_placeholder_resolver(Context $context) {
return function($placeholder_parts) use ($context) {
// $placeholder_parts = ['my_custom', 'category', 'key']
// From placeholder: {my_custom.category.key}
if ($placeholder_parts[0] !== 'my_custom') {
return null; // Not for this package
}
// Load context data if not already loaded
$context->load('my_custom');
// Convert parts to dot notation path
$path = implode('.', $placeholder_parts);
// Get value from context
$value = $context->get($path, '');
return is_scalar($value) ? (string) $value : '';
};
}
```
**Usage**:
```php
Rules::create('use_custom_placeholder')
->when()->request_url('/api/*')
->then()
->custom('log', [
'message' => 'Site: {my_custom.site.name}, Users: {my_custom.stats.total_users}'
])
->register();
```
### Advanced Placeholder Resolver
```php
use MilliRules\Context;
public function get_placeholder_resolver(Context $context) {
return function($placeholder_parts) use ($context) {
if ($placeholder_parts[0] !== 'my_custom') {
return null;
}
$category = $placeholder_parts[1] ?? '';
$key = $placeholder_parts[2] ?? '';
// Load context data once
$context->load('my_custom');
switch ($category) {
case 'user':
return $this->resolve_user_placeholder($context, $key);
case 'product':
return $this->resolve_product_placeholder($context, $key);
case 'setting':
return $this->resolve_setting_placeholder($context, $key);
default:
return '';
}
};
}
private function resolve_user_placeholder(Context $context, $key) {
switch ($key) {
case 'level':
return $context->get('my_custom.user.level', '0');
case 'points':
return $context->get('my_custom.user.points', '0');
default:
return $context->get("my_custom.user.{$key}", '');
}
}
```
---
## Declaring Package Dependencies
Packages can require other packages.
### Simple Dependency
```php
public function get_required_packages(): array {
return ['PHP']; // Requires PHP package
}
```
### Multiple Dependencies
```php
public function get_required_packages(): array {
return ['PHP', 'WP']; // Requires both PHP and WordPress packages
}
```
> [!WARNING]
> Avoid circular dependencies. Package A should not require Package B if Package B requires Package A. MilliRules will detect this and throw an error.
---
## Complete Custom Package Example
Here's a complete example of a custom package for a membership system:
```php
namespace MyPlugin\Packages;
use MilliRules\Packages\BasePackage;
class MembershipPackage extends BasePackage {
public function get_name(): string {
return 'Membership';
}
public function get_namespaces(): array {
return [
'MyPlugin\Packages\Membership\Conditions',
'MyPlugin\Packages\Membership\Actions',
];
}
public function is_available(): bool {
// Check if membership system is active
return class_exists('My_Membership_System');
}
public function get_required_packages(): array {
return ['PHP', 'WP']; // Requires both PHP and WordPress
}
public function register_providers(Context $context): void {
// Register membership provider (loads on-demand)
$context->register_provider('membership', function() {
$user_id = get_current_user_id();
$membership_data = [];
if ($user_id) {
$membership_data = [
'level' => get_user_meta($user_id, 'membership_level', true) ?: 'free',
'status' => get_user_meta($user_id, 'membership_status', true) ?: 'inactive',
'expiry' => get_user_meta($user_id, 'membership_expiry', true) ?: 0,
'features' => $this->get_user_features($user_id),
];
}
return [
'membership' => [
'user' => $membership_data,
'levels' => $this->get_available_levels(),
'features' => $this->get_all_features(),
],
];
});
}
public function get_placeholder_resolver(Context $context) {
return function($parts) use ($context) {
if ($parts[0] !== 'membership') {
return null;
}
// Load membership context if not already loaded
$context->load('membership');
$category = $parts[1] ?? '';
$key = $parts[2] ?? '';
if ($category === 'user') {
return $context->get("membership.user.{$key}", '');
}
return '';
};
}
private function get_user_features($user_id) {
// Get features available to user
return ['feature1', 'feature2'];
}
private function get_available_levels() {
return ['free', 'basic', 'premium', 'enterprise'];
}
private function get_all_features() {
return ['feature1', 'feature2', 'feature3'];
}
}
```
**Membership Condition Example**:
```php
namespace MyPlugin\Packages\Membership\Conditions;
use MilliRules\Conditions\BaseCondition;
use MilliRules\Context;
class MembershipLevelCondition extends BaseCondition {
protected function get_actual_value(Context $context) {
$context->load('membership');
return $context->get('membership.user.level', 'free');
}
public function get_type(): string {
return 'membership_level';
}
}
```
**Membership Action Example**:
```php
namespace MyPlugin\Packages\Membership\Actions;
use MilliRules\Actions\BaseAction;
use MilliRules\Context;
class UpgradeMembershipAction extends BaseAction {
public function execute(Context $context): void {
$context->load('user');
$user_id = $context->get('user.id', 0);
$new_level = $this->config['level'] ?? 'basic';
if (!$user_id) {
return;
}
update_user_meta($user_id, 'membership_level', $new_level);
update_user_meta($user_id, 'membership_status', 'active');
// Resolve message with placeholders
$message = $this->resolve_value(
$this->config['message'] ?? 'Upgraded to {membership.user.level}'
);
error_log($message);
}
public function get_type(): string {
return 'upgrade_membership';
}
}
```
**Using the Custom Package**:
```php
use MilliRules\MilliRules;
use MyPlugin\Packages\MembershipPackage;
// Initialize with custom package
$membership_package = new MembershipPackage();
MilliRules::init(null, [$membership_package]);
// Create rule using package conditions and actions
Rules::create('auto_upgrade_frequent_buyers')
->when()
->is_user_logged_in() // WP condition
->custom('membership_level', ['value' => 'free']) // Membership condition
->custom('purchase_count', ['value' => 10, 'operator' => '>='])
->then()
->custom('upgrade_membership', [
'level' => 'premium',
'message' => 'Congratulations! Upgraded to premium membership.'
])
->register();
```
---
## Real-World Example: Acorn MilliRules
The [Acorn MilliRules](https://github.com/MilliPress/Acorn-MilliRules) package is a real-world custom package that extends MilliRules for the [Roots Acorn](https://roots.io/acorn/) framework. It's a good reference for how to structure a production package.
### Package Class
The Acorn package registers route-aware conditions, HTTP response actions, and a route context provider:
```php
namespace MilliRules\Acorn\Packages\Acorn;
use MilliRules\Acorn\Packages\Acorn\Contexts\Route;
use MilliRules\Packages\BasePackage;
class Package extends BasePackage
{
public function get_name(): string
{
return 'Acorn';
}
public function get_namespaces(): array
{
return [
'MilliRules\\Acorn\\Packages\\Acorn\\Actions',
'MilliRules\\Acorn\\Packages\\Acorn\\Conditions',
'MilliRules\\Acorn\\Packages\\Acorn\\Contexts',
];
}
public function is_available(): bool
{
return function_exists('app');
}
public function get_required_packages(): array
{
return ['PHP'];
}
}
```
### What It Provides
| Component | Description |
|------------------------|-----------------------------------------------------------------|
| **Conditions** | `RouteName`, `RouteParameter`, `RouteController` |
| **Actions** | `Redirect`, `SetHeader` |
| **Context** | Route metadata (name, parameters, controller, URI, middleware) |
| **Auto-discovery** | Rule classes in `app/Rules/` are registered automatically |
| **Artisan commands** | 8 CLI commands to list, inspect, and scaffold rules |
### Usage Example
```php
// app/Rules/RedirectLegacyDocs.php
namespace App\Rules;
use MilliRules\Rules;
class RedirectLegacyDocs
{
public function register(): void
{
Rules::create('redirect_legacy_docs', 'Acorn')
->when()
->routeName('docs.*')
->routeParameter('product', ['value' => 'old-product'])
->then()
->redirect('/docs/new-product/', ['status' => 301])
->register();
}
}
```
For full documentation, see the [Acorn MilliRules docs](https://millipress.com/docs/acorn-millirules/).
---
## Best Practices
### 1. Use Descriptive Package Names
```php
// ✅ Good - clear and specific
public function get_name(): string {
return 'WooCommerce';
}
// ❌ Bad - vague or generic
public function get_name(): string {
return 'Custom';
}
```
### 2. Validate Environment in is_available()
```php
// ✅ Good - comprehensive checks
public function is_available(): bool {
return class_exists('WooCommerce')
&& function_exists('wc_get_product')
&& defined('WC_VERSION');
}
// ❌ Bad - minimal checking
public function is_available(): bool {
return true;
}
```
### 3. Cache Expensive Context Data
```php
use MilliRules\Context;
// ✅ Good - caches API calls in lazy provider
public function register_providers(Context $context): void {
$context->register_provider('my_package', function() {
$data = get_transient('my_package_context');
if ($data === false) {
$data = $this->fetch_expensive_data();
set_transient('my_package_context', $data, 300);
}
return ['my_package' => $data];
});
}
```
**Note**: With lazy loading, this expensive data is only fetched when a rule actually needs it!
### 4. Document Your Package
```php
/**
* Membership Package
*
* Provides membership-related conditions and actions.
*
* Conditions:
* - membership_level: Check user's membership level
* - membership_status: Check membership status
* - has_feature: Check if user has access to feature
*
* Actions:
* - upgrade_membership: Upgrade user to new level
* - grant_feature: Grant feature access
* - send_membership_email: Send membership-related email
*
* Context:
* - membership.user.level: User's membership level
* - membership.user.status: Membership status
* - membership.user.features: Available features
*
* Placeholders:
* - {membership.user.level}: User's membership level
* - {membership.user.status}: Membership status
*/
class MembershipPackage extends BasePackage {
// ...
}
```
---
## Common Pitfalls
### 1. Circular Dependencies
```php
// ❌ Wrong - circular dependency
class PackageA extends BasePackage {
public function get_required_packages(): array {
return ['PackageB']; // A requires B
}
}
class PackageB extends BasePackage {
public function get_required_packages(): array {
return ['PackageA']; // B requires A - CIRCULAR!
}
}
```
### 2. Accessing Unavailable Context
```php
use MilliRules\Context;
// ❌ Wrong - doesn't check availability
protected function get_actual_value(Context $context) {
$context->load('user');
return $context->get('user.id'); // May return null if not available!
}
// ✅ Correct - provides default value
protected function get_actual_value(Context $context) {
$context->load('user');
return $context->get('user.id', 0);
}
```
### 3. Expensive Provider Registration
```php
use MilliRules\Context;
// ❌ Wrong - executes expensive operation during registration
public function register_providers(Context $context): void {
$data = expensive_api_call(); // Runs on every request!
$context->register_provider('my_package', function() use ($data) {
return ['my_package' => $data];
});
}
// ✅ Correct - expensive operation runs only when provider loads
public function register_providers(Context $context): void {
$context->register_provider('my_package', function() {
$data = wp_cache_get('my_package_data', 'my_group');
if ($data === false) {
$data = expensive_api_call(); // Only runs when needed!
wp_cache_set('my_package_data', $data, 'my_group', 300);
}
return ['my_package' => $data];
});
}
```
---
## Next Steps
- **[Advanced Patterns](/docs/millirules/04-advanced/02-advanced-patterns)** - Advanced package techniques
- **[WordPress Integration](/docs/millirules/04-advanced/03-wordpress-integration)** - WordPress-specific patterns
- **[API Reference](/docs/millirules/05-reference/03-api)** - Complete API documentation
- **[Real-World Examples](/docs/millirules/04-advanced/01-examples)** - See complete package implementations
---
**Ready for advanced techniques?** Continue to [Advanced Patterns](/docs/millirules/04-advanced/02-advanced-patterns) to learn optimization strategies and advanced rule patterns.
---
Canonical: https://www.millipress.com/docs/millirules/04-advanced/01-examples
---
title: 'Real-World Examples'
description: 'Complete MilliRules examples for WordPress: page caching, access control, API rate limiting, feature flags, WooCommerce rules, and a full membership system.'
menu_order: 10
---
# Real-World Examples
This guide provides complete, working examples of MilliRules implementations for common use cases. Each example includes full code with explanations.
## Table of Contents
- [Page Caching System](#page-caching-system)
- [Access Control and Redirects](#access-control-and-redirects)
- [Content Modification](#content-modification)
- [User Tracking and Analytics](#user-tracking-and-analytics)
- [API Rate Limiting](#api-rate-limiting)
- [Feature Flags](#feature-flags)
- [WooCommerce Integration](#woocommerce-integration)
- [Membership System](#membership-system)
---
## Page Caching System
A complete page caching implementation using early execution.
```php
/**
* Plugin Name: MilliRules Page Cache
* Description: Intelligent page caching with MilliRules
*/
require_once __DIR__ . '/vendor/autoload.php';
use MilliRules\MilliRules;
use MilliRules\Rules;
use MilliRules\Context;
// Initialize early (in mu-plugins or early hook)
add_action('plugins_loaded', function() {
MilliRules::init();
// Register cache check action
Rules::register_action('check_page_cache', function($args, Context $context) {
$context->load('request');
$uri = $context->get('request.uri', '') ?? '';
$cache_key = 'page_cache_' . md5($uri);
$cached = get_transient($cache_key);
if ($cached !== false) {
header('Content-Type: text/html; charset=UTF-8');
header('X-Cache: HIT');
header('X-Cache-Key: ' . $cache_key);
echo $cached;
exit;
}
});
// Register cache save action
Rules::register_action('save_page_cache', function($args, Context $context) {
$uri = $context->get('request.uri', '') ?? '';
$cache_key = 'page_cache_' . md5($uri);
$duration = $args['duration'] ?? 3600;
ob_start(function($buffer) use ($cache_key, $duration) {
// Save to cache
set_transient($cache_key, $buffer, $duration);
// Add cache header
header('X-Cache: MISS');
header('X-Cache-Key: ' . $cache_key);
return $buffer;
});
});
// Rule 1: Check cache for cacheable requests
Rules::create('check_cache', 'php')
->order(5)
->when()
->request_method(['GET', 'HEAD'], 'IN')
->request_url('/wp-admin/*', 'NOT LIKE')
->request_url('/wp-login.php', '!=')
->cookie('wordpress_logged_in_*', null, 'NOT EXISTS')
->then()
->custom('check_page_cache')
->register();
// Rule 2: Save to cache after response
Rules::create('save_cache', 'php')
->order(10)
->when()
->request_method(['GET', 'HEAD'], 'IN')
->request_url('/wp-admin/*', 'NOT LIKE')
->request_url('/wp-login.php', '!=')
->then()
->custom('save_page_cache', ['duration' => 3600])
->register();
// Execute early rules
MilliRules::execute_rules(['PHP']);
}, 1);
// Clear cache on post update
add_action('save_post', function($post_id) {
// Clear all page cache
global $wpdb;
$wpdb->query("DELETE FROM {$wpdb->options} WHERE option_name LIKE '_transient_page_cache_%'");
});
```
---
## Access Control and Redirects
Protect pages and redirect unauthorized users.
```php
/**
* Plugin Name: MilliRules Access Control
* Description: Rule-based access control
*/
require_once __DIR__ . '/vendor/autoload.php';
use MilliRules\MilliRules;
use MilliRules\Rules;
add_action('init', function() {
MilliRules::init();
// Register custom conditions
Rules::register_condition('user_has_role', function($args, Context $context) {
$required_role = $args['role'] ?? '';
$user_roles = $context['wp']['user']['roles'] ?? [];
return in_array($required_role, $user_roles);
});
Rules::register_condition('user_can', function($args, Context $context) {
$capability = $args['capability'] ?? '';
$user_id = $context->get('user.id', 0) ?? 0;
return $user_id && user_can($user_id, $capability);
});
// Register redirect action
Rules::register_action('redirect_to', function($args, Context $context) {
$url = $args['url'] ?? home_url();
$status = $args['status'] ?? 302;
$message = $args['message'] ?? '';
if ($message) {
set_transient('redirect_message_' . get_current_user_id(), $message, 30);
}
wp_redirect($url, $status);
exit;
});
// Register message display action
Rules::register_action('show_redirect_message', function($args, Context $context) {
$user_id = get_current_user_id();
$message = get_transient('redirect_message_' . $user_id);
if ($message) {
delete_transient('redirect_message_' . $user_id);
add_action('admin_notices', function() use ($message) {
echo '' . esc_html($message) . '
';
$badge .= '⏱ Reading time: ' . $reading_time . ' min';
$badge .= '
';
return $badge . $content;
}, 10);
});
// Rule 1: Add disclaimer to product posts
Rules::create('product_disclaimer', 'wp')
->on('the_content', 10)
->when()
->is_singular('post')
->post_type('product')
->then()
->custom('prepend_content', [
'text' => '' .
'⚠ Disclaimer: Product specifications and prices are subject to change without notice.' .
'
',
'priority' => 10
])
->register();
// Rule 2: Add reading time to blog posts
Rules::create('add_blog_reading_time', 'wp')
->on('the_content', 10)
->when()
->is_singular('post')
->post_type('post')
->then()
->custom('add_reading_time')
->register();
// Rule 3: Add CTA to pages for non-members
Rules::create('membership_cta', 'wp')
->on('the_content', 10)
->when()
->is_singular('page')
->is_user_logged_in(false)
->then()
->custom('append_content', [
'text' => '' .
'
Enjoying this content?
' .
'
Join our community to access exclusive content and features!
' .
'
Join Now' .
'
About " . esc_html($author_name) . "
";
echo "" . esc_html($author_bio) . "
";
echo "View all posts by " . esc_html($author_name) . "";
echo "";
?>',
'priority' => 30
])
->register();
}, 1);
```
---
## User Tracking and Analytics
Track user behavior and log analytics events.
```php
/**
* Plugin Name: MilliRules Analytics
* Description: User tracking and analytics
*/
require_once __DIR__ . '/vendor/autoload.php';
use MilliRules\MilliRules;
use MilliRules\Rules;
add_action('init', function() {
MilliRules::init();
// Register tracking actions
Rules::register_action('track_page_view', function($args, Context $context) {
global $wpdb;
$table = $wpdb->prefix . 'page_views';
$user_id = $context->get('user.id', 0) ?? 0;
$url = $context->get('request.uri', '') ?? '';
$ip = $context['request']['ip'] ?? '';
$user_agent = $context['request']['user_agent'] ?? '';
$wpdb->insert($table, [
'user_id' => $user_id,
'url' => $url,
'ip' => $ip,
'user_agent' => $user_agent,
'viewed_at' => current_time('mysql'),
]);
});
Rules::register_action('track_event', function($args, Context $context) {
global $wpdb;
$table = $wpdb->prefix . 'analytics_events';
$event_type = $args['event_type'] ?? 'pageview';
$event_data = $args['event_data'] ?? [];
$user_id = $context->get('user.id', 0) ?? 0;
$wpdb->insert($table, [
'user_id' => $user_id,
'event_type' => $event_type,
'event_data' => json_encode($event_data),
'created_at' => current_time('mysql'),
]);
});
Rules::register_action('update_user_activity', function($args, Context $context) {
$user_id = $context->get('user.id', 0) ?? 0;
if ($user_id) {
update_user_meta($user_id, 'last_activity', time());
update_user_meta($user_id, 'total_visits',
(int) get_user_meta($user_id, 'total_visits', true) + 1
);
}
});
// Rule 1: Track all page views
Rules::create('track_all_pages', 'wp')
->on('wp', 10)
->when()->request_url('*')
->then()->custom('track_page_view')
->register();
// Rule 2: Track user activity
Rules::create('track_user_activity', 'wp')
->on('wp', 10)
->when()->is_user_logged_in()
->then()->custom('update_user_activity')
->register();
// Rule 3: Track important pages
Rules::create('track_important_pages', 'wp')
->on('wp', 10)
->when()
->request_url(['/pricing', '/contact', '/checkout'], 'IN')
->then()
->custom('track_event', [
'event_type' => 'important_page_view',
'event_data' => [
'page' => '{request.uri}',
'referrer' => '{request.referer}'
]
])
->register();
// Rule 4: Track downloads
Rules::create('track_downloads', 'wp')
->on('wp', 10)
->when()
->request_url('/downloads/*', 'LIKE')
->request_param('file')
->then()
->custom('track_event', [
'event_type' => 'file_download',
'event_data' => [
'file' => '{param.file}',
'user_id' => '{user.id}'
]
])
->register();
}, 1);
// Create tables on plugin activation
register_activation_hook(__FILE__, function() {
global $wpdb;
$charset_collate = $wpdb->get_charset_collate();
$sql1 = "CREATE TABLE IF NOT EXISTS {$wpdb->prefix}page_views (
id bigint(20) NOT NULL AUTO_INCREMENT,
user_id bigint(20) NOT NULL DEFAULT 0,
url varchar(255) NOT NULL,
ip varchar(45) NOT NULL,
user_agent text,
viewed_at datetime NOT NULL,
PRIMARY KEY (id),
KEY user_id (user_id),
KEY viewed_at (viewed_at)
) $charset_collate;";
$sql2 = "CREATE TABLE IF NOT EXISTS {$wpdb->prefix}analytics_events (
id bigint(20) NOT NULL AUTO_INCREMENT,
user_id bigint(20) NOT NULL DEFAULT 0,
event_type varchar(100) NOT NULL,
event_data text,
created_at datetime NOT NULL,
PRIMARY KEY (id),
KEY user_id (user_id),
KEY event_type (event_type),
KEY created_at (created_at)
) $charset_collate;";
require_once(ABSPATH . 'wp-admin/includes/upgrade.php');
dbDelta($sql1);
dbDelta($sql2);
});
```
---
## API Rate Limiting
Implement rate limiting for API endpoints.
```php
/**
* Plugin Name: MilliRules API Rate Limiter
* Description: Rate limiting for API endpoints
*/
require_once __DIR__ . '/vendor/autoload.php';
use MilliRules\MilliRules;
use MilliRules\Rules;
add_action('init', function() {
MilliRules::init();
// Register rate limit condition
Rules::register_condition('within_rate_limit', function($args, Context $context) {
$ip = $context['request']['ip'] ?? '';
$limit = $args['limit'] ?? 60; // Requests per minute
$period = $args['period'] ?? 60; // Seconds
$cache_key = 'rate_limit_' . md5($ip);
$current = get_transient($cache_key) ?: 0;
if ($current >= $limit) {
return false; // Rate limit exceeded
}
// Increment counter
set_transient($cache_key, $current + 1, $period);
return true;
});
// Register rate limit response action
Rules::register_action('send_rate_limit_response', function($args, Context $context) {
$retry_after = $args['retry_after'] ?? 60;
status_header(429);
header('Content-Type: application/json');
header('Retry-After: ' . $retry_after);
echo json_encode([
'error' => 'Rate limit exceeded',
'message' => 'Too many requests. Please try again later.',
'retry_after' => $retry_after
]);
exit;
});
// Rule 1: Rate limit API endpoints
Rules::create('api_rate_limit', 'php')
->order(5)
->when()
->request_url('/wp-json/*', 'LIKE')
->custom('within_rate_limit', ['limit' => 60, 'period' => 60])
->match_none() // If NOT within limit
->then()
->custom('send_rate_limit_response', ['retry_after' => 60])
->register();
// Rule 2: Stricter limits for authentication endpoints
Rules::create('auth_rate_limit', 'php')
->order(3)
->when()
->request_url('/wp-json/*/auth/*', 'LIKE')
->custom('within_rate_limit', ['limit' => 10, 'period' => 60])
->match_none()
->then()
->custom('send_rate_limit_response', ['retry_after' => 300])
->register();
// Execute early
MilliRules::execute_rules(['PHP']);
}, 1);
```
---
## Feature Flags
Implement dynamic feature flags.
```php
/**
* Plugin Name: MilliRules Feature Flags
* Description: Dynamic feature flag system
*/
require_once __DIR__ . '/vendor/autoload.php';
use MilliRules\MilliRules;
use MilliRules\Rules;
add_action('init', function() {
MilliRules::init();
// Register feature flag condition
Rules::register_condition('feature_enabled', function($args, Context $context) {
$feature = $args['feature'] ?? '';
return get_option("feature_flag_{$feature}", false);
});
// Register feature actions
Rules::register_action('enable_feature', function($args, Context $context) {
$feature = $args['feature'] ?? '';
if ($feature) {
// Mark feature as enabled
update_option("feature_enabled_{$feature}", true);
// Load feature code
$feature_file = plugin_dir_path(__FILE__) . "features/{$feature}.php";
if (file_exists($feature_file)) {
require_once $feature_file;
}
}
});
// Rule 1: Enable beta features for admins in dev
Rules::create('enable_beta_for_admins', 'wp')
->when()
->is_user_logged_in()
->custom('user_has_role', ['role' => 'administrator'])
->constant('WP_ENVIRONMENT_TYPE', ['local', 'development'], 'IN')
->then()
->custom('enable_feature', ['feature' => 'beta_dashboard'])
->custom('enable_feature', ['feature' => 'advanced_editor'])
->register();
// Rule 2: Enable features based on flags
Rules::create('load_new_checkout', 'wp')
->when()->custom('feature_enabled', ['feature' => 'new_checkout'])
->then()->custom('enable_feature', ['feature' => 'new_checkout'])
->register();
// Rule 3: Gradual rollout (10% of users)
Rules::register_condition('in_rollout_group', function($args, Context $context) {
$percentage = $args['percentage'] ?? 10;
$user_id = $context->get('user.id', 0) ?? 0;
// Consistent assignment based on user ID
return ($user_id % 100) < $percentage;
});
Rules::create('gradual_rollout', 'wp')
->when()
->is_user_logged_in()
->custom('in_rollout_group', ['percentage' => 10])
->then()
->custom('enable_feature', ['feature' => 'experimental_ui'])
->register();
}, 1);
// Helper function to check if feature is enabled
function is_feature_enabled($feature) {
return get_option("feature_enabled_{$feature}", false);
}
```
---
## WooCommerce Integration
Complete WooCommerce conditional logic example.
```php
/**
* Plugin Name: MilliRules WooCommerce Integration
* Description: Advanced WooCommerce rules
*/
require_once __DIR__ . '/vendor/autoload.php';
use MilliRules\MilliRules;
use MilliRules\Rules;
add_action('init', function() {
if (!class_exists('WooCommerce')) {
return;
}
MilliRules::init();
// Register WooCommerce conditions
Rules::register_condition('cart_total', function($args, Context $context) {
$minimum = $args['minimum'] ?? 0;
$operator = $args['operator'] ?? '>=';
$cart_total = WC()->cart->get_total('edit');
return BaseCondition::compare_values($cart_total, $minimum, $operator);
});
Rules::register_condition('cart_item_count', function($args, Context $context) {
$count = $args['count'] ?? 1;
$operator = $args['operator'] ?? '>=';
$cart_count = WC()->cart->get_cart_contents_count();
return BaseCondition::compare_values($cart_count, $count, $operator);
});
Rules::register_condition('has_product_category_in_cart', function($args, Context $context) {
$category_slug = $args['category'] ?? '';
foreach (WC()->cart->get_cart() as $cart_item) {
$product_id = $cart_item['product_id'];
if (has_term($category_slug, 'product_cat', $product_id)) {
return true;
}
}
return false;
});
// Register WooCommerce actions
Rules::register_action('apply_discount', function($args, Context $context) {
$coupon = $args['coupon'] ?? '';
if ($coupon && !WC()->cart->has_discount($coupon)) {
WC()->cart->apply_coupon($coupon);
wc_add_notice('Discount applied automatically!', 'success');
}
});
Rules::register_action('add_cart_notice', function($args, Context $context) {
$message = $args['message'] ?? '';
$type = $args['type'] ?? 'notice';
if ($message) {
wc_add_notice($message, $type);
}
});
// Rule 1: Free shipping for orders over $50
Rules::create('free_shipping_notice', 'wp')
->on('woocommerce_before_cart', 10)
->when()
->custom('cart_total', ['minimum' => 50])
->then()
->custom('add_cart_notice', [
'message' => '🎉 You qualify for free shipping!',
'type' => 'success'
])
->register();
// Rule 2: Auto-apply discount for bulk orders
Rules::create('bulk_order_discount', 'wp')
->on('woocommerce_before_calculate_totals', 10)
->when()
->custom('cart_item_count', ['count' => 10, 'operator' => '>='])
->then()
->custom('apply_discount', ['coupon' => 'BULK10'])
->register();
// Rule 3: Category-specific promotion
Rules::create('electronics_promo', 'wp')
->on('woocommerce_before_cart', 10)
->when()
->custom('has_product_category_in_cart', ['category' => 'electronics'])
->custom('cart_total', ['minimum' => 100, 'operator' => '>='])
->then()
->custom('apply_discount', ['coupon' => 'ELECTRONICS15'])
->custom('add_cart_notice', [
'message' => '15% discount applied to your electronics purchase!',
'type' => 'success'
])
->register();
// Rule 4: Minimum order notice
Rules::create('minimum_order_notice', 'wp')
->on('woocommerce_before_cart', 10)
->when()
->custom('cart_total', ['minimum' => 25, 'operator' => '<'])
->then()
->custom('add_cart_notice', [
'message' => 'Add $' . (25 - WC()->cart->get_total('edit')) . ' more to meet our minimum order amount.',
'type' => 'notice'
])
->register();
}, 1);
```
---
## Membership System
Complete membership system with tiers and access control.
```php
/**
* Plugin Name: MilliRules Membership System
* Description: Complete membership tier system
*/
require_once __DIR__ . '/vendor/autoload.php';
use MilliRules\MilliRules;
use MilliRules\Rules;
add_action('init', function() {
MilliRules::init();
// Register membership conditions
Rules::register_condition('has_membership_level', function($args, Context $context) {
$required_level = $args['level'] ?? 'free';
$user_id = $context->get('user.id', 0) ?? 0;
if (!$user_id) {
return $required_level === 'free';
}
$user_level = get_user_meta($user_id, 'membership_level', true) ?: 'free';
$levels = ['free' => 0, 'basic' => 1, 'premium' => 2, 'enterprise' => 3];
return ($levels[$user_level] ?? 0) >= ($levels[$required_level] ?? 0);
});
Rules::register_condition('membership_expired', function($args, Context $context) {
$user_id = $context->get('user.id', 0) ?? 0;
if (!$user_id) {
return false;
}
$expiry = get_user_meta($user_id, 'membership_expiry', true);
if (!$expiry) {
return false; // No expiry = lifetime
}
return time() > $expiry;
});
// Register membership actions
Rules::register_action('restrict_content', function($args, Context $context) {
$message = $args['message'] ?? 'This content requires a membership.';
$cta_url = $args['cta_url'] ?? home_url('/membership');
add_filter('the_content', function($content) use ($message, $cta_url) {
$restricted = '';
$restricted .= '
🔒 Members Only Content
';
$restricted .= '
' . esc_html($message) . '
';
$restricted .= '
Upgrade Membership';
$restricted .= '
5 min read
',
'priority' => 10
])
->register();
```
### Navigation Menu Modification
```php
Rules::register_action('add_menu_item', function($args, Context $context) {
$menu_slug = $args['menu_slug'] ?? '';
$title = $args['title'] ?? '';
$capability = $args['capability'] ?? 'read';
$url = $args['url'] ?? '#';
add_menu_page($title, $title, $capability, $menu_slug, function() use ($url) {
wp_redirect($url);
exit;
});
});
Rules::create('add_tools_menu')
->on('admin_menu', 20)
->when()->is_user_logged_in()
->then()
->custom('add_menu_item', [
'menu_slug' => 'custom-tools',
'title' => 'Custom Tools',
'capability' => 'manage_options',
'url' => admin_url('admin.php?page=custom-tools')
])
->register();
```
### Widget Registration
```php
Rules::register_action('register_sidebar', function($args, Context $context) {
$sidebar_config = wp_parse_args($config, [
'name' => 'Custom Sidebar',
'id' => 'custom-sidebar',
'description' => 'A custom sidebar',
'before_widget' => '',
'after_widget' => '
',
'before_title' => '',
'after_title' => '
',
]);
register_sidebar($sidebar_config);
});
Rules::create('conditional_sidebar')
->on('widgets_init', 10)
->when()->constant('ENABLE_CUSTOM_SIDEBAR', true)
->then()
->custom('register_sidebar', [
'name' => 'Product Sidebar',
'id' => 'product-sidebar'
])
->register();
```
### User Meta Updates
```php
Rules::register_action('update_user_meta', function($args, Context $context) {
$user_id = $context->get('user.id', 0) ?? 0;
$meta_key = $args['key'] ?? '';
$meta_value = $args['value'] ?? '';
if (!$user_id || !$meta_key) {
return;
}
update_user_meta($user_id, $meta_key, $meta_value);
});
Rules::create('track_login_time')
->on('wp_login', 10)
->when()->is_user_logged_in()
->then()
->custom('update_user_meta', [
'key' => 'last_login',
'value' => time()
])
->register();
```
---
## WooCommerce Integration
### WooCommerce Conditions
```php
Rules::register_condition('cart_total', function($args, Context $context) {
if (!function_exists('WC')) {
return false;
}
$minimum = $args['minimum'] ?? 0;
$cart_total = WC()->cart->get_total('');
return $cart_total >= $minimum;
});
Rules::register_condition('has_product_in_cart', function($args, Context $context) {
if (!function_exists('WC')) {
return false;
}
$product_id = $args['product_id'] ?? 0;
foreach (WC()->cart->get_cart() as $cart_item) {
if ($cart_item['product_id'] == $product_id) {
return true;
}
}
return false;
});
```
### WooCommerce Actions
```php
Rules::register_action('apply_coupon', function($args, Context $context) {
if (!function_exists('WC')) {
return;
}
$coupon_code = $args['coupon'] ?? '';
if ($coupon_code && !WC()->cart->has_discount($coupon_code)) {
WC()->cart->apply_coupon($coupon_code);
}
});
Rules::create('auto_apply_coupon')
->when()
->custom('cart_total', ['minimum' => 100])
->is_user_logged_in()
->then()
->custom('apply_coupon', ['coupon' => 'LOYALTYDISCOUNT'])
->register();
```
---
## Plugin Integration Patterns
### Feature Flags
```php
// Enable/disable features based on rules
Rules::register_action('enable_feature', function($args, Context $context) {
$feature = $args['feature'] ?? '';
if ($feature) {
update_option("feature_enabled_{$feature}", true);
}
});
Rules::create('enable_beta_features')
->when()
->is_user_logged_in()
->custom('user_has_role', ['role' => 'administrator'])
->constant('WP_ENVIRONMENT_TYPE', ['local', 'development'], 'IN')
->then()
->custom('enable_feature', ['feature' => 'beta_dashboard'])
->custom('enable_feature', ['feature' => 'advanced_editor'])
->register();
```
### Access Control
```php
Rules::register_action('restrict_access', function($args, Context $context) {
$message = $args['message'] ?? 'Access denied';
$redirect = $args['redirect'] ?? home_url();
wp_die($message, 'Access Denied', [
'link_url' => $redirect,
'link_text' => 'Go back',
]);
});
Rules::create('protect_admin_pages')
->when()
->request_url('/wp-admin/options-*.php')
->is_user_logged_in()
->custom('user_has_role', ['role' => 'administrator'])
->match_none() // NOT administrator
->then()
->custom('restrict_access', [
'message' => 'Only administrators can access this page',
'redirect' => admin_url()
])
->register();
```
### Conditional Plugin Loading
```php
// Conditionally load plugin features
add_action('plugins_loaded', function() {
MilliRules::init();
Rules::register_action('load_plugin_module', function($args, Context $context) {
$module = $args['module'] ?? '';
$file = plugin_dir_path(__FILE__) . "modules/{$module}.php";
if (file_exists($file)) {
require_once $file;
}
});
Rules::create('load_api_module')
->when()->request_url('/wp-json/myplugin/*')
->then()->custom('load_plugin_module', ['module' => 'api'])
->register();
Rules::create('load_admin_module')
->when()->constant('WP_ADMIN', true)
->then()->custom('load_plugin_module', ['module' => 'admin'])
->register();
}, 5);
```
---
## Best Practices
### 1. Hook Timing
```php
// ✅ Good - initialize early
add_action('init', function() {
MilliRules::init();
register_rules();
}, 1); // Early priority
// ❌ Bad - too late, hooks may have fired
add_action('wp_footer', function() {
MilliRules::init(); // Too late!
register_rules();
});
```
### 2. WordPress Function Availability
```php
// ✅ Good - checks function availability
Rules::register_condition('wp_safe_condition', function($args, Context $context) {
if (!function_exists('get_current_user_id')) {
return false;
}
$user_id = get_current_user_id();
return $user_id > 0;
});
// ❌ Bad - assumes WordPress is loaded
Rules::register_condition('unsafe_condition', function($args, Context $context) {
$user_id = get_current_user_id(); // May not exist!
return $user_id > 0;
});
```
### 3. Multisite Compatibility
```php
Rules::register_condition('is_main_site', function($args, Context $context) {
if (!is_multisite()) {
return true; // Not multisite, always main site
}
return is_main_site();
});
Rules::create('main_site_only_feature')
->when()->custom('is_main_site')
->then()->custom('enable_network_feature')
->register();
```
### 4. Translation Ready
```php
Rules::register_action('show_message', function($args, Context $context) {
$message = $args['message'] ?? '';
// Make translatable
$translated = __($message, 'my-text-domain');
echo '' . esc_html($translated) . '
';
});
```
---
## Troubleshooting
### Rules Not Executing in WordPress
**Check initialization timing**:
```php
// Verify MilliRules is initialized
add_action('init', function() {
if (!class_exists('MilliRules\MilliRules')) {
error_log('MilliRules not loaded!');
return;
}
MilliRules::init();
error_log('MilliRules initialized');
}, 1);
```
**Verify package loading**:
```php
$packages = MilliRules::get_loaded_packages();
error_log('Loaded packages: ' . implode(', ', $packages));
if (!in_array('WP', $packages)) {
error_log('WordPress package not loaded!');
}
```
### Hook Conflicts
```php
// Check if hook has fired
add_action('init', function() {
error_log('Init hook fired');
MilliRules::init();
Rules::create('test_rule')
->on('template_redirect', 10)
->when()->request_url('*')
->then()->custom('log', ['value' => 'Template redirect fired'])
->register();
}, 1);
add_action('template_redirect', function() {
error_log('template_redirect fired directly');
}, 1);
```
---
## Next Steps
- **[API Reference](/docs/millirules/05-reference/03-api)** - Complete method documentation
- **[Real-World Examples](/docs/millirules/04-advanced/01-examples)** - WordPress integration examples
- **[Advanced Patterns](/docs/millirules/04-advanced/02-advanced-patterns)** - Advanced WordPress patterns
---
**Ready for complete examples?** Continue to [Real-World Examples](/docs/millirules/04-advanced/01-examples) to see full WordPress implementations and use cases.
---
Canonical: https://www.millipress.com/docs/millirules/05-reference/01-conditions
---
title: 'Built-in Conditions Reference'
description: 'Reference for every built-in MilliRules condition: PHP request URL, method, header, cookie, and constant checks plus WordPress is_* and has_* conditionals.'
menu_order: 10
---
# Built-in Conditions Reference
MilliRules comes with a comprehensive set of built-in conditions for both framework-agnostic PHP applications and WordPress-specific scenarios. This reference guide documents every available condition with examples and usage patterns.
## Condition Packages
Conditions are organized into packages:
- **PHP Package** - Framework-agnostic HTTP and request conditions (always available)
- **WordPress Package** - WordPress-specific conditions (available only in WordPress)
## PHP Package Conditions
The PHP package provides framework-agnostic conditions that work in any PHP 7.4+ environment. These conditions handle HTTP requests, headers, cookies, and parameters.
### request_url
Check the request URL or URI path against a pattern or value.
**Namespace**: `MilliRules\Packages\PHP\Conditions\RequestUrl`
**Signature**:
```php
->request_url($value, $operator = '=')
```
**Parameters**:
- `$value` (string|array): URL pattern or array of patterns
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: All operators (=, !=, LIKE, REGEXP, IN, NOT IN, EXISTS, etc.)
**Context Data Used**: `$context->get('request.uri', '')`
#### Examples
**Exact match**:
```php
Rules::create('exact_url')
->when()
->request_url('/wp-admin/edit.php') // Exact URL match
->then()->custom('action')
->register();
```
**Wildcard pattern matching**:
```php
Rules::create('admin_urls')
->when()
->request_url('/wp-admin/*', 'LIKE') // Matches any admin URL
->then()->custom('action')
->register();
// Auto-detected LIKE operator (has wildcard)
Rules::create('api_urls')
->when()
->request_url('/api/*') // LIKE operator auto-detected
->then()->custom('action')
->register();
```
**Multiple URL patterns**:
```php
Rules::create('protected_areas')
->when()
->request_url([
'/wp-admin/*',
'/wp-login.php',
'/dashboard/*'
], 'IN')
->then()->custom('check_authentication')
->register();
```
**Regex matching**:
```php
Rules::create('api_versioned')
->when()
// Matches /api/v1/, /api/v2/, etc.
->request_url('/^\\/api\\/v[0-9]+\\//i', 'REGEXP')
->then()->custom('route_api_request')
->register();
```
**Exclude patterns**:
```php
Rules::create('non_admin_urls')
->when()
->request_url('/wp-admin/*', 'NOT LIKE') // Not admin URLs
->then()->custom('public_action')
->register();
```
> [!TIP]
> Use wildcards (`*` matches anything, `?` matches single character) for flexible pattern matching without the complexity of regex.
---
### request_method
Check the HTTP request method (GET, POST, PUT, DELETE, etc.).
**Namespace**: `MilliRules\Packages\PHP\Conditions\RequestMethod`
**Signature**:
```php
->request_method($value, $operator = '=')
```
**Parameters**:
- `$value` (string|array): HTTP method(s) to check
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: =, !=, IN, NOT IN, EXISTS
**Context Data Used**: `$context->get('request.method', '')`
#### Examples
**Single method**:
```php
Rules::create('post_requests')
->when()
->request_method('POST') // Only POST requests
->then()->custom('process_form')
->register();
```
**Multiple methods** (OR logic):
```php
Rules::create('safe_methods')
->when()
->request_method(['GET', 'HEAD'], 'IN') // GET or HEAD
->then()->custom('enable_caching')
->register();
// Auto-detected IN operator (array value)
Rules::create('safe_methods_auto')
->when()
->request_method(['GET', 'HEAD']) // IN auto-detected
->then()->custom('enable_caching')
->register();
```
**Exclude methods**:
```php
Rules::create('non_post_requests')
->when()
->request_method('POST', '!=')
->then()->custom('action')
->register();
Rules::create('non_modifying_requests')
->when()
->request_method(['POST', 'PUT', 'DELETE', 'PATCH'], 'NOT IN')
->then()->custom('read_only_action')
->register();
```
> [!NOTE]
> HTTP methods are case-insensitive. Both `'POST'` and `'post'` work identically.
---
### request_header
Check request headers against expected values.
**Namespace**: `MilliRules\Packages\PHP\Conditions\RequestHeader`
**Signature**:
```php
->request_header($header_name, $value = null, $operator = '=')
```
**Parameters**:
- `$header_name` (string): Header name (case-insensitive)
- `$value` (mixed): Expected value (null to check existence)
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: All operators
**Context Data Used**: `$context['request']['headers'][$header_name]`
#### Examples
**Check header existence**:
```php
Rules::create('has_auth_header')
->when()
->request_header('Authorization') // Header exists
->then()->custom('process_authenticated')
->register();
```
**Check header value**:
```php
Rules::create('json_requests')
->when()
->request_header('Content-Type', 'application/json')
->then()->custom('parse_json')
->register();
```
**Pattern matching headers**:
```php
Rules::create('bearer_token')
->when()
->request_header('Authorization', 'Bearer *', 'LIKE')
->then()->custom('validate_token')
->register();
```
**Multiple accepted values**:
```php
Rules::create('json_or_xml')
->when()
->request_header('Content-Type', [
'application/json',
'application/xml',
'text/xml'
], 'IN')
->then()->custom('parse_structured_data')
->register();
```
**Regex for complex matching**:
```php
Rules::create('api_key_format')
->when()
->request_header('X-API-Key', '/^[A-Za-z0-9]{32}$/', 'REGEXP')
->then()->custom('validate_api_key')
->register();
```
> [!IMPORTANT]
> Header names are case-insensitive in HTTP. `'Content-Type'`, `'content-type'`, and `'CONTENT-TYPE'` all reference the same header.
---
### request_param
Check URL query parameters or form POST data.
**Namespace**: `MilliRules\Packages\PHP\Conditions\RequestParam`
**Signature**:
```php
->request_param($param_name, $value = null, $operator = '=')
```
**Parameters**:
- `$param_name` (string): Parameter name
- `$value` (mixed): Expected value (null to check existence)
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: All operators
**Context Data Used**: `$context['request']['params'][$param_name]` (merges $_GET and $_POST)
#### Examples
**Check parameter existence**:
```php
Rules::create('has_action_param')
->when()
->request_param('action') // Parameter exists
->then()->custom('route_action')
->register();
```
**Check parameter value**:
```php
Rules::create('delete_action')
->when()
->request_param('action', 'delete')
->then()->custom('confirm_delete')
->register();
```
**Numeric comparison**:
```php
Rules::create('pagination')
->when()
->request_param('page', '1', '>') // Page > 1
->then()->custom('show_pagination')
->register();
```
**Multiple accepted values**:
```php
Rules::create('list_actions')
->when()
->request_param('view', ['list', 'grid', 'table'], 'IN')
->then()->custom('render_list_view')
->register();
```
**Pattern matching**:
```php
Rules::create('search_query')
->when()
->request_param('s', '*product*', 'LIKE') // Contains "product"
->then()->custom('enhance_product_search')
->register();
```
> [!NOTE]
> `request_param` checks both GET and POST parameters, with POST taking precedence if the same parameter exists in both.
---
### cookie
Check for cookie existence or value.
**Namespace**: `MilliRules\Packages\PHP\Conditions\Cookie`
**Signature**:
```php
->cookie($cookie_name, $value = null, $operator = '=')
```
**Parameters**:
- `$cookie_name` (string): Cookie name
- `$value` (mixed): Expected value (null to check existence)
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: All operators
**Context Data Used**: `$context['request']['cookies'][$cookie_name]` (from $_COOKIE)
#### Examples
**Check cookie existence**:
```php
Rules::create('has_session')
->when()
->cookie('session_id') // Cookie exists
->then()->custom('load_session')
->register();
```
**Check cookie value**:
```php
Rules::create('theme_preference')
->when()
->cookie('theme', 'dark')
->then()->custom('apply_dark_theme')
->register();
```
**Cookie doesn't exist**:
```php
Rules::create('first_time_visitor')
->when()
->cookie('visited_before', null, 'NOT EXISTS')
->then()->custom('show_welcome_message')
->register();
```
**Multiple cookie values**:
```php
Rules::create('preferred_languages')
->when()
->cookie('lang', ['en', 'en-US', 'en-GB'], 'IN')
->then()->custom('use_english')
->register();
```
**Pattern matching cookies**:
```php
Rules::create('tracking_cookies')
->when()
->cookie('_ga', 'GA*', 'LIKE') // Google Analytics cookie
->then()->custom('record_analytics')
->register();
```
> [!WARNING]
> Cookies are set by the client and can be manipulated. Never trust cookie values for security-critical decisions without additional validation.
---
### constant
Check PHP or WordPress constants.
**Namespace**: `MilliRules\Packages\PHP\Conditions\Constant`
**Signature**:
```php
->constant($constant_name, $value = null, $operator = '=')
```
**Parameters**:
- `$constant_name` (string): Constant name
- `$value` (mixed): Expected value (null to check existence)
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: All operators
**Context Data Used**: Uses `defined()` and `constant()` PHP functions
#### Examples
**Check constant existence**:
```php
Rules::create('has_debug_constant')
->when()
->constant('WP_DEBUG') // Constant is defined
->then()->custom('enable_debug_mode')
->register();
```
**Check boolean constants**:
```php
Rules::create('debug_enabled')
->when()
->constant('WP_DEBUG', true) // Debug is ON
->then()->custom('show_debug_info')
->register();
Rules::create('debug_disabled')
->when()
->constant('WP_DEBUG', false) // Debug is OFF
->then()->custom('hide_debug_info')
->register();
```
**Check string constants**:
```php
Rules::create('local_environment')
->when()
->constant('WP_ENVIRONMENT_TYPE', 'local')
->then()->custom('enable_local_features')
->register();
```
**Multiple environment types**:
```php
Rules::create('non_production')
->when()
->constant('WP_ENVIRONMENT_TYPE', ['local', 'development'], 'IN')
->then()->custom('enable_dev_tools')
->register();
```
**Version checking**:
```php
Rules::create('php_version_check')
->when()
->constant('PHP_VERSION', '8.0', '>=')
->then()->custom('use_php8_features')
->register();
```
> [!TIP]
> Use constant conditions to create environment-specific rules that behave differently in development, staging, and production.
---
## WordPress Package Conditions
WordPress package conditions are available only when WordPress is detected. They provide access to WordPress-specific functionality and query information.
### Generic WordPress is_* Conditions
MilliRules supports any WordPress conditional tag function through the `IsConditional` class. Any function starting with `is_` (like `is_singular()`, `is_home()`, `is_archive()`, `is_category()`, etc.) can be used as a condition.
**How It Works**:
- The `IsConditional` class acts as a bridge between MilliRules and WordPress conditional tags
- Supports all WordPress conditional tags: [WordPress Conditional Tags](https://developer.wordpress.org/themes/basics/conditional-tags/)
- Arguments passed to the condition are forwarded to the WordPress function
- Operates in two modes: Boolean Mode (no arguments) or Function Call Mode (with arguments)
#### Basic Usage (Boolean Mode)
When used without arguments, `is_*` conditions behave as simple boolean checks:
```php
// Fluent builder
Rules::create('rule-1')
->when()->is_404()->then()->register();
// Array configuration
[
'id' => 'rule-1',
'conditions' => [
[ 'type' => 'is_404' ], // is_404() IS TRUE
],
'actions' => [],
];
```
In this mode:
- The underlying WordPress function is called with **no arguments**
- The boolean result is compared to the configured `value` (default: `true`) using the configured `operator` (default: `IS`)
Examples:
- `->is_404()` → `is_404() IS true`
- `->is_user_logged_in(false)` → `is_user_logged_in() IS false`
**Basic conditionals**:
```php
// Check if any archive page
Rules::create('archive_pages')
->when()
->is_archive()
->then()->custom('show_archive_sidebar')
->register();
```
#### Function Call Mode (With Arguments)
For conditionals that accept arguments, you can pass them directly to the builder. `IsConditional` will call the underlying `is_*` function with those arguments and compare the result to `true`.
In this mode:
- All non-boolean arguments are treated as **function arguments** for the underlying `is_*` function
- The condition always checks whether the function result is `true` (using `value = true` internally)
**With arguments**:
```php
// Single-argument conditional
->is_singular('page') // is_singular('page') IS TRUE
// Multi-argument conditional
->is_tax('genre', 'sci-fi') // is_tax('genre', 'sci-fi') IS TRUE
```
**Combining conditions**:
```php
// Check if user is logged in and viewing a product archive
Rules::create('archive_list_user_orders')
->when()
->is_user_logged_in()
->is_post_type_archive('product')
->then()->custom('show_orders')
->register();
```
#### Using Operators with WordPress Conditionals
You can optionally pass a comparison operator as the **last argument** when using function call mode. This operator controls how the boolean result of the `is_*` function is compared to `true`.
Supported operators:
- `=`
- `!=`
- `IS`
- `IS NOT`
```php
// Calls is_tax('genre', 'sci-fi') and compares result != TRUE
// Check for multiple taxonomy terms with IN operator
Rules::create('action_or_drama')
->when()
->is_tax('genre', 'sci-fi', '!=');
->then()->custom('show_newsletter_cta')
->register();
// Check for multiple taxonomy terms with IN operator
Rules::create('action_or_drama')
->when()
->is_tax('genre', ['action', 'drama'], 'IN')
->then()->custom('show_intense_content_warning')
->register();
```
#### Implementation Notes
- The builder records all raw method arguments in a generic `args` key in the condition config
- The WordPress `IsConditional` class interprets `args` to determine whether to operate in boolean mode or function-call mode
- Other packages can reuse the `args` convention in their own condition classes without any changes to core engine or base condition logic
---
### Generic WordPress has_* Conditions
MilliRules supports any WordPress conditional tag function starting with `has_` through the `HasConditional` class. Functions like `has_post_thumbnail()`, `has_block()`, `has_term()`, `has_excerpt()`, etc. can all be used as conditions.
**How It Works**:
- The `HasConditional` class acts as a bridge between MilliRules and WordPress `has_*` conditional functions
- Arguments passed to the condition are forwarded to the WordPress function
- Operates in two modes: Boolean Mode (no arguments) or Function Call Mode (with arguments)
#### Basic Usage (Boolean Mode)
When used without arguments, `has_*` conditions behave as simple boolean checks:
```php
// Fluent builder
Rules::create('rule-1')
->when()->has_post_thumbnail()->then()->register();
// Array configuration
[
'id' => 'rule-1',
'conditions' => [
[ 'type' => 'has_post_thumbnail' ], // has_post_thumbnail() IS TRUE
],
'actions' => [],
];
```
In this mode:
- The underlying WordPress function is called with **no arguments**
- The boolean result is compared to the configured `value` (default: `true`) using the configured `operator` (default: `IS`)
Examples:
- `->has_post_thumbnail()` → `has_post_thumbnail() IS true`
- `->has_post_thumbnail(false)` → `has_post_thumbnail() IS false`
**Basic conditionals**:
```php
// Check if the post has an excerpt
Rules::create('has_excerpt')
->when()
->has_excerpt()
->then()->custom('show_custom_excerpt')
->register();
```
#### Function Call Mode (With Arguments)
For conditionals that accept arguments, you can pass them directly to the builder. `HasConditional` will call the underlying `has_*` function with those arguments and compare the result to `true`.
In this mode:
- All non-boolean arguments are treated as **function arguments** for the underlying `has_*` function
- The condition always checks whether the function result is `true` (using `value = true` internally)
**With arguments**:
```php
// Single-argument conditional
->has_block('core/paragraph') // has_block('core/paragraph') IS TRUE
// Multi-argument conditional
->has_term('news', 'category') // has_term('news', 'category') IS TRUE
```
**Combining conditions**:
```php
// Check if a post has a featured image and a specific block
Rules::create('rich_content')
->when()
->has_post_thumbnail()
->has_block('core/gallery')
->then()->custom('show_rich_layout')
->register();
```
#### Using Operators with WordPress has_* Conditionals
You can optionally pass a comparison operator as the **last argument** when using function call mode. This operator controls how the boolean result of the `has_*` function is compared to `true`.
Supported operators:
- `=`
- `!=`
- `IS`
- `IS NOT`
```php
// Check that a post does NOT have a specific term
Rules::create('not_in_news')
->when()
->has_term('news', 'category', '!=')
->then()->custom('show_generic_sidebar')
->register();
// Check that a post does NOT have a featured image
Rules::create('no_thumbnail')
->when()
->has_post_thumbnail(false)
->then()->custom('show_placeholder_image')
->register();
```
#### Implementation Notes
- The builder records all raw method arguments in a generic `args` key in the condition config
- The WordPress `HasConditional` class interprets `args` to determine whether to operate in boolean mode or function-call mode
- Other packages can reuse the `args` convention in their own condition classes without any changes to core engine or base condition logic
---
### post_type
Check the current post type.
**Namespace**: `MilliRules\Packages\WordPress\Conditions\PostType`
**Signature**:
```php
->post_type($post_types, $operator = '=')
```
**Parameters**:
- `$post_types` (string|array): Post type(s) to check
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: =, !=, IN, NOT IN, EXISTS
**Context Data Used**: `$context['wp']['post']['post_type']`
#### Examples
**Single post type**:
```php
Rules::create('product_pages')
->when()
->post_type('product')
->then()->custom('show_product_gallery')
->register();
```
**Multiple post types**:
```php
Rules::create('content_types')
->when()
->post_type(['post', 'page', 'article'], 'IN')
->then()->custom('enable_reading_time')
->register();
```
**Exclude post type**:
```php
Rules::create('non_page_content')
->when()
->post_type('page', '!=')
->then()->custom('show_author_bio')
->register();
```
---
### post_status
Check the current post status.
**Namespace**: `MilliRules\Packages\WordPress\Conditions\PostStatus`
**Signature**:
```php
->post_status($status, $operator = '=')
```
**Parameters**:
- `$status` (string|array): Post status(es) to check (`publish`, `draft`, `pending`, `private`, `future`, `trash`, etc.)
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: =, !=, IN, NOT IN
**How it resolves**: Reads `post_status` from the queried object or global `$post`.
#### Examples
**Single status**:
```php
Rules::create('published_only')
->when()
->post_status('publish')
->then()->custom('show_share_buttons')
->register();
```
**Multiple statuses**:
```php
Rules::create('visible_content')
->when()
->post_status(['publish', 'private'], 'IN')
->then()->custom('enable_comments')
->register();
```
**Exclude status**:
```php
Rules::create('not_draft')
->when()
->post_status('draft', '!=')
->then()->custom('index_content')
->register();
```
> [!NOTE]
> This condition reads the actual `post_status` property — there is no WordPress `is_post_status()` conditional tag, which is why this dedicated condition exists.
---
### post_parent
Check the parent post ID of the current post.
**Namespace**: `MilliRules\Packages\WordPress\Conditions\PostParent`
**Signature**:
```php
->post_parent($parent_id, $operator = '=')
```
**Parameters**:
- `$parent_id` (int|array): Parent post ID(s) to check
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: =, !=, IN, NOT IN, >, <
**How it resolves**: Reads `post_parent` from the queried object or global `$post`. Returns `0` if no post is found.
#### Examples
**Exact parent**:
```php
Rules::create('child_of_about')
->when()
->post_parent(10)
->then()->custom('show_about_subnav')
->register();
```
**Has any parent** (hierarchical post):
```php
Rules::create('is_child_page')
->when()
->post_parent(0, '>')
->then()->custom('show_breadcrumbs')
->register();
```
**Is top-level page** (no parent):
```php
Rules::create('top_level_page')
->when()
->post_parent(0)
->then()->custom('show_child_pages_menu')
->register();
```
> [!TIP]
> Use `->post_parent(0, '>')` as an efficient way to check if a page is a child of any parent, regardless of which parent.
---
### user_role
Check the roles of the current logged-in user.
**Namespace**: `MilliRules\Packages\WordPress\Conditions\UserRole`
**Signature**:
```php
->user_role($role, $operator = 'IN')
```
**Parameters**:
- `$role` (string|array): Role(s) to check (`administrator`, `editor`, `author`, `contributor`, `subscriber`, or custom roles)
- `$operator` (string): Comparison operator (default: `'IN'`)
**Supported Operators**: =, !=, IN, NOT IN
**How it resolves**: Loads user data from context and checks the `roles` array. Uses intersection logic — a user with multiple roles matches if *any* of their roles match any of the expected roles.
#### Examples
**Single role**:
```php
Rules::create('admin_features')
->when()
->user_role('administrator')
->then()->custom('show_admin_toolbar')
->register();
```
**Multiple roles**:
```php
Rules::create('editorial_features')
->when()
->user_role(['editor', 'administrator'], 'IN')
->then()->custom('show_editorial_tools')
->register();
```
**Exclude role**:
```php
Rules::create('non_subscribers')
->when()
->user_role('subscriber', '!=')
->then()->custom('show_premium_content')
->register();
```
> [!NOTE]
> WordPress users can have multiple roles. This condition uses array intersection, so `->user_role('editor')` will match a user who has both `editor` and `administrator` roles.
---
### wp_environment
Check the WordPress environment type.
**Namespace**: `MilliRules\Packages\WordPress\Conditions\WpEnvironment`
**Signature**:
```php
->wp_environment($environment, $operator = '=')
```
**Parameters**:
- `$environment` (string|array): Environment type(s) to check (`production`, `staging`, `development`, `local`)
- `$operator` (string): Comparison operator (default: `'='`)
**Supported Operators**: =, !=, IN, NOT IN
**How it resolves**: Uses `wp_get_environment_type()` (WordPress 5.5+). Falls back to `'production'` if the function is unavailable.
#### Examples
**Production check**:
```php
Rules::create('production_only')
->when()
->wp_environment('production')
->then()->custom('enable_caching')
->register();
```
**Non-production environments**:
```php
Rules::create('dev_tools')
->when()
->wp_environment(['development', 'local'], 'IN')
->then()->custom('enable_debug_bar')
->register();
```
**Exclude production**:
```php
Rules::create('not_production')
->when()
->wp_environment('production', '!=')
->then()->custom('show_environment_banner')
->register();
```
> [!TIP]
> You can also use `->constant('WP_ENVIRONMENT_TYPE', 'local')` from the PHP package for the same effect. The `wp_environment` condition is a convenience wrapper that handles the function availability check.
---
### query_var
Check WordPress query variables.
**Namespace**: `MilliRules\Packages\WordPress\Conditions\QueryVar`
**Signature**:
```php
->query_var($name, $value = null, $operator = '=')
```
**Parameters**:
- `$name` (string): Query variable name (e.g., `paged`, `post_type`, `s`, `m`, `author`, etc.)
- `$value` (mixed): Expected value (null defaults to `EXISTS` operator)
- `$operator` (string): Comparison operator (default: `'='`, or `'EXISTS'` when no value)
**Supported Operators**: =, !=, IN, NOT IN, LIKE, EXISTS, NOT EXISTS
**How it resolves**: First checks the execution context, then falls back to `get_query_var()`. When no value is provided, automatically uses the `EXISTS` operator.
#### Examples
**Check existence**:
```php
Rules::create('is_search')
->when()
->query_var('s') // Defaults to EXISTS
->then()->custom('enhance_search')
->register();
```
**Check value**:
```php
Rules::create('page_two')
->when()
->query_var('paged', 2)
->then()->custom('show_pagination_notice')
->register();
```
**Check post type query var**:
```php
Rules::create('product_archive_query')
->when()
->query_var('post_type', 'product')
->then()->custom('show_product_filters')
->register();
```
**Check non-existence**:
```php
Rules::create('no_search')
->when()
->query_var('s', null, 'NOT EXISTS')
->then()->custom('show_default_content')
->register();
```
> [!NOTE]
> `query_var` is a name-based condition — the first argument is always the query variable name, not a value. This makes it unique among WordPress conditions.
---
## Combining Conditions
### PHP Conditions Only
```php
Rules::create('api_authentication', 'php')
->when()
->request_url('/api/*')
->request_method('POST')
->request_header('Authorization', 'Bearer *', 'LIKE')
->cookie('session_id')
->then()->custom('process_api_request')
->register();
```
### WordPress Conditions Only
```php
Rules::create('admin_users_posts', 'wp')
->when()
->is_user_logged_in()
->is_singular('post')
->post_type('post')
->then()->custom('show_admin_tools')
->register();
```
### Mixed PHP and WordPress Conditions
```php
Rules::create('secure_admin_area', 'wp')
->when()
->request_url('/wp-admin/*') // PHP condition
->is_user_logged_in() // WordPress condition
->cookie('admin_preference') // PHP condition
->then()->custom('customize_admin')
->register();
```
> [!TIP]
> When mixing PHP and WordPress conditions, ensure the WordPress package is available. Auto-detection will set the rule type to `'wp'` when WordPress conditions are used.
## Condition Evaluation Order
Conditions are evaluated in the order they're defined:
```php
Rules::create('sequential_checks')
->when()
->request_url('/api/*') // Checked first
->request_method('POST') // Checked second
->cookie('auth_token') // Checked third
->then()->custom('action')
->register();
```
For performance, place the **most restrictive or fastest conditions first**:
```php
// ✅ Good - quick checks first
Rules::create('optimized')
->when()
->request_method('POST') // Fast check
->request_url('/specific/path') // Fast check
->custom('complex_validation') // Slow custom check last
->then()->custom('action')
->register();
// ❌ Bad - slow check first
Rules::create('unoptimized')
->when()
->custom('complex_validation') // Slow check first!
->request_method('POST')
->request_url('/specific/path')
->then()->custom('action')
->register();
```
> [!IMPORTANT]
> With match_all() (default), if any condition fails, subsequent conditions are not evaluated. Place restrictive conditions first to short-circuit evaluation early.
## Custom Conditions
When built-in conditions aren't sufficient, create custom conditions:
```php
// Register custom condition
Rules::register_condition('is_weekend', function(Context $context) {
return date('N') >= 6; // Saturday or Sunday
});
// Use in rule
Rules::create('weekend_special')
->when()
->custom('is_weekend')
->request_url('/shop/*')
->then()->custom('apply_weekend_discount')
->register();
```
See [Creating Custom Conditions](/docs/millirules/03-customization/01-custom-conditions) for detailed information.
## Best Practices
### 1. Use Specific Conditions
```php
// ✅ Good - specific conditions
->when()
->request_url('/api/users')
->request_method('GET')
// ❌ Bad - too broad
->when()
->request_url('*')
```
### 2. Leverage Auto-Detection
```php
// ✅ Good - let MilliRules detect operators
->request_url('/admin/*') // LIKE auto-detected
->request_method(['GET', 'HEAD']) // IN auto-detected
->constant('WP_DEBUG', true) // IS auto-detected
// ❌ Unnecessary - explicit when auto-detected works
->request_url('/admin/*', 'LIKE')
->request_method(['GET', 'HEAD'], 'IN')
->constant('WP_DEBUG', true, 'IS')
```
### 3. Group Related Conditions
```php
// ✅ Good - logical grouping
Rules::create('api_security')
->when()
// API context
->request_url('/api/*')
->request_method('POST')
// Authentication
->cookie('session_id')
->request_header('Authorization')
->then()->custom('process_secure_api')
->register();
```
### 4. Use Comments for Complex Logic
```php
Rules::create('complex_caching')
->when()
// Cacheable request types
->request_method(['GET', 'HEAD'], 'IN')
// Not in admin or login areas
->request_url('/wp-admin/*', 'NOT LIKE')
->request_url('/wp-login.php', '!=')
// User hasn't disabled caching
->cookie('disable_cache', null, 'NOT EXISTS')
->then()->custom('apply_cache')
->register();
```
## Next Steps
- **[Built-in Actions](/docs/millirules/05-reference/02-actions)** - Learn about available actions
- **[Operators](/docs/millirules/02-core-concepts/04-operators)** - Master comparison and pattern matching
- **[Custom Conditions](/docs/millirules/03-customization/01-custom-conditions)** - Create your own conditions
- **[Examples](/docs/millirules/04-advanced/01-examples)** - See conditions in real-world scenarios
---
**Need more details?** Check the [API Reference](/docs/millirules/05-reference/03-api) for complete method signatures and parameters.
---
Canonical: https://www.millipress.com/docs/millirules/05-reference/02-actions
---
title: 'Built-in Actions Reference'
description: 'How the MilliRules action system works: callback and class-based actions, execution order, context access, and reusable patterns for redirects and caching.'
menu_order: 20
---
# Built-in Actions Reference
Actions are the "then" part of your rules—they define what happens when conditions are met. Unlike conditions, MilliRules' action system is primarily designed around **custom actions** that you define for your specific needs.
## Understanding the Action System
MilliRules provides a flexible action framework that allows you to:
- **Register custom callback actions** for quick, inline functionality
- **Create reusable action classes** for complex operations
- **Execute actions sequentially** in the order they're defined
- **Access full context** within actions for data-driven decisions
## Action Execution Flow
When a rule's conditions match:
```
1. Rule conditions evaluate to true
↓
2. Rule engine triggers action execution
↓
3. For each action in the rule:
a. Instantiate action with config and context
b. Execute action's execute() method
c. Continue to next action
↓
4. Return execution statistics
```
Actions execute **immediately and sequentially**. There's no action queue or deferred execution.
> [!IMPORTANT]
> Actions execute in the exact order they're defined in your rule. If one action fails, MilliRules logs the error and continues to the next action.
## Action Types
### 1. Custom Callback Actions
The simplest way to create actions is using callback functions.
#### Registering Callback Actions
```php
use MilliRules\Rules;
use MilliRules\Context;
// Simple action
Rules::register_action('log_message', function($args, Context $context) {
$message = $args['message'] ?? $args[0] ?? 'No message';
error_log('MilliRules: ' . $message);
});
// Action with context access
Rules::register_action('log_user_action', function($args, Context $context) {
$action = $args['action'] ?? 'accessed';
$user = $context->get('user.login', 'guest');
$url = $context->get('request.uri', 'unknown');
error_log("User {$user} {$action} {$url}");
});
```
#### Using Callback Actions in Rules
```php
Rules::create('log_admin_access')
->when()
->request_url('/wp-admin/*')
->is_user_logged_in()
->then()
->custom('log_message', ['value' => 'Admin area accessed'])
->custom('log_user_action')
->register();
```
**Callback Parameters**:
- `$context` (array): Full execution context with request, WP data, etc.
- `$config` (array): Action configuration passed from the rule
> [!TIP]
> Use callback actions for simple operations that don't require state management or extensive configuration.
---
### 2. Class-Based Actions
For complex operations, create action classes implementing `ActionInterface`.
#### Action Interface
```php
namespace MilliRules\Interfaces;
interface ActionInterface {
public function execute(Context $context): void;
public function get_type(): string;
}
```
#### Creating an Action Class
```php
namespace MyPlugin\Actions;
use MilliRules\Interfaces\ActionInterface;
class SendEmailAction implements ActionInterface {
private $config;
private $context;
public function __construct(array $config, Context $context) {
$this->config = $config;
$this->context = $context;
}
public function execute(Context $context): void {
$to = $this->config['to'] ?? '';
$subject = $this->config['subject'] ?? 'Notification';
$message = $this->config['message'] ?? '';
// Access context for dynamic data
$user_email = $context['wp']['user']['email'] ?? $to;
wp_mail($to, $subject, $message);
}
public function get_type(): string {
return 'send_email';
}
}
```
#### Registering the Namespace
```php
use MilliRules\RuleEngine;
// Register action namespace so MilliRules can find your action classes
RuleEngine::register_namespace('Actions', 'MyPlugin\Actions');
```
#### Using Class-Based Actions
```php
Rules::create('user_registration_notification')
->when()
->request_url('/wp-admin/user-new.php')
->request_param('action', 'createuser')
->then()
->custom('send_email', [
'to' => 'admin@example.com',
'subject' => 'New User Registration',
'message' => 'A new user has registered.'
])
->register();
```
> [!NOTE]
> Class-based actions provide better organization, testability, and reusability for complex operations.
---
### 3. BaseAction Helper Class
MilliRules provides a `BaseAction` abstract class that includes placeholder resolution.
```php
namespace MyPlugin\Actions;
use MilliRules\Actions\BaseAction;
class CustomAction extends BaseAction {
public function execute(Context $context): void {
// Resolve placeholders in config values
$message = $this->resolve_value($this->config['value'] ?? '');
// Use resolved value
error_log($message);
}
public function get_type(): string {
return 'custom_action';
}
}
```
**Using placeholder resolution**:
```php
Rules::create('dynamic_logging')
->when()
->request_url('/api/*')
->then()
->custom('custom_action', [
'value' => 'API request to {request.uri} from {request.ip}'
])
->register();
// Logs: "API request to /api/users from 192.168.1.1"
```
See [Dynamic Placeholders](/docs/millirules/02-core-concepts/05-placeholders) for complete placeholder syntax.
---
## Common Action Patterns
### 1. Logging Actions
```php
// Simple logging
Rules::register_action('log', function($args, Context $context) {
error_log($args['value'] ?? '');
});
// Structured logging
Rules::register_action('log_structured', function($args, Context $context) {
$data = [
'timestamp' => time(),
'user' => $context->get('user.login', 'guest') ?? 'guest',
'ip' => $context['request']['ip'] ?? 'unknown',
'message' => $args['value'] ?? '',
];
error_log(json_encode($data));
});
// Usage
Rules::create('log_actions')
->when()->request_url('/important/*')
->then()
->custom('log', ['value' => 'Important URL accessed'])
->custom('log_structured', ['value' => 'Security alert'])
->register();
```
---
### 2. Redirect Actions
```php
Rules::register_action('redirect', function($args, Context $context) {
$url = $args['url'] ?? home_url();
$status = $args['status'] ?? 302;
if (!headers_sent()) {
wp_redirect($url, $status);
exit;
}
});
// Usage
Rules::create('redirect_logged_out_users')
->when()
->request_url('/members/*')
->is_user_logged_in(false)
->then()
->custom('redirect', [
'url' => wp_login_url(),
'status' => 302
])
->register();
```
> [!WARNING]
> Redirect actions should typically be the last action in a rule, as they terminate execution with `exit`.
---
### 3. Cache Control Actions
```php
Rules::register_action('set_cache_headers', function($args, Context $context) {
$duration = $args['duration'] ?? 3600;
if (!headers_sent()) {
header("Cache-Control: public, max-age={$duration}");
header('Expires: ' . gmdate('D, d M Y H:i:s', time() + $duration) . ' GMT');
}
});
// Usage
Rules::create('cache_api_responses')
->when()
->request_url('/api/*')
->request_method(['GET', 'HEAD'], 'IN')
->then()
->custom('set_cache_headers', ['duration' => 7200])
->register();
```
---
### 4. Database Operations
```php
Rules::register_action('log_to_database', function($args, Context $context) {
global $wpdb;
$table = $wpdb->prefix . 'access_log';
$wpdb->insert($table, [
'user_id' => $context->get('user.id', 0) ?? 0,
'url' => $context->get('request.uri', '') ?? '',
'timestamp' => current_time('mysql'),
]);
});
// Usage
Rules::create('track_premium_access')
->when()
->request_url('/premium/*')
->is_user_logged_in()
->then()
->custom('log_to_database')
->register();
```
---
### 5. WordPress Hook Triggers
```php
// Trigger WordPress actions
Rules::register_action('do_action', function($args, Context $context) {
$hook = $args['value'] ?? '';
$args = $args['args'] ?? [];
if ($hook) {
do_action($hook, ...$args);
}
});
// Trigger WordPress filters
Rules::register_action('apply_filters', function($args, Context $context) {
$hook = $args['value'] ?? '';
$value = $args['filter_value'] ?? '';
$args = $args['args'] ?? [];
if ($hook) {
return apply_filters($hook, $value, ...$args);
}
});
// Usage
Rules::create('trigger_custom_hooks')
->when()->request_url('/checkout/*')
->then()
->custom('do_action', [
'value' => 'my_checkout_started',
'args' => ['checkout_page']
])
->register();
```
---
### 6. Content Modification
```php
Rules::register_action('modify_content', function($args, Context $context) {
add_filter('the_content', function($content) use ($config) {
$prepend = $args['prepend'] ?? '';
$append = $args['append'] ?? '';
return $prepend . $content . $append;
}, $args['priority'] ?? 10);
});
// Usage
Rules::create('add_disclaimer')
->when()
->is_singular('post')
->post_type('product')
->then()
->custom('modify_content', [
'prepend' => 'Product information may vary.
',
'priority' => 10
])
->register();
```
---
### 7. Conditional Execution
```php
Rules::register_action('execute_if', function($args, Context $context) {
$condition = $args['condition'] ?? null;
$callback = $args['callback'] ?? null;
if (is_callable($condition) && is_callable($callback)) {
if ($condition($context)) {
$callback($context);
}
}
});
// Usage
Rules::create('conditional_action')
->when()->request_url('/api/*')
->then()
->custom('execute_if', [
'condition' => function(Context $context) {
return date('H') >= 9 && date('H') <= 17; // Business hours
},
'callback' => function(Context $context) {
error_log('API accessed during business hours');
}
])
->register();
```
---
## Action Configuration
Actions receive configuration through the `$config` array:
```php
Rules::register_action('flexible_action', function($args, Context $context) {
// Common configuration keys
$value = $args['value'] ?? ''; // Primary value
$enabled = $args['enabled'] ?? true; // Enable flag
$priority = $args['priority'] ?? 10; // Priority/order
$options = $args['options'] ?? []; // Additional options
// Custom configuration
$custom_param = $args['custom_param'] ?? 'default';
});
// Usage with full configuration
Rules::create('configured_action')
->when()->request_url('/test')
->then()
->custom('flexible_action', [
'value' => 'test value',
'enabled' => true,
'priority' => 20,
'options' => ['key' => 'value'],
'custom_param' => 'custom value'
])
->register();
```
> [!TIP]
> Use consistent configuration key names across your actions:
> - `'value'` for the primary action value
> - `'enabled'` for enable/disable flags
> - `'priority'` for ordering within the action
> - `'options'` for nested configuration
---
## Accessing Context in Actions
The context provides access to all available data:
```php
Rules::register_action('context_aware_action', function($args, Context $context) {
// Request data
$url = $context->get('request.uri', '') ?? '';
$method = $context->get('request.method', '') ?? '';
$ip = $context['request']['ip'] ?? '';
// Cookies
$session = $context['request']['cookies']['session_id'] ?? '';
// WordPress data (if available)
$user_id = $context->get('user.id', 0) ?? 0;
$user_login = $context->get('user.login', 'guest') ?? 'guest';
$post_id = $context->get('post.id', 0) ?? 0;
// Query flags
$is_singular = $context['wp']['query']['is_singular'] ?? false;
$is_admin = $context['wp']['query']['is_admin'] ?? false;
// Use context data
error_log("User {$user_login} accessed {$url} from {$ip}");
});
```
**Full context structure**:
```php
[
'request' => [
'method' => 'GET',
'uri' => '/path',
'scheme' => 'https',
'host' => 'example.com',
'path' => '/path',
'query' => 'key=value',
'referer' => 'https://example.com',
'user_agent' => 'Mozilla/5.0...',
'headers' => [...],
'ip' => '192.168.1.1',
'cookies' => [...],
'params' => [...],
],
'wp' => [ // WordPress only
'post' => [...],
'user' => [...],
'query' => [...],
'constants' => [...],
],
]
```
---
## Error Handling in Actions
MilliRules catches action exceptions and continues execution:
```php
Rules::register_action('safe_action', function($args, Context $context) {
try {
// Risky operation
$result = risky_operation();
if (!$result) {
throw new Exception('Operation failed');
}
} catch (Exception $e) {
error_log('Action error: ' . $e->getMessage());
// Execution continues to next action
}
});
```
> [!IMPORTANT]
> If an action throws an uncaught exception, MilliRules logs the error and continues to the next action. The rule is marked as executed even if actions fail.
---
## Multiple Actions in Sequence
Actions execute sequentially in definition order:
```php
Rules::create('multi_step_process')
->when()->request_url('/process')
->then()
->custom('log', ['value' => '1. Starting process'])
->custom('validate_data')
->custom('log', ['value' => '2. Data validated'])
->custom('process_data')
->custom('log', ['value' => '3. Data processed'])
->custom('send_response')
->custom('log', ['value' => '4. Response sent'])
->register();
```
**Execution flow**:
1. Log: "1. Starting process"
2. Validate data
3. Log: "2. Data validated"
4. Process data
5. Log: "3. Data processed"
6. Send response
7. Log: "4. Response sent"
---
## Best Practices
### 1. Keep Actions Focused
```php
// ✅ Good - single responsibility
Rules::register_action('log_access', function($args, Context $context) {
error_log('Access logged');
});
Rules::register_action('update_counter', function($args, Context $context) {
update_option('access_count', get_option('access_count', 0) + 1);
});
// ❌ Bad - multiple responsibilities
Rules::register_action('do_everything', function($args, Context $context) {
error_log('Access logged');
update_option('access_count', get_option('access_count', 0) + 1);
send_email('admin@example.com', 'Access', 'Someone accessed');
update_database();
// Too much in one action!
});
```
### 2. Use Descriptive Action Names
```php
// ✅ Good
Rules::register_action('send_admin_notification_email', ...);
Rules::register_action('log_security_event', ...);
Rules::register_action('update_user_last_login_timestamp', ...);
// ❌ Bad
Rules::register_action('send', ...);
Rules::register_action('log', ...);
Rules::register_action('update', ...);
```
### 3. Validate Configuration
```php
Rules::register_action('safe_action', function($args, Context $context) {
// Validate required configuration
if (empty($args['required_value'])) {
error_log('Action error: missing required_value');
return;
}
// Validate data types
$count = absint($args['count'] ?? 0);
$enabled = (bool) ($args['enabled'] ?? true);
// Proceed with validated data
// ...
});
```
### 4. Check Prerequisites
```php
Rules::register_action('wordpress_dependent', function($args, Context $context) {
// Check if WordPress functions are available
if (!function_exists('wp_mail')) {
error_log('WordPress not available');
return;
}
wp_mail($args['to'], $args['subject'], $args['message']);
});
```
### 5. Use Constants for Configuration
```php
// Define action configuration constants
define('DEFAULT_EMAIL_RECIPIENT', 'admin@example.com');
define('DEFAULT_LOG_LEVEL', 'info');
Rules::register_action('send_notification', function($args, Context $context) {
$to = $args['to'] ?? DEFAULT_EMAIL_RECIPIENT;
$level = $args['level'] ?? DEFAULT_LOG_LEVEL;
// Use constants for consistent configuration
});
```
---
## Common Pitfalls
### 1. Modifying Context
```php
// ❌ Wrong - context modifications don't persist
Rules::register_action('modify_context', function($args, Context $context) {
$context['custom_value'] = 'modified';
// This change is lost after the action completes
});
// ✅ Correct - use external state or return values
Rules::register_action('store_value', function($args, Context $context) {
update_option('custom_value', 'modified');
});
```
> [!WARNING]
> Context is passed by value to actions. Modifications to `$context` within an action do not persist to subsequent actions.
### 2. Assuming Action Order Across Rules
```php
// ❌ Wrong - different rules, no guaranteed order
Rules::create('rule1')->order(10)->when()->then()->custom('action1')->register();
Rules::create('rule2')->order(20)->when()->then()->custom('action2')->register();
// action1 and action2 only execute if their respective rule conditions match
// ✅ Correct - actions in same rule execute in order
Rules::create('rule')->order(10)
->when()->request_url('*')
->then()
->custom('action1') // Executes first
->custom('action2') // Executes second
->register();
```
### 3. Using Exit/Die in Actions
```php
// ❌ Wrong - prevents subsequent actions
Rules::register_action('early_exit', function($args, Context $context) {
echo 'Response';
exit; // Stops all subsequent actions!
});
// ✅ Correct - use flags or return early
Rules::register_action('conditional_processing', function($args, Context $context) {
if (!some_condition()) {
return; // Skip this action, continue to next
}
// Process normally
});
```
---
## Next Steps
- **[Operators and Pattern Matching](/docs/millirules/02-core-concepts/04-operators)** - Master condition operators
- **[Dynamic Placeholders](/docs/millirules/02-core-concepts/05-placeholders)** - Use dynamic values in actions
- **[Creating Custom Actions](/docs/millirules/03-customization/02-custom-actions)** - Advanced action development
- **[Real-World Examples](/docs/millirules/04-advanced/01-examples)** - See actions in complete examples
---
**Ready to create custom actions?** Continue to [Creating Custom Actions](/docs/millirules/03-customization/02-custom-actions) for advanced techniques and patterns.
---
Canonical: https://www.millipress.com/docs/millirules/05-reference/03-api
---
title: 'Complete API Reference'
description: 'Full API documentation for MilliRules: every public class and method with parameters, return types, and PHP examples, from Rules::create() to ArgumentSchema.'
menu_order: 30
---
# Complete API Reference
This comprehensive API reference documents all public classes, methods, interfaces, and functions in MilliRules.
## Table of Contents
- [Core Classes](#core-classes)
- [Builders](#builders)
- [Interfaces](#interfaces)
- [Base Classes](#base-classes)
---
## Core Classes
### MilliRules
Main entry point for initializing and executing rules.
**Namespace**: `MilliRules`
#### Methods
##### `init(?array $package_names = null, ?array $packages = null): array`
Initialize MilliRules and load packages.
**Parameters**:
- `$package_names` (array|null): Array of package names to load (null = auto-load all available)
- `$packages` (array|null): Array of PackageInterface instances to register (null = register defaults)
**Returns**: `array` - Array of loaded package names
**Example**:
```php
// Auto-load available packages
MilliRules::init();
// Load specific packages by name
MilliRules::init(['PHP', 'WP']);
// Load with custom package instances
$custom = new CustomPackage();
MilliRules::init(null, [$custom]);
```
---
##### `execute_rules(?array $allowed_packages = null, array $context = []): array`
Execute all registered rules.
**Parameters**:
- `$allowed_packages` (array|null): Array of package names to use (null = all loaded)
- `$context` (array): Additional context data (merges with auto-built context)
**Returns**: `array` - Execution result with statistics
```php
[
'rules_processed' => int, // Total rules evaluated
'rules_skipped' => int, // Rules skipped
'rules_matched' => int, // Rules with matching conditions
'actions_executed' => int, // Actions executed
'context' => array, // Execution context
]
```
**Example**:
```php
// Execute all rules
$result = MilliRules::execute_rules();
// Execute only PHP rules
$result = MilliRules::execute_rules(['PHP']);
// Execute with custom context
$result = MilliRules::execute_rules(null, ['custom_data' => 'value']);
```
---
##### `get_loaded_packages(): array`
Get names of all loaded packages.
**Returns**: `array` - Array of package names
**Example**:
```php
$packages = MilliRules::get_loaded_packages();
// ['PHP', 'WP']
```
---
##### `build_context(): array`
Build context from all loaded packages.
**Returns**: `array` - Aggregated context data
**Example**:
```php
$context = MilliRules::build_context();
/*
[
'request' => [...],
'wp' => [...],
]
*/
```
---
### Rules
Fluent interface for creating and registering rules.
**Namespace**: `MilliRules`
> [!NOTE]
> **Naming Convention**: All fluent API methods can be called in either `snake_case` or `camelCase`. For example, `->when_all()` and `->whenAll()` are equivalent, as are `->set_conditions()` and `->setConditions()`. This applies to all builder methods on `Rules`, `ConditionBuilder`, and `ActionBuilder`. The documentation uses `snake_case` throughout, but use whichever style fits your project.
#### Methods
##### `create(string $id, ?string $type = null): Rules`
Create a new rule.
**Parameters**:
- `$id` (string): Unique rule identifier
- `$type` (string|null): Rule type (`'php'` or `'wp'`), auto-detected if null
**Returns**: `Rules` - Rule builder instance
**Example**:
```php
$rule = Rules::create('my_rule');
$rule = Rules::create('wp_rule', 'wp');
```
---
##### `title(string $title): Rules`
Set rule title.
**Parameters**:
- `$title` (string): Human-readable title
**Returns**: `Rules` - Fluent interface
**Example**:
```php
Rules::create('my_rule')
->title('My Custom Rule')
->register();
```
---
##### `order(int $order): Rules`
Set execution order.
**Parameters**:
- `$order` (int): Order value (lower = executes first)
**Returns**: `Rules` - Fluent interface
**Example**:
```php
Rules::create('my_rule')
->order(10) // Execute at priority 10
->register();
```
---
##### `enabled(bool $enabled): Rules`
Enable or disable rule.
**Parameters**:
- `$enabled` (bool): Whether rule is enabled
**Returns**: `Rules` - Fluent interface
**Example**:
```php
Rules::create('my_rule')
->enabled(false) // Disable rule
->register();
```
---
##### `lock(): Rules`
Lock the rule to prevent overwriting or unregistering.
Locked rules cannot be overwritten by another rule with the same ID, nor can they be unregistered. This guards the entire rule — conditions, actions, and metadata — from replacement.
**Returns**: `Rules` - Fluent interface
**Example**:
```php
// Lock a safety-critical rule
Rules::create('no-cache-post')->lock()->order(0)
->when_all()->request_method('POST')
->then()->set_cache(false)->lock()
->register();
// Attempting to overwrite is silently rejected
Rules::create('no-cache-post') // Same ID — rejected
->when_all()
->then()->set_cache(true)
->register();
// Attempting to unregister is also rejected
Rules::unregister('no-cache-post'); // Returns false
```
**Key Points**:
- Protects the rule definition (conditions + actions + metadata)
- Separate from `ActionBuilder::lock()` which locks action *execution*
- Use both together for maximum protection on core rules
---
##### `when(): ConditionBuilder`
Start building conditions with match_all logic.
**Returns**: `ConditionBuilder` - Condition builder instance
**Example**:
```php
Rules::create('my_rule')
->when()
->request_url('/api/*')
->request_method('GET')
->then()
->custom('action')
->register();
```
---
##### `when_all(): ConditionBuilder`
Start building conditions with ALL logic (AND).
**Returns**: `ConditionBuilder`
**Example**:
```php
Rules::create('my_rule')
->when_all()
->condition1()
->condition2()
->then()->custom('action')
->register();
```
---
##### `when_any(): ConditionBuilder`
Start building conditions with ANY logic (OR).
**Returns**: `ConditionBuilder`
**Example**:
```php
Rules::create('my_rule')
->when_any()
->condition1()
->condition2()
->then()->custom('action')
->register();
```
---
##### `when_none(): ConditionBuilder`
Start building conditions with NONE logic (NOT).
**Returns**: `ConditionBuilder`
**Example**:
```php
Rules::create('my_rule')
->when_none()
->condition1()
->condition2()
->then()->custom('action')
->register();
```
---
##### `and(): Rules`
Finalize the current condition group and prepare for the next one. Used to chain multiple condition groups with different match types. All groups are combined with AND logic.
**Returns**: `Rules` - Fluent interface (call `when_all()`, `when_any()`, or `when_none()` next)
**Example**:
```php
Rules::create('my_rule')
->when_any()
->post_type('page')
->post_type('post')
->and()->when_none()
->user_role('subscriber')
->then()
->custom('action')
->register();
```
---
##### `then(?array $actions = null): ActionBuilder`
Start building actions.
**Parameters**:
- `$actions` (array|null): Array of action configurations (optional)
**Returns**: `ActionBuilder` - Action builder instance
**Example**:
```php
Rules::create('my_rule')
->when()->request_url('*')
->then()
->custom('action1')
->custom('action2')
->register();
```
---
##### `on(string $hook, int $priority = 10): Rules`
Register rule on WordPress hook.
**Parameters**:
- `$hook` (string): WordPress hook name
- `$priority` (int): Hook priority
**Returns**: `Rules` - Fluent interface
**Example**:
```php
Rules::create('my_rule', 'wp')
->on('init', 10)
->when()->is_user_logged_in()
->then()->custom('action')
->register();
```
---
##### `register(): void`
Register rule with MilliRules.
If a rule with the same ID already exists, the one with the **higher `order()` wins** — and on a tie the incoming rule replaces the existing one, so a stored rule can take over a built-in registered with the same number. Since the default order is `10` on both sides, re-registering an ID replaces it unless you have set the orders apart.
A rule that loses is discarded with a warning; the ID keeps the rule that was already there. This makes the outcome independent of which file happened to load first. [Locked rules](#lock-rules) are never replaced, at any order.
Use [`discarded_orders()`](#static-discarded_ordersstring-rule_id-array) to find out whether a rule you cannot see is competing for the same ID.
**Returns**: `void`
**Example**:
```php
Rules::create('my_rule')
->when()->request_url('*')
->then()->custom('action')
->register(); // Must call to activate rule
// Same ID, same default order → replaces the rule
Rules::create('my_rule')
->when()->request_url('/api/*')
->then()->custom('different_action')
->register(); // Replaces previous 'my_rule'
// Same ID, lower order → discarded, the order 20 rule stays
Rules::create('ranked')->order(20)->then()->custom('a')->register();
Rules::create('ranked')->order(10)->then()->custom('b')->register(); // ignored
```
> **Rules registered after their phase has run**
>
> A `php`-typed rule registered after the PHP phase has already executed can never run — that phase happens once, before the framework loads. Such a rule is moved to the WordPress phase automatically, with a debug log line, so it still governs the response instead of failing silently.
---
##### `unregister(string $rule_id): bool`
Remove a rule by its ID.
**Parameters**:
- `$rule_id` (string): The ID of the rule to remove
**Returns**: `bool` - True if rule was found and removed, false otherwise
**Example**:
```php
// Remove a rule
$removed = Rules::unregister('my_rule');
// Check if removal was successful
if ($removed) {
error_log('Rule was removed');
} else {
error_log('Rule not found');
}
// Use case: Child theme disabling parent rule
Rules::unregister('parent_theme_cache_rule');
// Use case: Environment-specific disabling
if (wp_get_environment_type() === 'production') {
Rules::unregister('debug_logging_rule');
}
```
---
##### `register_condition(string $type, callable $callback): ConditionMeta`
Register custom condition callback.
Returns a `ConditionMeta` instance for fluent declaration of metadata (label, description, categories, operators, arguments).
**Parameters**:
- `$type` (string): Condition type identifier
- `$callback` (callable): Callback function `function($args, Context $context): bool`
**Returns**: `ConditionMeta` — fluent metadata declaration for the registered condition
**Example**:
```php
// Simple condition (return value can be ignored)
Rules::register_condition('is_weekend', function($args, Context $context) {
return date('N') >= 6;
});
// With full metadata for UI introspection
Rules::register_condition('is_weekend', function($args, Context $context) {
return date('N') >= 6;
})
->label('Is Weekend')
->description('Matches on Saturdays and Sundays.')
->categories('date')
->operators('=', '!=');
```
For class-based conditions, override `set_meta()` on your `BaseCondition` subclass:
```php
class RequestUrl extends BaseCondition {
public static function set_meta(ConditionMeta $meta): void
{
$meta
->label('Request URL')
->description('Match the current request URL.')
->categories('request')
->operators('=', '!=', 'LIKE', 'REGEXP', 'IN', 'NOT IN')
->args()
->string('value')->label('URL Pattern')->required();
}
}
```
---
##### `get_condition_meta(string $type): ?ConditionMeta`
Get the full metadata for a registered condition type.
Resolves metadata from either the callback-based registry (populated by `register_condition()`) or the class-based `BaseCondition::set_meta()` method. For class-based conditions, the argument mapping from `BaseCondition::get_argument_mapping()` is automatically included.
Results are cached per type.
**Parameters**:
- `$type` (string): Condition type identifier
**Returns**: `ConditionMeta|null` — metadata for the condition, or `null` if not found
**Example**:
```php
$meta = Rules::get_condition_meta('request_url');
if ($meta) {
$label = $meta->get_label(); // 'Request URL'
$operators = $meta->get_operators(); // ['=', '!=', 'LIKE', ...]
$mapping = $meta->get_argument_mapping(); // ['value']
$args = $meta->get_arguments(); // array
$data = $meta->to_array(); // For REST/JSON serialization
}
```
---
#### `ConditionMeta` — fluent condition metadata
`ConditionMeta` is the metadata container for condition types. Parallel to `ActionMeta` but with operators instead of scope.
##### Core fields
- `->label(string $label)` — human-readable name
- `->description(string $description)` — help text
- `->categories(string ...$categories)` — one or more UI grouping categories
- `->operators(string ...$operators)` — supported comparison operators (e.g., `'='`, `'!='`, `'LIKE'`, `'IN'`)
- `->argument_mapping(array $mapping)` — how builder args map to config keys (auto-set for class-based conditions)
- `->args()` → `ArgumentsBuilder` — same walking-builder pattern as ActionMeta
- `->extend(string $key, $value)` — plugin-specific metadata bag
##### `->to_array(): array` — wire format
```php
[
'type' => string,
'label' => string,
'description' => string,
'categories' => array,
'operators' => array,
'argument_mapping' => array,
'arguments' => array,
'extensions' => array,
]
```
---
##### `register_action(string $type, callable $callback): ActionMeta`
Register custom action callback.
Returns an `ActionMeta` instance for fluent declaration of action metadata (scope, label, description, category).
**Parameters**:
- `$type` (string): Action type identifier
- `$callback` (callable): Callback function `function($args, Context $context): void`
**Returns**: `ActionMeta` — fluent metadata declaration for the registered action
**Example**:
```php
// Simple action (return value can be ignored)
Rules::register_action('log', function($args, Context $context) {
error_log($args['value'] ?? '');
});
// Paired actions with shared scope (value-level locking when locked)
Rules::register_action('add_flag', $addCallback)->scope('flag');
Rules::register_action('remove_flag', $removeCallback)->scope('flag');
// With full metadata for UI introspection
Rules::register_action('add_flag', $addCallback)
->scope('flag')
->label('Add Flag')
->description('Tag the response with a flag for bulk invalidation.')
->categories('flags')
->args()
->string(0)->label('Flag')->required();
```
For class-based actions, override two static methods on your `BaseAction` subclass:
- `get_scope()` — returns the lock scope as a plain string. **Must not use framework-specific functions** (e.g., translation) because the engine calls it during rule execution, which may happen during early bootstrap.
- `set_meta(ActionMeta $meta)` — configures consumer-facing metadata (label, description, categories, args). Called only by consumer code like UIs or REST endpoints, which always run after the framework has initialized.
```php
class AddFlag extends BaseAction {
// Engine-relevant. Called during early bootstrap — plain strings only.
public static function get_scope(): string
{
return 'flag';
}
// Consumer-relevant. Called after framework initialization.
public static function set_meta(ActionMeta $meta): void
{
$meta
->label('Add Flag')
->description('Tag the response with a flag.')
->categories('flags');
}
public function execute(Context $context): void { /* ... */ }
public function get_type(): string { return 'add_flag'; }
}
```
**Why this signature**: the engine owns the action type string (from the registration lookup), so it constructs the `ActionMeta` and passes it in. Subclasses can't accidentally set the wrong type or forget to call `parent::set_meta()` — there's no boilerplate to forget.
**Why scope is split from `set_meta()`**: the engine reads scope during rule execution, which may happen during early bootstrap before the application framework has fully initialized. If scope were set inside `set_meta()` alongside framework-dependent calls (e.g., translation functions), the engine couldn't read it safely. The split keeps the hot path runtime-safe.
---
##### `get_action_scope(string $type): string`
Get the lock scope for an action type — **engine hot path, runtime-safe**.
Fast-path accessor that never calls `set_meta()`. Used internally by `RuleEngine::build_lock_key()`. Safe to call during early bootstrap before the application framework has initialized.
**Parameters**:
- `$type` (string): Action type identifier
**Returns**: `string` — the scope identifier, or `''` for unknown or unscoped actions
**Example**:
```php
$scope = Rules::get_action_scope('add_flag'); // 'flag'
$scope = Rules::get_action_scope('set_ttl'); // '' (unscoped)
```
Resolution order:
1. Callback-based: reads from the meta set at registration time (`register_action()->scope()`).
2. Class-based: calls `$class::get_scope()` directly.
Results are cached per type.
---
##### `get_action_meta(string $type): ?ActionMeta`
Get the full metadata for a registered action type.
Resolves metadata from either the callback-based registry (populated by `register_action()`) or the class-based `BaseAction::set_meta()` method. Results are cached per type.
**May require framework functions**: for class-based actions, this calls `set_meta()`, which may use framework-specific functions (e.g., translation). Do NOT call this during early bootstrap before the framework has initialized — use `get_action_scope()` instead if you only need the scope.
**Parameters**:
- `$type` (string): Action type identifier
**Returns**: `ActionMeta|null` — metadata for the action, or `null` if not found
**Example**:
```php
$meta = Rules::get_action_meta('add_flag');
if ($meta) {
$label = $meta->get_label(); // 'Add Flag'
$scope = $meta->get_scope(); // 'flag' (synced from $class::get_scope())
$categories = $meta->get_categories(); // ['flags']
$arguments = $meta->get_arguments(); // array
$icon = $meta->get_extension('millicache:icon'); // plugin-specific
$data = $meta->to_array(); // For REST/JSON serialization
}
```
---
##### `get_all_condition_metas(): array`
Get metadata for all available condition types.
Discovers all condition types from both class-based (via namespace scanning) and callback-based registrations, and resolves their metadata.
Results are cached after first call. The cache is cleared when new conditions are registered.
**Returns**: `array` — map of type string to ConditionMeta
**Example**:
```php
$conditions = Rules::get_all_condition_metas();
foreach ($conditions as $type => $meta) {
echo $type; // 'post_type'
echo $meta->get_label(); // 'Post Type'
echo $meta->get_operators(); // ['=', '!=', 'IN', 'NOT IN']
}
```
---
##### `get_all_action_metas(): array`
Get metadata for all available action types.
Discovers all action types from both class-based (via namespace scanning) and callback-based registrations, and resolves their metadata.
Results are cached after first call. The cache is cleared when new actions are registered.
**Returns**: `array` — map of type string to ActionMeta
**Example**:
```php
$actions = Rules::get_all_action_metas();
foreach ($actions as $type => $meta) {
echo $type; // 'add_flag'
echo $meta->get_label(); // 'Add Flag'
echo $meta->get_scope(); // 'flag'
}
```
---
##### `get_all_placeholder_metas(): array`
Get every placeholder category a rule value may use, as `{category.key}`.
Placeholders come from two places, and a caller that wants to tell a valid placeholder from a mistyped one needs both:
- **Context classes** found in the registered `Contexts` namespaces (`source: 'context'`)
- **Categories registered** with [`register_placeholder()`](#register_placeholderstring-category-callable-resolver) (`source: 'custom'`)
This matters because an unresolvable placeholder is **left in the value verbatim** rather than raising an error — so `{reqest.host}` silently turns a per-visitor value into a constant string. Validate against this catalog before storing a rule.
An empty `keys` array means the key is chosen by the caller rather than by the context — a cookie name, a query parameter, a WordPress query var. A non-empty `keys` array is closed: anything outside it will not resolve.
Contexts that are unavailable in the current environment are omitted, so a bare PHP process does not advertise `{post.id}`. Where a context class and a custom resolver share a name, the context wins, since it is the one carrying a label and a key set.
Results are **not** cached: custom resolvers can be registered at any point in the request.
`description` is one sentence naming a concrete `{category.key}`, written for both a person choosing a placeholder in a rule builder and an AI client that has to pick one without guessing. It is empty for a custom resolver, which has no way to supply one. The strings are raw English by design — consumers exclude vendored dependencies from POT extraction, so translate on your side and use these as the fallback.
**Returns**: `array, source: string}>` — map of category to metadata
**Example**:
```php
$placeholders = Rules::get_all_placeholder_metas();
foreach ($placeholders as $category => $meta) {
echo $category; // 'request'
echo $meta['label']; // 'Request'
echo $meta['description']; // 'The current HTTP request, for example {request.host} ...'
print_r($meta['keys']); // ['method', 'uri', 'scheme', 'host', ...]
echo $meta['source']; // 'context'
}
// Reject a mistyped placeholder before the rule is stored.
function placeholder_is_known(string $placeholder): bool {
$catalog = Rules::get_all_placeholder_metas();
[$category, $key] = array_pad(explode('.', $placeholder, 2), 2, '');
if (! isset($catalog[$category])) {
return false;
}
$keys = $catalog[$category]['keys'];
// Empty keys = caller-named (cookie, param, header, query var).
return empty($keys) || in_array($key, $keys, true);
}
placeholder_is_known('request.host'); // true
placeholder_is_known('reqest.host'); // false — mistyped category
placeholder_is_known('request.hostname'); // false — not a request key
placeholder_is_known('cookie.anything'); // true — caller-named
```
---
##### `validate(array $rule): array`
Validate a rule configuration against the engine's registry.
Checks that the rule's `match_type`, condition types, operators, action types, and action arguments are all recognized by the engine. Returns an array of plain-English error strings (empty array = valid).
This validates engine-level concerns only. Storage-layer concerns (ID format, title length, order range) are the consumer's responsibility.
**Parameters**:
- `$rule` (array): The rule configuration array
**Returns**: `array` — error messages; empty if valid
**Example**:
```php
$errors = Rules::validate([
'match_type' => 'all',
'conditions' => [
['type' => 'post_type', 'operator' => '=', 'value' => 'page'],
],
'actions' => [
['type' => 'set_ttl', 'ttl' => 3600],
],
]);
if (! empty($errors)) {
// Handle validation errors.
foreach ($errors as $error) {
echo $error; // "Condition #1 has unknown type 'foo'."
}
}
```
**Validates**:
- `match_type` against `Rules::MATCH_TYPES`
- Condition types exist in the registry
- Condition operators are in the condition's declared operators (if any)
- Condition groups recursively (match_type + nested conditions)
- Action types exist in the registry
- Action arguments pass `ArgumentSchema::validate()`
---
#### Constants
##### `Rules::MATCH_TYPES`
Array of match types supported by the rule engine.
```php
Rules::MATCH_TYPES // ['all', 'any', 'none']
```
Use this instead of hardcoding match type values:
```php
// In validation
if (! in_array($match_type, Rules::MATCH_TYPES, true)) { /* ... */ }
// In UI dropdowns
foreach (Rules::MATCH_TYPES as $type) { /* ... */ }
```
---
#### `ActionMeta` — fluent action metadata
`ActionMeta` is the declarative metadata container for an action type. Obtain it from `Rules::register_action()` (for callback-based actions) or override `BaseAction::set_meta()` (for class-based actions).
##### Core fields
- `->scope(string $scope)` — lock scope (engine-relevant; see [Scoped Locking](/docs/millirules/02-core-concepts/01-concepts#scoped-locking-for-paired-actions))
- `->label(string $label)` — human-readable name
- `->description(string $description)` — help text
- `->categories(string ...$categories)` — one or more UI grouping categories
##### `->args(): ArgumentsBuilder`
Enter the arguments declaration context. Returns an internal `ArgumentsBuilder` instance that collects argument schemas via type factories. The builder is cached — calling `args()` multiple times returns the same instance.
```php
$meta->args()
->integer('ttl')->format('seconds')->default(3600)->min(0)
->string('reason')->default('');
```
Inside the builder, each type factory (`->integer($key)`, `->string($key)`, etc.) creates a new `ArgumentSchema` and returns it for continued configuration. To declare another argument, just call another type factory — it "walks" back to the builder and starts a new one.
Preserves declaration order (no auto-sorting). Any meta-level methods called after `->args()` (like `->extend()` or `->categories()`) are automatically forwarded back to the `ActionMeta` via `__call()`, so the chain can continue seamlessly:
```php
$meta
->label(__('Set TTL'))
->args()
->integer('ttl')->default(3600)
->string('reason')->default('')
->extend('millicache:icon', 'clock'); // forwarded to $meta
```
See [ArgumentSchema](#argumentschema--argument-metadata) below for the per-argument API.
##### `->extend(string $key, mixed $value): self`
Attach plugin-specific metadata under a namespaced key. MilliRules stores the value but never interprets it. Use this for anything that isn't part of MilliRules core: icons, conditional visibility rules, documentation URLs, plugin-defined widgets.
```php
->extend('millicache:icon', 'clock')
->extend('seo-redirects:default_status', 301)
->extend('docs:url', 'https://example.com/actions/set-ttl')
```
**Namespacing convention**: use `plugin-slug:field-name` to avoid collisions. MilliRules does not enforce this — the convention is the contract.
##### Extension bag getters
- `->get_extension(string $key): mixed|null` — returns the value, or `null` if not set
- `->has_extension(string $key): bool` — distinguishes "set to null" from "not set"
- `->get_extensions(): array` — returns the full keyed bag
##### `->to_array(): array` — wire format
```php
[
'type' => string,
'scope' => string,
'label' => string,
'description' => string,
'categories' => array,
'arguments' => array, // each via ArgumentSchema::to_array()
'extensions' => array, // plugin-specific bag
]
```
This is the stable, REST-serializable format for transmitting action metadata to consumers.
---
#### `ArgumentSchema` — argument metadata
`ArgumentSchema` is the declarative format for action arguments. Consumer code never references this class directly — schemas are obtained via `$meta->args()->type($key)`. The class is internal but documented here so you understand what your `->args()` chain is producing.
Every consumer that introspects actions (UIs, CLIs, docs generators, validators) reads the same schema. MilliRules' `RuleEngine` does **not** use `ArgumentSchema` at runtime — it's purely metadata.
##### Type system
Six core types cover all engine-level data shapes:
| Type | Coercion | min/max semantics | Default |
|------------|-------------------|-------------------|------------|
| `string` | `(string)` cast | length bounds | `''` |
| `integer` | `(int)` cast | value bounds | `0` |
| `number` | `(float)` cast | value bounds | `0.0` |
| `boolean` | truthy check | — | `false` |
| `choice` | pass-through | — | first option or `null` |
| `choices` | `(array)` + filter to valid options | — | `[]` |
Everything else (`url`, `email`, `seconds`, `regex`, `date`, etc.) is expressible as a core type + `format`:
```php
$meta->args()
->integer('ttl')->format('seconds') // TTL input
->string('homepage')->format('url') // URL field
->string('contact')->format('email') // email field
->string('pattern')->format('regex'); // regex pattern
```
MilliRules stores `format` but never interprets it. Consumers pick their own vocabulary and handle format-specific rendering/validation.
##### Creating schemas
Schemas are created exclusively via the builder's type factories, obtained from `$meta->args()`:
```php
$meta->args()
->string($key) // $key is int|string
->integer($key)
->number($key)
->boolean($key)
->choice($key)
->choices($key);
```
You never write `new ArgumentSchema(...)` yourself.
##### Walking: chain to the next argument
Type factories are also available **on an existing schema** and delegate back to the builder to start a new argument:
```php
$meta->args()
->integer('ttl')->default(3600) // schema for 'ttl'
->string('reason')->default(''); // ->string() walks back; new schema for 'reason'
```
This is why you can chain multiple arguments in a single fluent expression without restarting from `$meta->args()`.
##### Fluent setters (config)
- `->format(string $format)` — consumer-defined format hint
- `->label(string $label)` — human-readable name
- `->description(string $description)` — help text
- `->required(bool $required = true)` — mark as mandatory
- `->default(mixed $value)` — default value (rejects closures)
- `->min(int $min)` / `->max(int $max)` — length (string) or value (integer/number) bounds; throws on other types
- `->options(array $options)` — allowed values for `choice`/`choices` types; throws on other types
##### `options()` format
Accepts either simple or structured form:
```php
// Simple — value == label
->options(['GET', 'POST', 'PUT'])
// Structured — separate value and label
->options([
['value' => 'get', 'label' => 'GET Request'],
['value' => 'post', 'label' => 'POST Request'],
])
```
Stored internally as the structured form. `to_array()` always emits the structured form.
##### Runtime guards
Calling incompatible setters throws `InvalidArgumentException` at declaration time (i.e., at class-load time for class-based actions):
```php
$meta->args()->string('k')->min(5); // OK: length bound
$meta->args()->boolean('k')->min(5); // ✗ throws
$meta->args()->integer('k')->options(['a', 'b']); // ✗ throws
```
##### Getters
- `->get_key(): int|string`
- `->get_type(): string`
- `->get_format(): string`
- `->get_label(): string`
- `->get_description(): string`
- `->get_default(): mixed`
- `->has_default(): bool` — distinguishes "default is null" from "no default set"
- `->is_required(): bool`
- `->get_min(): ?int`
- `->get_max(): ?int`
- `->get_options(): array`
##### `validate(mixed $value): ?string`
Consumer utility. Returns `null` if the value is valid, or a plain English error message string if invalid. MilliRules ships no translation layer — consumers wrap the returned string in their own i18n if needed.
```php
// Retrieve schemas via the meta's get_arguments():
$schemas = Rules::get_action_meta('set_ttl')->get_arguments();
$schema = $schemas[0];
$schema->validate(50); // null (valid)
$schema->validate(150); // "Argument 'ttl' must be at most 100"
$schema->validate('abc'); // "Argument 'ttl' must be an integer"
```
Note: `RuleEngine` does not call `validate()`. It's an opt-in utility for consumers (validators, UIs, CLIs).
##### `sanitize(mixed $value): mixed`
Consumer utility. Coerces a raw value to the declared type.
```php
$integer_schema->sanitize('3600'); // 3600
$boolean_schema->sanitize('yes'); // true
$choices_schema->sanitize(['a', 'invalid', 'b']); // ['a', 'b']
```
Null values are replaced with the default if set, otherwise the type's zero value (`''`, `0`, `0.0`, `false`, first option, or `[]`).
##### `to_array(): array` — wire format
```php
[
'key' => int|string,
'type' => string,
'format' => string,
'label' => string,
'description' => string,
'default' => mixed,
'has_default' => bool,
'required' => bool,
'min' => int|null,
'max' => int|null,
'options' => array,
]
```
---
##### `register_placeholder(string $category, callable $resolver): void`
Register custom placeholder resolver.
**Parameters**:
- `$category` (string): Placeholder category
- `$resolver` (callable): Resolver function `function($context, $parts): string`
**Returns**: `void`
**Example**:
```php
Rules::register_placeholder('custom', function($context, $parts) {
return $context['custom'][$parts[0]] ?? '';
});
```
---
## Builders
### ConditionBuilder
Fluent builder for rule conditions.
**Namespace**: `MilliRules`
#### Methods
##### `match_all(): ConditionBuilder`
Use AND logic for conditions.
**Returns**: `ConditionBuilder`
---
##### `match_any(): ConditionBuilder`
Use OR logic for conditions.
**Returns**: `ConditionBuilder`
---
##### `match_none(): ConditionBuilder`
Use NOT logic for conditions.
**Returns**: `ConditionBuilder`
---
##### `custom(string $type, $arg = null): ConditionBuilder`
Add custom condition.
**Parameters**:
- `$type` (string): Condition type
- `$arg` (mixed): Condition argument (value, config array, etc.)
**Returns**: `ConditionBuilder`
**Example**:
```php
->when()
->custom('is_weekend')
->custom('time_range', ['start' => 9, 'end' => 17])
```
---
##### `add_namespace(string $namespace): ConditionBuilder`
Add condition namespace for class resolution.
**Parameters**:
- `$namespace` (string): Fully qualified namespace
**Returns**: `ConditionBuilder`
---
##### `__call(string $method, array $args): mixed`
Magic method for dynamic condition creation.
Converts method calls to condition types:
- `request_url()` → `RequestUrlCondition`
- `is_user_logged_in()` → `IsUserLoggedInCondition`
---
### ActionBuilder
Fluent builder for rule actions.
**Namespace**: `MilliRules`
#### Methods
##### `custom(string $type, $arg = null): ActionBuilder`
Add custom action.
**Parameters**:
- `$type` (string): Action type
- `$arg` (mixed): Action argument (config array, value, etc.)
**Returns**: `ActionBuilder`
**Example**:
```php
->then()
->custom('log', ['value' => 'message'])
->custom('send_email', ['to' => 'admin@example.com'])
```
---
##### `lock(): ActionBuilder`
Mark the last action as locked.
Locked actions prevent subsequent actions from changing the same setting. How locking works depends on whether the action was registered with a **scope**:
- **Unscoped actions** (default): locks by action type — `set_ttl(300)->lock()` blocks all `set_ttl` calls
- **Scoped actions**: locks by scope + value — `add_flag('x')->lock()` only blocks operations on `'x'` within the same scope
**Returns**: `ActionBuilder`
**Example — unscoped (type-level locking)**:
```php
// Rule 1 (order: 10) - Disable cache for logged-in users
Rules::create('no-cache-logged-in')->order(10)
->when()->is_user_logged_in()
->then()->do_cache(false)->lock() // Lock the cache setting
->register();
// Rule 2 (order: 20) - This cache action will be IGNORED
Rules::create('cache-api')->order(20)
->when()->request_url('/api/*')
->then()->do_cache(true) // Blocked - do_cache is locked
->register();
```
**Example — scoped (value-level locking)**:
```php
// Consumer registers paired actions with shared scope
Rules::register_action('add_flag', $callback)->scope('flag');
Rules::register_action('remove_flag', $callback)->scope('flag');
// Lock a specific flag value
->then()->add_flag('system-flag')->lock() // Locks 'flag:system-flag'
// Later rules:
->then()->add_flag('custom-flag') // Allowed — different lock key
->then()->remove_flag('system-flag') // Blocked — same lock key
```
**Key Points**:
- Unscoped: locks are per action type
- Scoped: locks are per scope + value (cross-type within the same scope)
- Different action types/scopes can still execute
- Lock only applies if the rule's conditions match
- Locks reset on each rule execution
---
##### `add_namespace(string $namespace): ActionBuilder`
Add action namespace for class resolution.
**Parameters**:
- `$namespace` (string): Fully qualified namespace
**Returns**: `ActionBuilder`
---
##### `__call(string $method, array $args): mixed`
Magic method for dynamic action creation.
---
## Interfaces
### PackageInterface
Interface for all packages.
**Namespace**: `MilliRules\Interfaces`
#### Methods
##### `get_name(): string`
Get unique package name.
**Returns**: `string` - Package name
---
##### `get_namespaces(): array`
Get condition and action namespaces.
**Returns**: `array` - Array of namespace strings
---
##### `is_available(): bool`
Check if package is available in current environment.
**Returns**: `bool` - True if available
---
##### `get_required_packages(): array`
Get required package names.
**Returns**: `array` - Array of package names
---
##### `build_context(): array`
Build context data for this package.
**Returns**: `array` - Context data
---
##### `get_placeholder_resolver(array $context)`
Get placeholder resolver for this package.
**Parameters**:
- `$context` (array): Execution context
**Returns**: `callable|null` - Resolver function or null
---
##### `register_rule(array $rule, array $metadata): void`
Register rule with package.
**Parameters**:
- `$rule` (array): Rule configuration
- `$metadata` (array): Rule metadata
**Returns**: `void`
---
##### `execute_rules(array $rules, array $context): array`
Execute rules for this package.
**Parameters**:
- `$rules` (array): Rules to execute
- `$context` (array): Execution context
**Returns**: `array` - Execution result
---
### ConditionInterface
Interface for all conditions.
**Namespace**: `MilliRules\Interfaces`
#### Methods
##### `matches(array $context): bool`
Check if condition matches.
**Parameters**:
- `$context` (array): Execution context
**Returns**: `bool` - True if matches
---
##### `get_type(): string`
Get condition type identifier.
**Returns**: `string` - Condition type
---
### ActionInterface
Interface for all actions.
**Namespace**: `MilliRules\Interfaces`
#### Methods
##### `execute(Context $context): void`
Execute action.
**Parameters**:
- `$context` (array): Execution context
**Returns**: `void`
---
##### `get_type(): string`
Get action type identifier.
**Returns**: `string` - Action type
---
## Base Classes
### BasePackage
Abstract base class for packages.
**Namespace**: `MilliRules\Packages`
Provides default implementations for most `PackageInterface` methods.
**Must Override**:
- `get_name(): string`
- `get_namespaces(): array`
- `is_available(): bool`
**Can Override**:
- `get_required_packages(): array` - Defaults to `[]`
- `build_context(): array` - Defaults to `[]`
- `get_placeholder_resolver()` - Defaults to `null`
---
### BaseCondition
Abstract base class for conditions.
**Namespace**: `MilliRules\Conditions`
Provides operator support and comparison logic.
#### Methods
##### `__construct(array $config, Context $context)`
Constructor.
**Parameters**:
- `$config` (array): Condition configuration
- `$context` (array): Execution context
---
##### `matches(array $context): bool`
Check if condition matches (implemented).
**Parameters**:
- `$context` (array): Execution context
**Returns**: `bool`
---
##### `abstract protected function get_actual_value(Context $context)`
Get actual value to compare (must implement).
**Parameters**:
- `$context` (array): Execution context
**Returns**: `mixed` - Actual value
---
##### `static public function compare_values($actual, $expected, string $operator = '='): bool`
Compare values using operator.
**Parameters**:
- `$actual` (mixed): Actual value
- `$expected` (mixed): Expected value
- `$operator` (string): Comparison operator
**Returns**: `bool` - True if comparison matches
---
### BaseAction
Abstract base class for actions.
**Namespace**: `MilliRules\Actions`
Provides placeholder resolution.
#### Methods
##### `__construct(array $config, Context $context)`
Constructor.
**Parameters**:
- `$config` (array): Action configuration
- `$context` (array): Execution context
---
##### `protected function resolve_value(string $value): string`
Resolve placeholders in value.
**Parameters**:
- `$value` (string): Value with placeholders
**Returns**: `string` - Resolved value
---
##### `abstract public function execute(Context $context): void`
Execute action (must implement).
**Parameters**:
- `$context` (array): Execution context
**Returns**: `void`
---
## PackageManager
Static manager for packages.
**Namespace**: `MilliRules`
#### Methods
##### `static register_package(PackageInterface $package): void`
Register package.
**Parameters**:
- `$package` (PackageInterface): Package instance
**Returns**: `void`
---
##### `static load_packages(?array $package_names = null): array`
Load packages by name.
**Parameters**:
- `$package_names` (array|null): Package names (null = load all available)
**Returns**: `array` - Loaded package names
---
##### `static get_loaded_packages(): array`
Get loaded package instances.
**Returns**: `array` - Array of PackageInterface instances
---
##### `static get_loaded_package_names(): array`
Get loaded package names.
**Returns**: `array` - Array of package names
---
##### `static get_package(string $name): ?PackageInterface`
Get package by name.
**Parameters**:
- `$name` (string): Package name
**Returns**: `PackageInterface|null` - Package instance or null
---
##### `static is_package_loaded(string $name): bool`
Check if package is loaded.
**Parameters**:
- `$name` (string): Package name
**Returns**: `bool` - True if loaded
---
##### `static has_packages(): bool`
Check if any packages are loaded.
**Returns**: `bool` - True if packages exist
---
##### `static build_context(): array`
Build context from all loaded packages.
**Returns**: `array` - Aggregated context
---
##### `static discarded_orders(string $rule_id): array`
The orders of registrations that lost this ID to another rule.
The registry only ever holds the winner, so this is what tells a caller that a rule it cannot see is competing for the same ID — for example a stored rule whose `order()` sits below a built-in's. Each distinct order appears once, however many times it was attempted.
**Parameters**:
- `$rule_id` (string): The rule ID
**Returns**: `array` - Orders that were discarded, empty if none
**Example**:
```php
Rules::create('ranked')->order(20)->then()->custom('a')->register();
Rules::create('ranked')->order(10)->then()->custom('b')->register();
PackageManager::discarded_orders('ranked'); // [10]
```
---
##### `static has_executed(string $name): bool`
Whether a package's rules have already run this request.
A rule registered for that package afterwards can no longer execute, which is why a late `php` rule is [moved to the WordPress phase](#register-void).
**Parameters**:
- `$name` (string): Package name, e.g. `'PHP'` or `'WP'`
**Returns**: `bool` - True if that phase has run
---
## RuleEngine
Rule execution engine.
**Namespace**: `MilliRules`
#### Methods
##### `execute(array $rules, array $context, ?array $allowed_packages = null): array`
Execute rules.
**Parameters**:
- `$rules` (array): Rules to execute
- `$context` (array): Execution context
- `$allowed_packages` (array|null): Allowed package names
**Returns**: `array` - Execution result
---
##### `static register_namespace(string $type, string $namespace): void`
Register namespace for class resolution.
**Parameters**:
- `$type` (string): Type (`'condition'` or `'action'`)
- `$namespace` (string): Namespace string
**Returns**: `void`
---
## Next Steps
- **[Real-World Examples](/docs/millirules/04-advanced/01-examples)** - See API usage in complete examples
- **[Getting Started](/docs/millirules/01-getting-started/01-introduction)** - Basic usage guide
- **[Building Rules](/docs/millirules/02-core-concepts/03-building-rules)** - Fluent API guide
---
**Ready for complete examples?** Continue to [Real-World Examples](/docs/millirules/04-advanced/01-examples) to see the API in action with full working code.
---
Canonical: https://www.millipress.com/docs/millirules/05-reference/04-changelog
---
title: 'MilliRules Changelog'
description: 'Version history for the MilliRules PHP rules engine: new features, bug fixes, and breaking changes for every release, from 0.1.0 to the current version.'
menu_order: 40
---
# Changelog
## [1.3.0](https://github.com/MilliPress/MilliRules/compare/v1.2.1...v1.3.0) (2026-08-14)
### Features
* Decide same-ID collisions by order instead of load sequence ([81f39bf](https://github.com/MilliPress/MilliRules/commit/81f39bf942e043bd40fca4cf04e1828194e410eb))
* Expose a catalog of available placeholders for rule builders ([1642240](https://github.com/MilliPress/MilliRules/commit/16422409658d491bd56162e8f28dbfec32bd6686))
### Bug Fixes
* Move a php rule to the WordPress phase when that phase is over ([0821a4a](https://github.com/MilliPress/MilliRules/commit/0821a4a65b4982ff3b41a391b7f79a9e300cd009))
* Resolve {cookie.x} and {param.x} from the data the engine builds ([0d0ab85](https://github.com/MilliPress/MilliRules/commit/0d0ab85eeb01a7ec9f63d051e86a921d855f8a34))
* Skip an action whose placeholder resolved to nothing ([949e7a2](https://github.com/MilliPress/MilliRules/commit/949e7a283599ec00b983c15ae5e0d031791a96c4))
### Refactoring
* **logger:** Standardize log message formatting for consistency ([54c6ba2](https://github.com/MilliPress/MilliRules/commit/54c6ba24c87d61dec044e817a34e07aa35b25470))
* Register package placeholders when the package registers ([90385ea](https://github.com/MilliPress/MilliRules/commit/90385eaa1fc96a8fbb5ac90c78fba5776e71face))
## [1.2.1](https://github.com/MilliPress/MilliRules/compare/v1.2.0...v1.2.1) (2026-07-16)
### Bug Fixes
* never let a foreign condition or action class fatal the request ([45c11bf](https://github.com/MilliPress/MilliRules/commit/45c11bf9a351e5d3e0ad2499774b1bb42adf3f14))
## [1.2.0](https://github.com/MilliPress/MilliRules/compare/v1.1.6...v1.2.0) (2026-07-10)
### Features
* expose which rules override an earlier rule of the same ID ([e1d04d9](https://github.com/MilliPress/MilliRules/commit/e1d04d9341142f699258770a4e545af88e4f81e2))
### Refactoring
* mark overrides on the rule instead of a side array ([4fe9ac7](https://github.com/MilliPress/MilliRules/commit/4fe9ac71909dc98c33b7f99793c61225c9f3720f))
## [1.1.6](https://github.com/MilliPress/MilliRules/compare/v1.1.5...v1.1.6) (2026-05-28)
### Features
* add current_site condition for multisite blog targeting ([ee02693](https://github.com/MilliPress/MilliRules/commit/ee0269375718d44d8925796106851d6ba0061837))
* register rules from array config via Rules::register_rule() ([2e4a8a5](https://github.com/MilliPress/MilliRules/commit/2e4a8a51b8064c2d5e3843f114f2bd8675e1562e))
### Bug Fixes
* **docs:** Update placeholder syntax from colon to dot notation ([ccd1243](https://github.com/MilliPress/MilliRules/commit/ccd12437cc759553d0a06414dd25180bf34a1acc))
* honor NOT IN semantics for conditions with array values ([1da7e65](https://github.com/MilliPress/MilliRules/commit/1da7e65e97ff53a650c656a6254dac3154b57c82))
* resolve nested {request:*} and {wp:*} placeholders ([6fab125](https://github.com/MilliPress/MilliRules/commit/6fab125bdc0e0810b6b882c33d45dd54cad867e8))
### Refactoring
* drop unreachable callable guard in register_condition/register_action ([dbbf8e7](https://github.com/MilliPress/MilliRules/commit/dbbf8e7ec9d0bbc933360f9aa98293e59774eed6))
## [1.1.5](https://github.com/MilliPress/MilliRules/compare/v1.1.4...v1.1.5) (2026-05-04)
### Bug Fixes
* honor ->enabled(false) for non-WordPress rules ([ca54b36](https://github.com/MilliPress/MilliRules/commit/ca54b360aaf0e9bb876bd6648521376c76afd595))
## [1.1.4](https://github.com/MilliPress/MilliRules/compare/v1.1.3...v1.1.4) (2026-05-04)
### Bug Fixes
* execute WordPress-package rules via MilliRules::execute_rules() ([8c46c56](https://github.com/MilliPress/MilliRules/commit/8c46c5649d18f29335eea5f88cfedf8260f5bf3c))
## [1.1.3](https://github.com/MilliPress/MilliRules/compare/v1.1.2...v1.1.3) (2026-05-03)
### Bug Fixes
* defer rules referencing unloaded packages instead of misregistering as Core ([2ce0628](https://github.com/MilliPress/MilliRules/commit/2ce0628db0925689cced5ab7794aded9aaef0310))
## [1.1.2](https://github.com/MilliPress/MilliRules/compare/v1.1.1...v1.1.2) (2026-04-29)
### Bug Fixes
* prevent duplicate package registration when explicit type matches auto-detected package ([29becd4](https://github.com/MilliPress/MilliRules/commit/29becd4228818fdda9958db430e23cd24ef52076))
## [1.1.1](https://github.com/MilliPress/MilliRules/compare/v1.1.0...v1.1.1) (2026-04-24)
### Bug Fixes
* **discovery:** Find actions and conditions in Strauss-prefixed host plugins ([400ea12](https://github.com/MilliPress/MilliRules/commit/400ea120236d445b7936e9ef86c353fceae08a60))
## [1.1.0](https://github.com/MilliPress/MilliRules/compare/v1.0.0...v1.1.0) (2026-04-23)
### Features
* **actions:** Add value-level locking for paired actions via ActionMeta ([74edea9](https://github.com/MilliPress/MilliRules/commit/74edea900eba3fc89bb1864e78f756192efc66d1))
* **actions:** Allow actions to declare metadata for UI-driven rule builders ([3919f2b](https://github.com/MilliPress/MilliRules/commit/3919f2b8482574df9f358b33b04c17ffd018db8d))
* Add rule validation API and metadata discovery methods ([3ad448e](https://github.com/MilliPress/MilliRules/commit/3ad448e9bbf5911f7bf89311088370504f39ee85))
* **conditions:** Add and() connector for combining condition groups with different match types ([3f37214](https://github.com/MilliPress/MilliRules/commit/3f37214cb905e98c2d03c972a3067d5c37ad1904))
* **conditions:** Add format('pattern') to name fields that support wildcards ([c82baf3](https://github.com/MilliPress/MilliRules/commit/c82baf3b41809288bacec1d1d08fe1112939106b))
* **conditions:** Add metadata to all built-in conditions and auto-generate for WordPress conditionals ([0ec5e35](https://github.com/MilliPress/MilliRules/commit/0ec5e35702c61a055962086eae8b684602279f09))
* **conditions:** Add mode/accepts to schema, auto-infer pattern operators ([24dc931](https://github.com/MilliPress/MilliRules/commit/24dc9313fd94468d256c779260c3003ccf9455cb))
* **conditions:** Allow conditions to declare metadata for UI-driven rule builders ([8c2cf46](https://github.com/MilliPress/MilliRules/commit/8c2cf463b42c09f2353812df671c36be20ba4930))
* **conditions:** Parse condition description from WP function docblocks ([5db66d9](https://github.com/MilliPress/MilliRules/commit/5db66d9d71ac0ac0524069c0aab342376ad15bf9))
* **rules:** Add rule-level locking to prevent overwriting or unregistering safety-critical rules ([ed64a28](https://github.com/MilliPress/MilliRules/commit/ed64a28c2f85555b10709cdb9fbd8dac7c34c6a7))
* **schema:** Validate and sanitize array values via also_accepts('array') ([b60f5e6](https://github.com/MilliPress/MilliRules/commit/b60f5e63c5be718e4699ff5013beaf15febfa144))
* **wp:** Group rules by hook priority and reuse engine across priorities ([45a5180](https://github.com/MilliPress/MilliRules/commit/45a518044b7185a314c216bb17502f3a57bcd5b2))
### Bug Fixes
* **actions:** Support named argument keys from data-stored rules ([5b3ac7c](https://github.com/MilliPress/MilliRules/commit/5b3ac7c9dfc71b0b59d6b2fbdf31b156a151b4df))
* **conditions:** Rename fn_args to args and trim trailing empty strings ([d40a3c7](https://github.com/MilliPress/MilliRules/commit/d40a3c7ff200d45a96065b86ea68e39752103965))
* Correct [@since](https://github.com/since) version tags from 1.2.0 to 1.1.0 ([e84498b](https://github.com/MilliPress/MilliRules/commit/e84498bd87abe434e37a6a65286ea86776625797))
* **discovery:** Exclude handler base classes from condition catalog ([29186a8](https://github.com/MilliPress/MilliRules/commit/29186a815cf9f03e841610abfb6e8e8968669760))
* **engine:** Resolve scoped lock keys from named action arguments ([50ef450](https://github.com/MilliPress/MilliRules/commit/50ef450ffb267d74a9d74b5c5a38d2b2c09a9c89))
* **packages:** Deduplicate rules when required packages change ([d7105d3](https://github.com/MilliPress/MilliRules/commit/d7105d3842801759b914ef6b6842bd672fc1c556))
### Refactoring
* **conditions:** Remove boolean mode from Is/Has conditionals ([c3cffa6](https://github.com/MilliPress/MilliRules/commit/c3cffa68b695d873016f566f4ac2b54fa092fbfc))
* **conditions:** Use compare_values() for name field pattern matching ([58a9a34](https://github.com/MilliPress/MilliRules/commit/58a9a3477151afc7da68756c97821c89eb8f59e8))
## [1.0.0](https://github.com/MilliPress/MilliRules/compare/v0.7.3...v1.0.0) (2026-03-31)
### ⚠ BREAKING CHANGES
**conditions:** The following dedicated condition classes have been removed in favor of the generic `is_*` and `has_*` conditional bridges:
- `category` → use `is_category()` instead
- `tag` → use `is_tag()` instead
- `author` → use `is_author()` instead
- `taxonomy` → use `is_tax()` instead
- `term` → use `has_term()` instead
- `template` → use `is_page_template()` instead
- `post` → use `is_single()` or `is_page()` instead
### Features
* **conditions:** Remove redundant WordPress conditions covered by is_*/has_* ([bd7eed0](https://github.com/MilliPress/MilliRules/commit/bd7eed041ab140d17ca5bd3b0ec9972f4e65f909))
## [0.7.3](https://github.com/MilliPress/MilliRules/compare/v0.7.2...v0.7.3) (2026-02-15)
### Bug Fixes
* **rules:** Always include package for set explicit type ([b2c0d23](https://github.com/MilliPress/MilliRules/commit/b2c0d233782bba937c34beffc2dbb96b167d974c))
## [0.7.2](https://github.com/MilliPress/MilliRules/compare/v0.7.1...v0.7.2) (2026-02-11)
### Bug Fixes
* **conditions:** Return wildcard type identifiers for generic WP conditionals ([0a3b0eb](https://github.com/MilliPress/MilliRules/commit/0a3b0eb4ad131e5d77b7e66ae1b5b22ef12f87fc))
## [0.7.1](https://github.com/MilliPress/MilliRules/compare/v0.7.0...v0.7.1) (2026-02-11)
### Features
* Add public getters for registered namespaces and custom types ([6d1b517](https://github.com/MilliPress/MilliRules/commit/6d1b5175a1c671ff3a03b3f25e3c786797c2eac4))
### Bug Fixes
* **ci:** Drop PHP 8.1 from CI matrix ([ab0ab6e](https://github.com/MilliPress/MilliRules/commit/ab0ab6ec06951a028a79627992a12cad3f6f8335))
* **ci:** Loosen Pest constraint to ^2.0 for PHP 8.1 compatibility ([124d4db](https://github.com/MilliPress/MilliRules/commit/124d4dbaac1030f12cb1b8578e2188753cd2c281))
* **docs:** Correct indentation in README example for better readability ([38b09b8](https://github.com/MilliPress/MilliRules/commit/38b09b8691d864a51054e3712b71d1098909de98))
## [0.7.0](https://github.com/MilliPress/MilliRules/compare/v0.6.2...v0.7.0) (2026-02-11)
### Features
* **builders:** Add method normalization for camelCase and snake_case compatibility ([fad8f3d](https://github.com/MilliPress/MilliRules/commit/fad8f3d7ebc7cee997becb882d8f0bc1c51ec9d0))
## [0.6.2](https://github.com/MilliPress/MilliRules/compare/v0.6.1...v0.6.2) (2026-02-11)
### Bug Fixes
* **package-manager:** Ensure case-insensitive package name mapping ([f6cc490](https://github.com/MilliPress/MilliRules/commit/f6cc490f3e8634992f2b90dc798935b8202c732b))
## [0.6.1](https://github.com/MilliPress/MilliRules/compare/v0.6.0...v0.6.1) (2026-02-09)
### Features
* **docs:** Add changelog file for version tracking and updates ([207f41c](https://github.com/MilliPress/MilliRules/commit/207f41c660fcfc977ad7412891f5226e320ad94d))
* **docs:** Revise package description to highlight features and improve clarity ([9612260](https://github.com/MilliPress/MilliRules/commit/961226066e4aa109e700816fa83ba5a1ee6d0c80))
* **package-manager:** Add method to retrieve all rules with package names ([db1f732](https://github.com/MilliPress/MilliRules/commit/db1f7322e7e3312520d615028bad9607b423d915))
### Documentation
* Replace ASCII diagrams with mermaid flowcharts for better visualization ([5ef0ac5](https://github.com/MilliPress/MilliRules/commit/5ef0ac5d6940949391c7cac58387cae38b7a024e))
* Update internal links to use relative paths for consistency ([bd20128](https://github.com/MilliPress/MilliRules/commit/bd201286ed3590bbad7a6137e0c56b8903e1a9ff))
## [0.6.0](https://github.com/MilliPress/MilliRules/compare/v0.5.0...v0.6.0) (2025-12-17)
### Features
* Add rule replacement by ID and Rules::unregister() method ([05c9a73](https://github.com/MilliPress/MilliRules/commit/05c9a73c5237dc7b2bfd02192663d070776e4502))
* Add rule replacement by ID, Rules::unregister(), and Release Please ([#2](https://github.com/MilliPress/MilliRules/issues/2)) ([9e80708](https://github.com/MilliPress/MilliRules/commit/9e8070820515a4b0d97e7569b65a66d372ab7ef6))
### Bug Fixes
* Remove return type declaration from resolve_builtin_placeholder method ([efc8504](https://github.com/MilliPress/MilliRules/commit/efc850418166fc3db02746d88f0dfd89285c747a))
* Rename normalize_operator to avoid PHP 7.4 static method conflict ([5e6c3e5](https://github.com/MilliPress/MilliRules/commit/5e6c3e5f4e47561a401e1ce6edf3b9f8da83a393))
## [0.5.0](https://github.com/MilliPress/MilliRules/compare/v0.4.0...v0.5.0) (2025-12-17)
### Features
* Add WordPress has_* conditional support ([06ddde9](https://github.com/MilliPress/MilliRules/commit/06ddde9))
## [0.4.0](https://github.com/MilliPress/MilliRules/compare/v0.3.1...v0.4.0) (2025-12-03)
### Features
* Add VERSION constant to MilliRules and update release workflow ([b313037](https://github.com/MilliPress/MilliRules/commit/b313037))
* Add GitHub Actions release workflow ([cf4c7a1](https://github.com/MilliPress/MilliRules/commit/cf4c7a1))
* Add fluent argument access API to action classes ([bee5af0](https://github.com/MilliPress/MilliRules/commit/bee5af0))
### Bug Fixes
* Use PHP 8.1 in release workflow for PHPStan compatibility ([ac7f1ae](https://github.com/MilliPress/MilliRules/commit/ac7f1ae))
* Remove PHP 8.0 mixed type hint for PHP 7.4 compatibility ([0c60c92](https://github.com/MilliPress/MilliRules/commit/0c60c92))
* Remove static from normalize_operator method in IsConditional ([41a1eed](https://github.com/MilliPress/MilliRules/commit/41a1eed))
### Refactoring
* Add type declarations for private properties in ArgumentValue class ([3fc1a21](https://github.com/MilliPress/MilliRules/commit/3fc1a21))
## [0.3.1](https://github.com/MilliPress/MilliRules/compare/v0.3.0...v0.3.1) (2025-12-03)
### Refactoring
* Rename query_vars context to query and remove redundant Query context ([46c7035](https://github.com/MilliPress/MilliRules/commit/46c7035))
## [0.3.0](https://github.com/MilliPress/MilliRules/compare/v0.2.1...v0.3.0) (2025-12-02)
### Features
* Add object property access support to Context::get() ([676bff5](https://github.com/MilliPress/MilliRules/commit/676bff5))
## [0.2.1](https://github.com/MilliPress/MilliRules/compare/v0.2.0...v0.2.1) (2025-11-28)
### Bug Fixes
* Context discovery fails with Mozart and other scoping tools ([cf27cf0](https://github.com/MilliPress/MilliRules/commit/cf27cf0))
## [0.2.0](https://github.com/MilliPress/MilliRules/compare/v0.1.0...v0.2.0) (2025-11-28)
### Features
* Add intelligent logging system with rate limiting ([c4e0c22](https://github.com/MilliPress/MilliRules/commit/c4e0c22))
* Add action-level locking with ->lock() method ([0a34cd7](https://github.com/MilliPress/MilliRules/commit/0a34cd7))
* Refactor comprehensive documentation ([9380a1d](https://github.com/MilliPress/MilliRules/commit/9380a1d))
* Add `load_packages` method for package loading with dependency resolution ([cac041c](https://github.com/MilliPress/MilliRules/commit/cac041c))
### Bug Fixes
* Skip disabled rules in WordPress Package registration ([6a4414f](https://github.com/MilliPress/MilliRules/commit/6a4414f))
### Refactoring
* Rename _args to args for cleaner API ([82e6341](https://github.com/MilliPress/MilliRules/commit/82e6341))
* Change placeholder syntax from colon to dot notation for consistency ([a76c5ed](https://github.com/MilliPress/MilliRules/commit/a76c5ed))
* Rename callback parameter from $config to $args for consistency ([7bac347](https://github.com/MilliPress/MilliRules/commit/7bac347))
* Remove _args wrapper from ActionBuilder for cleaner config structure ([d989bd5](https://github.com/MilliPress/MilliRules/commit/d989bd5))
* Rename `value`/`config` to `type`/`args` in BaseAction for clarity ([195b0cd](https://github.com/MilliPress/MilliRules/commit/195b0cd))
* Pass Context objects to callback actions and conditions ([127c782](https://github.com/MilliPress/MilliRules/commit/127c782))
* Update default hook and priority in Rules and registration logic ([5cb08a4](https://github.com/MilliPress/MilliRules/commit/5cb08a4))
## [0.1.0](https://github.com/MilliPress/MilliRules/releases/tag/v0.1.0) (2025-11-17)
### Features
* Initial MilliRules implementation ([d3a7b44](https://github.com/MilliPress/MilliRules/commit/d3a7b44))
* Implement lazy context loading system ([96d9977](https://github.com/MilliPress/MilliRules/commit/96d9977))
* Add generic package-based class resolution ([2bde3e5](https://github.com/MilliPress/MilliRules/commit/2bde3e5))
* Add deferred rule registration with pending queue for unloaded packages ([6eb8ce4](https://github.com/MilliPress/MilliRules/commit/6eb8ce4))
* Auto-add WP package if 'wp' type is detected without it in required packages ([d23f10d](https://github.com/MilliPress/MilliRules/commit/d23f10d))
* Add support for accessing WordPress hook arguments in execution context ([02bc150](https://github.com/MilliPress/MilliRules/commit/02bc150))
### Bug Fixes
* Add fallback for generic `is_*` conditions in RuleEngine ([a68da5f](https://github.com/MilliPress/MilliRules/commit/a68da5f))
* Simplify conditional logic in WordPress hook registration ([494eb20](https://github.com/MilliPress/MilliRules/commit/494eb20))
* Update context key to `wp.hook` for WordPress hook arguments ([ce759cb](https://github.com/MilliPress/MilliRules/commit/ce759cb))
* Add safeguard for missing `add_action` function in WordPress hook registration ([5182ce3](https://github.com/MilliPress/MilliRules/commit/5182ce3))
* Adjust `get_rules` to return rules grouped by hook in WordPress package ([68f94b9](https://github.com/MilliPress/MilliRules/commit/68f94b9))
* Correct package name from 'WordPress' to 'WP' in required package check ([60fcb4d](https://github.com/MilliPress/MilliRules/commit/60fcb4d))
### Refactoring
* Update conditions and actions to use Context object ([7b277ee](https://github.com/MilliPress/MilliRules/commit/7b277ee))
* Update core classes to use Context object ([178bbda](https://github.com/MilliPress/MilliRules/commit/178bbda))
* Update packages to use lazy context system ([4266ff5](https://github.com/MilliPress/MilliRules/commit/4266ff5))
* Replace individual condition classes with unified implementations ([4c3240b](https://github.com/MilliPress/MilliRules/commit/4c3240b))
# Acorn MilliRules
---
Canonical: https://www.millipress.com/docs/acorn-millirules/01-getting-started/01-introduction
---
title: 'Introduction'
description: 'Acorn MilliRules adds route-aware conditions, HTTP response actions, WP-CLI commands, and rule auto-discovery to Laravel routes in Acorn on the Roots stack.'
menu_order: 10
---
# Introduction
Acorn MilliRules brings the [MilliRules Engine](https://millipress.com/docs/millirules/01-getting-started/01-introduction) into your Acorn application. It adds route-aware conditions, HTTP response actions, CLI commands, and automatic rule discovery — everything you need to define and manage rules that react to Laravel routes.
## What This Package Provides
- **Route-aware conditions** — match rules by route name, route parameters, or controller class
- **HTTP response actions** — redirect requests or set response headers
- **Route context** — automatic context loading with route metadata (name, parameters, controller, URI, middleware)
- **8 Artisan commands** — list, inspect, and scaffold rules, actions, and conditions
- **Auto-discovery** — rule classes in `app/Rules/` are registered automatically
- **Middleware integration** — rules execute after route matching with zero configuration
> [!NOTE]
> This package extends MilliRules with Acorn-specific features. For general concepts like rules, conditions, actions, operators, and the fluent builder API, see the [MilliRules documentation](https://millipress.com/docs/millirules/).
## Prerequisites
| Requirement | Version |
|---------------|------------------------------|
| PHP | >= 8.1 |
| Roots Acorn | ^4.0 or ^5.0 or ^6.0 |
| MilliRules | ^1.0 (auto-installed) |
MilliRules is declared as a Composer dependency and will be installed automatically. You do not need to install it separately.
## How It Works
The execution flow in Acorn follows these steps:
1. **Service provider boots** — `ServiceProvider` initializes MilliRules, registers the Acorn package, and discovers your rule classes
2. **Auto-discovery** — rule classes in `app/Rules/*.php` are instantiated and their `register()` method is called, which registers rules with the engine
3. **Request arrives** — Laravel routes the request to a controller as usual
4. **Middleware executes** — the `ExecuteRules` middleware runs *after* the controller, so route context (name, parameters, controller) is available
5. **Rules evaluate** — MilliRules evaluates all registered rules against the current context
6. **Response modified** — actions collect response modifications (headers, redirects) via the `ResponseCollector`, and the middleware applies them to the outgoing HTTP response
> [!TIP]
> The builder API supports both **camelCase** (`->routeName()`, `->setHeader()`) and **snake_case** (`->route_name()`, `->set_header()`) method names. This documentation uses camelCase to align with Laravel conventions, but both styles work identically.
## Next Steps
- **[Installation](/docs/acorn-millirules/01-getting-started/02-installation)** — install the package, publish config and stubs, create your first rule
- **[Creating Rules](/docs/acorn-millirules/02-usage/01-creating-rules)** — learn the rule class pattern and auto-discovery
- **[Artisan Commands](/docs/acorn-millirules/02-usage/03-artisan-commands)** — explore all 8 CLI commands
---
**Ready to get started?** Continue to the [Installation guide](/docs/acorn-millirules/01-getting-started/02-installation).
---
Canonical: https://www.millipress.com/docs/acorn-millirules/01-getting-started/02-installation
---
title: 'Installation'
description: 'Install Acorn MilliRules with Composer in your Acorn project, publish config and stubs, verify the WP-CLI commands, and build your first Laravel route rule.'
menu_order: 20
---
# Installation
## Install the Package
```bash
composer require millipress/acorn-millirules
```
The service provider is registered automatically via the `extra.acorn.providers` key in the package's `composer.json` — no manual registration needed.
## Publish Config and Stubs
Publish the configuration file and stub templates:
```bash
wp acorn vendor:publish --tag=millirules
```
This publishes:
| File | Location |
|---|---|
| Configuration | `config/millirules.php` |
| Rule stub | `stubs/millirules/rule.stub` |
| Action stub | `stubs/millirules/action.stub` |
| Condition stub | `stubs/millirules/condition.stub` |
> [!TIP]
> Publishing is optional. The package works out of the box with sensible defaults. Publish only if you need to customize the middleware configuration or scaffold templates.
## Verify the Installation
Run these commands to confirm everything is registered:
```bash
# List registered packages (should show PHP, Acorn, and optionally WP)
wp acorn rules:packages
# List available action types
wp acorn rules:actions
# List available condition types
wp acorn rules:conditions
```
You should see the Acorn package listed with its `redirect`, `set_header` actions and `route_name`, `route_parameter`, `route_controller` conditions.
## Your First Rule
Let's create a rule that adds security headers to all documentation pages.
### 1. Scaffold the Rule
```bash
wp acorn rules:make:rule SecurityHeaders
```
This creates `app/Rules/SecurityHeaders.php`:
```php
when()
// ->routeName('example.route')
// ->requestUrl('/example/*', 'LIKE')
->then()
// ->setHeader('X-Custom', 'value')
->register();
}
}
```
### 2. Fill in the Rule
Replace the placeholders with real conditions and actions:
```php
when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Content-Type-Options', 'nosniff')
->setHeader('X-Frame-Options', 'DENY')
->register();
}
}
```
This rule matches any route whose name starts with `docs.` and adds two security headers to the response.
### 3. Verify the Rule
```bash
# List all rules — you should see security-headers
wp acorn rules:list
# Show details for this specific rule
wp acorn rules:show security-headers
```
The `rules:show` command displays the rule's conditions, actions, and metadata:
```
Rule ID ................................... security-headers
Package ............................................. Acorn
Order .................................................. 10
Enabled ............................................... Yes
Match Type ............................................ all
Conditions (1)
route_name LIKE docs.*
Actions (2)
set_header {"name":"X-Content-Type-Options","value":"nosniff"}
set_header {"name":"X-Frame-Options","value":"DENY"}
```
> [!IMPORTANT]
> Rules are auto-discovered from `app/Rules/*.php`. There is no registration step beyond creating the file — the service provider finds and calls `register()` automatically.
## Next Steps
- **[Creating Rules](/docs/acorn-millirules/02-usage/01-creating-rules)** — learn the full rule class pattern, ordering, and multiple rules per class
- **[Conditions and Actions](/docs/acorn-millirules/02-usage/02-conditions-and-actions)** — explore all built-in Acorn conditions and actions
- **[Configuration](/docs/acorn-millirules/03-customization/02-configuration)** — customize middleware groups and stubs
---
Canonical: https://www.millipress.com/docs/acorn-millirules/02-usage/01-creating-rules
---
title: 'Creating Rules'
description: 'Write rule classes for Acorn MilliRules: scaffold with rules:make, auto-discovery from app/Rules, rule ordering, and multiple rules per class in Acorn.'
menu_order: 30
---
# Creating Rules
Rules in MilliRules are PHP classes with a `register()` method that uses the MilliRules fluent builder API to define conditions and actions.
## Rule Class Anatomy
A rule class lives in the `App\Rules` namespace and has a single `register()` method:
```php
when()
->routeName('docs.legacy')
->then()
->redirect('/docs/{route.parameters.product}', 301)
->register();
}
}
```
Key points:
- **Namespace**: `App\Rules` — auto-discovered by the service provider
- **No base class**: rule classes are plain PHP classes (no interface or abstract class required)
- **`register()` method**: called automatically during service provider boot
- **`Rules::create($id)`**: starts the fluent builder with a unique rule ID
- **`->register()`**: finalizes and registers the rule with the engine
> [!IMPORTANT]
> Each rule ID must be unique across all packages. Use descriptive IDs like `docs-security-headers` or `api-rate-limit-redirect`.
## Scaffolding
Use the `rules:make:rule` command to generate a new rule class:
```bash
wp acorn rules:make:rule DocsRedirects
```
Output:
```
Rule created successfully.
⇂ Rule ID: docs-redirects
⇂ Package: Acorn
⇂ Auto-discovered on next request
```
The rule ID is automatically derived from the class name using kebab-case conversion (`DocsRedirects` → `docs-redirects`).
### Options
| Option | Description |
|---|---|
| `--package=Acorn` | Target package name (default: `Acorn`) |
| `--force` | Overwrite the file if it already exists |
```bash
# Overwrite an existing rule
wp acorn rules:make:rule DocsRedirects --force
```
> [!TIP]
> `rules:make` is an alias for `rules:make:rule`. Both commands are identical.
## Multiple Rules in One Class
A single class can register multiple rules:
```php
when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Content-Type-Options', 'nosniff')
->setHeader('X-Frame-Options', 'DENY')
->register();
Rules::create('docs-cache-headers')
->when()
->routeName('docs.show')
->then()
->setHeader('Cache-Control', 'public, max-age=3600')
->register();
}
}
```
Each `Rules::create()` / `->register()` pair defines an independent rule with its own ID, conditions, and actions.
## Rule Ordering
Rules execute in order determined by their `order` value (default: `10`). Lower values execute first:
```php
Rules::create('early-rule')
->order(5)
->when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Processed-By', 'MilliRules')
->register();
Rules::create('late-rule')
->order(20)
->when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Cache', 'HIT')
->register();
```
## Disabling Rules
Temporarily disable a rule without removing it:
```php
Rules::create('maintenance-redirect')
->enabled(false)
->when()
->routeName('docs.*', 'LIKE')
->then()
->redirect('/maintenance')
->register();
```
Disabled rules appear in `rules:list` with **Enabled = No** but are skipped during execution.
## Next Steps
- **[Conditions and Actions](/docs/acorn-millirules/02-usage/02-conditions-and-actions)** — explore the built-in Acorn conditions and actions with examples
- **[Custom Conditions and Actions](/docs/acorn-millirules/03-customization/01-custom-conditions-and-actions)** — create your own condition and action types
- For details on the fluent builder API (`Rules::create()`, `->when()`, `->then()`, operators), see the [MilliRules Building Rules documentation](https://millipress.com/docs/millirules/02-core-concepts/03-building-rules)
---
Canonical: https://www.millipress.com/docs/acorn-millirules/02-usage/02-conditions-and-actions
---
title: 'Conditions and Actions'
description: 'Built-in Acorn MilliRules conditions and actions: match Laravel route names, parameters, and controllers, then set response headers or redirect requests.'
menu_order: 40
---
# Conditions and Actions
Acorn MilliRules ships with three route-aware conditions and two HTTP response actions. These are registered automatically by the Acorn package and available in the fluent builder immediately.
## Conditions
### Route Name
Match the current Laravel route name. Useful for targeting named routes like `docs.show` or groups like `docs.*`.
```php
Rules::create('docs-headers')
->when()
->routeName('docs.show')
->then()
->setHeader('X-Docs', 'true')
->register();
```
Pattern matching with the `LIKE` operator:
```php
Rules::create('all-docs-headers')
->when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Section', 'docs')
->register();
```
For a complete list of operators and examples, see the [Route Name reference](/docs/acorn-millirules/04-reference/01-conditions#route-name).
### Route Parameter
Check the value of a named route parameter. The first argument is the parameter name, the second is the expected value.
```php
Rules::create('millicache-product-header')
->when()
->routeParameter('product', 'millicache')
->then()
->setHeader('X-Product', 'millicache')
->register();
```
When only a parameter name is provided (no value), the condition checks if the parameter **exists**:
```php
Rules::create('has-product-parameter')
->when()
->routeParameter('product')
->then()
->setHeader('X-Has-Product', 'true')
->register();
```
For existence checks, pattern matching, and all operators, see the [Route Parameter reference](/docs/acorn-millirules/04-reference/01-conditions#route-parameter).
### Route Controller
Match the fully-qualified controller class name handling the current route.
```php
Rules::create('docs-controller-headers')
->when()
->routeController('App\Http\Controllers\DocsController')
->then()
->setHeader('X-Handler', 'docs')
->register();
```
Partial matching with `LIKE`:
```php
Rules::create('any-docs-controller')
->when()
->routeController('*DocsController', 'LIKE')
->then()
->setHeader('X-Handler', 'docs')
->register();
```
For all operators and examples, see the [Route Controller reference](/docs/acorn-millirules/04-reference/01-conditions#route-controller).
## Actions
### Set Header
Add an HTTP response header. The first argument is the header name, the second is the value.
```php
Rules::create('security-headers')
->when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Content-Type-Options', 'nosniff')
->setHeader('X-Frame-Options', 'DENY')
->setHeader('Referrer-Policy', 'strict-origin-when-cross-origin')
->register();
```
Headers support placeholders that resolve from context:
```php
Rules::create('product-header')
->when()
->routeParameter('product')
->then()
->setHeader('X-Product', '{route.parameters.product}')
->register();
```
For full details on placeholder support and behavior, see the [Set Header reference](/docs/acorn-millirules/04-reference/02-actions#set-header).
### Redirect
Redirect the request to a different URL. The first argument is the target URL, the second (optional) is the HTTP status code (default: `302`).
```php
Rules::create('legacy-docs-redirect')
->when()
->routeName('docs.legacy')
->then()
->redirect('/docs', 301)
->register();
```
Redirects support placeholders for dynamic URLs:
```php
Rules::create('product-redirect')
->when()
->routeName('docs.old-product')
->then()
->redirect('/docs/{route.parameters.product}/latest', 301)
->register();
```
For full details on redirect behavior and examples, see the [Redirect reference](/docs/acorn-millirules/04-reference/02-actions#redirect).
## Combining Acorn and Core Conditions
You can mix Acorn route conditions with conditions from other MilliRules packages (like the PHP package's `request_url` or `cookie` conditions) in the same rule:
```php
Rules::create('docs-logged-in-redirect')
->when()
->routeName('docs.premium')
->cookie('session_token', '', '!=')
->then()
->setHeader('X-Access', 'premium')
->register();
```
By default, all conditions must match (`match_type: all`). To match when **any** condition is true, use `matchAny()`:
```php
Rules::create('product-pages')
->matchAny()
->when()
->routeName('products.show')
->routeParameter('product', 'millicache')
->then()
->setHeader('X-Product-Page', 'true')
->register();
```
> [!NOTE]
> For the full list of conditions and actions available from other packages (like `request_url`, `cookie`, `request_method`), see the [MilliRules Conditions Reference](https://millipress.com/docs/millirules/05-reference/01-conditions) and [Actions Reference](https://millipress.com/docs/millirules/05-reference/02-actions).
## Next Steps
- **[Artisan Commands](/docs/acorn-millirules/02-usage/03-artisan-commands)** — list, inspect, and scaffold rules from the CLI
- **[Custom Conditions and Actions](/docs/acorn-millirules/03-customization/01-custom-conditions-and-actions)** — create your own condition and action types
- **[Conditions Reference](/docs/acorn-millirules/04-reference/01-conditions)** — full reference for all Acorn conditions
- **[Actions Reference](/docs/acorn-millirules/04-reference/02-actions)** — full reference for all Acorn actions
---
Canonical: https://www.millipress.com/docs/acorn-millirules/02-usage/03-artisan-commands
---
title: 'Artisan Commands'
description: 'Reference for all eight Acorn MilliRules WP-CLI commands: list, inspect, and scaffold rules, conditions, and actions with wp acorn rules commands.'
menu_order: 50
---
# Artisan Commands
Acorn MilliRules provides Artisan commands for managing rules from the CLI. All commands use the `rules:` prefix.
## Listing Commands
### `rules:list`
List all registered rules across loaded packages.
```bash
wp acorn rules:list
```
```
+--------------------+---------+-------+---------+-------+------------+---------+
| ID | Package | Order | Enabled | Match | Conditions | Actions |
+--------------------+---------+-------+---------+-------+------------+---------+
| security-headers | Acorn | 10 | Yes | all | 1 | 2 |
| docs-redirect | Acorn | 10 | Yes | all | 1 | 1 |
+--------------------+---------+-------+---------+-------+------------+---------+
```
#### Options
| Option | Description |
|---|---|
| `--package=` | Filter by package name (e.g., `--package=Acorn`) |
| `--id=` | Filter by rule ID substring (e.g., `--id=docs`) |
```bash
# Only Acorn rules
wp acorn rules:list --package=Acorn
# Rules containing "docs" in the ID
wp acorn rules:list --id=docs
```
### `rules:show`
Show detailed information about a specific rule.
```bash
wp acorn rules:show security-headers
```
```
Rule ID ................................... security-headers
Package ............................................. Acorn
Order .................................................. 10
Enabled ............................................... Yes
Match Type ............................................ all
Conditions (1)
route_name LIKE docs.*
Actions (2)
set_header {"name":"X-Content-Type-Options","value":"nosniff"}
set_header {"name":"X-Frame-Options","value":"DENY"}
```
#### Arguments
| Argument | Description |
|---|---|
| `id` | The rule ID to display (required) |
### `rules:packages`
List all registered MilliRules packages with their availability and rule counts.
```bash
wp acorn rules:packages
```
```
+-------+-----------+--------+--------------+-------+
| Name | Available | Loaded | Dependencies | Rules |
+-------+-----------+--------+--------------+-------+
| PHP | Yes | Yes | - | 0 |
| Acorn | Yes | Yes | PHP | 2 |
+-------+-----------+--------+--------------+-------+
```
### `rules:actions`
List all registered action types across loaded packages.
```bash
wp acorn rules:actions
```
```
+------------+------------------+---------+------------------------------------------------------+
| Type | Builder | Package | Class |
+------------+------------------+---------+------------------------------------------------------+
| redirect | ->redirect() | Acorn | MilliRules\Acorn\...\Actions\Redirect |
| set_header | ->setHeader() | Acorn | MilliRules\Acorn\...\Actions\SetHeader |
+------------+------------------+---------+------------------------------------------------------+
```
#### Options
| Option | Description |
|---|---|
| `--package=` | Filter by package name |
```bash
wp acorn rules:actions --package=Acorn
```
### `rules:conditions`
List all registered condition types across loaded packages.
```bash
wp acorn rules:conditions
```
```
+------------------+----------------------+---------+------------------------------------------------------+
| Type | Builder | Package | Class |
+------------------+----------------------+---------+------------------------------------------------------+
| route_name | ->routeName() | Acorn | MilliRules\Acorn\...\Conditions\RouteName |
| route_parameter | ->routeParameter() | Acorn | MilliRules\Acorn\...\Conditions\Route... |
| route_controller | ->routeController() | Acorn | MilliRules\Acorn\...\Conditions\Route... |
+------------------+----------------------+---------+------------------------------------------------------+
```
#### Options
| Option | Description |
|---|---|
| `--package=` | Filter by package name |
```bash
wp acorn rules:conditions --package=Acorn
```
## Scaffolding Commands
### `rules:make:rule`
Scaffold a new rule class in `app/Rules/`.
```bash
wp acorn rules:make:rule SecurityHeaders
```
```
Rule created successfully.
⇂ Rule ID: security-headers
⇂ Package: Acorn
⇂ Auto-discovered on next request
```
The class name is converted to a kebab-case rule ID: `SecurityHeaders` → `security-headers`.
#### Arguments and Options
| Argument / Option | Description |
|---|---|
| `name` | The rule class name (e.g., `SecurityHeaders`) |
| `--package=Acorn` | Target package name (default: `Acorn`) |
| `--force` | Overwrite the file if it already exists |
> [!TIP]
> `rules:make` is an alias for `rules:make:rule`.
### `rules:make:action`
Scaffold a new action class in `app/Rules/Actions/`.
```bash
wp acorn rules:make:action CorsHeaders
```
```
Action created successfully.
⇂ Action type: cors_headers
⇂ Builder: ->corsHeaders(...)
⇂ Auto-discovered via App\Rules\Actions namespace
```
The class name determines the action type (`CorsHeaders` → `cors_headers`) and builder method (`->corsHeaders()`).
#### Arguments and Options
| Argument / Option | Description |
|---|---|
| `name` | The action class name (e.g., `CorsHeaders`) |
| `--force` | Overwrite the file if it already exists |
### `rules:make:condition`
Scaffold a new condition class in `app/Rules/Conditions/`.
```bash
wp acorn rules:make:condition IsAdmin
```
```
Condition created successfully.
⇂ Condition type: is_admin
⇂ Builder: ->isAdmin(...)
⇂ Auto-discovered via App\Rules\Conditions namespace
```
The class name determines the condition type (`IsAdmin` → `is_admin`) and builder method (`->isAdmin()`).
#### Arguments and Options
| Argument / Option | Description |
|---|---|
| `name` | The condition class name (e.g., `IsAdmin`) |
| `--force` | Overwrite the file if it already exists |
## Customizing Stubs
All scaffolding commands use stub templates that you can customize after publishing:
```bash
wp acorn vendor:publish --tag=millirules
```
This copies the stubs to `stubs/millirules/` in your project root:
| Stub | Used by |
|---|---|
| `stubs/millirules/rule.stub` | `rules:make:rule` |
| `stubs/millirules/action.stub` | `rules:make:action` |
| `stubs/millirules/condition.stub` | `rules:make:condition` |
Published stubs take priority over the package defaults. Edit them to match your project's coding style or add boilerplate code.
## Next Steps
- **[Custom Conditions and Actions](/docs/acorn-millirules/03-customization/01-custom-conditions-and-actions)** — create your own types using the scaffolding commands
- **[Configuration](/docs/acorn-millirules/03-customization/02-configuration)** — customize middleware and published stubs
---
Canonical: https://www.millipress.com/docs/acorn-millirules/03-customization/01-custom-conditions-and-actions
---
title: 'Custom Conditions and Actions'
description: 'Create custom conditions and actions for Acorn MilliRules: scaffold your own types, use the ResponseCollector API, and read Laravel route context.'
menu_order: 60
---
# Custom Conditions and Actions
Beyond the built-in types, you can create your own conditions and actions that are auto-discovered and available in the fluent builder.
## Custom Conditions
### 1. Scaffold the Condition
```bash
wp acorn rules:make:condition IsAdmin
```
This creates `app/Rules/Conditions/IsAdmin.php`:
```php
get('route.name'), $context->get('route.parameters.slug'), etc.
return '';
}
}
```
### 2. Implement the Logic
Fill in `get_actual_value()` to return the value that should be compared against the condition's expected value:
```php
user();
return $user && $user->is_admin ? 'true' : 'false';
}
}
```
> [!NOTE]
> `get_actual_value()` should return a string (or scalar). The `BaseCondition` parent class handles all operator logic (`=`, `!=`, `LIKE`, `REGEXP`, `IN`) automatically.
### 3. Use in a Rule
The condition is auto-discovered and immediately available as `->isAdmin()` in the builder:
```php
Rules::create('admin-debug-headers')
->when()
->isAdmin('true')
->then()
->setHeader('X-Debug', 'enabled')
->register();
```
### 4. Verify
```bash
# Confirm the condition is registered
wp acorn rules:conditions --package=Acorn
# Confirm the rule uses it
wp acorn rules:show admin-debug-headers
```
## Custom Actions
### 1. Scaffold the Action
```bash
wp acorn rules:make:action CorsHeaders
```
This creates `app/Rules/Actions/CorsHeaders.php`:
```php
get_arg(0, 'default')->string();
//
// Modify the HTTP response:
// app('millirules.response')->addHeader('X-Custom', $value);
// app('millirules.response')->setRedirect('/path', 302);
}
}
```
### 2. Implement the Logic
Use `$this->get_arg()` to read arguments from the builder and `app('millirules.response')` to modify the HTTP response:
```php
get_arg(0, '*')->string();
$collector = app('millirules.response');
$collector->addHeader('Access-Control-Allow-Origin', $origin);
$collector->addHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
$collector->addHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
}
}
```
### 3. Use in a Rule
The action is auto-discovered and available as `->corsHeaders()` in the builder:
```php
Rules::create('api-cors')
->when()
->routeName('api.*', 'LIKE')
->then()
->corsHeaders('https://example.com')
->register();
```
### 4. Verify
```bash
# Confirm the action is registered
wp acorn rules:actions --package=Acorn
# Confirm the rule uses it
wp acorn rules:show api-cors
```
## ResponseCollector API
Custom actions modify the HTTP response through the `ResponseCollector` singleton, accessed via `app('millirules.response')`. The middleware reads the collector after rule execution and applies changes to the outgoing response.
### Available Methods
| Method | Description |
|---|---|
| `addHeader(string $name, string $value)` | Queue a header to be set on the response. If the same header name is added multiple times, the last value wins. |
| `setRedirect(string $url, int $status = 302)` | Queue a redirect response. Replaces the original response entirely. If multiple redirects are queued, the last one wins. |
```php
$collector = app('millirules.response');
// Add a header
$collector->addHeader('X-Custom', 'value');
// Queue a redirect (replaces the response)
$collector->setRedirect('/new-location', 301);
```
> [!WARNING]
> A redirect replaces the entire original response. Headers are still applied to the redirect response, but the original response body is discarded.
## Using Route Context in Custom Types
Custom conditions and actions can access the route context by loading it from the `Context` object:
```php
protected function get_actual_value(Context $context): string
{
// Load route context (lazy-loaded on first call)
$context->load('route');
// Access individual keys
$routeName = $context->get('route.name', '');
$productParam = $context->get('route.parameters.product', '');
$controller = $context->get('route.controller', '');
return is_string($routeName) ? $routeName : '';
}
```
The `$context->load('route')` call is idempotent — it loads route data once and subsequent calls are no-ops. See the [Route Context reference](/docs/acorn-millirules/04-reference/03-route-context) for all available context keys.
## Next Steps
- **[Configuration](/docs/acorn-millirules/03-customization/02-configuration)** — customize middleware groups and stubs
- **[Route Context Reference](/docs/acorn-millirules/04-reference/03-route-context)** — all available context keys, types, and examples
- For advanced patterns like custom operators and context providers, see the [MilliRules Custom Conditions](https://millipress.com/docs/millirules/03-customization/01-custom-conditions) and [Custom Actions](https://millipress.com/docs/millirules/03-customization/02-custom-actions) documentation
---
Canonical: https://www.millipress.com/docs/acorn-millirules/03-customization/02-configuration
---
title: 'Configuration'
description: 'Acorn MilliRules configuration reference: middleware groups, manual ExecuteRules registration on Laravel routes, and customizing scaffolding stubs.'
menu_order: 70
---
# Configuration
The configuration file controls how the MilliRules middleware is registered. Publish it with:
```bash
wp acorn vendor:publish --tag=millirules
```
This creates `config/millirules.php` in your application.
## Full Config Reference
```php
[
// Set to false to disable automatic middleware registration.
'enabled' => true,
// Middleware groups to attach to (e.g. ['web', 'api']).
'groups' => ['web'],
],
];
```
### Options
| Key | Type | Default | Description |
|---|---|---|---|
| `middleware.enabled` | `bool` | `true` | Enable or disable automatic middleware registration. Set to `false` to register the middleware manually. |
| `middleware.groups` | `string[]` | `['web']` | Middleware groups the `ExecuteRules` middleware is pushed to. Rules will only execute on routes belonging to these groups. |
## Adding Middleware Groups
To execute rules on API routes as well:
```php
'middleware' => [
'enabled' => true,
'groups' => ['web', 'api'],
],
```
## Disabling Automatic Middleware
Set `middleware.enabled` to `false` to take full control over where the middleware runs:
```php
'middleware' => [
'enabled' => false,
'groups' => [],
],
```
Then register the middleware manually on specific routes or groups:
```php
use MilliRules\Acorn\Http\Middleware\ExecuteRules;
// On a specific route
Route::get('/docs/{product}', [DocsController::class, 'show'])
->middleware(ExecuteRules::class);
// On a route group
Route::middleware([ExecuteRules::class])->group(function () {
Route::get('/docs/{product}', [DocsController::class, 'show']);
Route::get('/docs/{product}/{path}', [DocsController::class, 'page']);
});
```
> [!TIP]
> Manual registration is useful when you only want rules to execute on a subset of routes, avoiding the overhead of rule evaluation on routes that never match any conditions.
## Customizing Stubs
After publishing, you can customize the stub templates used by the scaffolding commands. Published stubs are located at:
| Stub | Path |
|---|---|
| Rule | `stubs/millirules/rule.stub` |
| Action | `stubs/millirules/action.stub` |
| Condition | `stubs/millirules/condition.stub` |
Published stubs take priority over the package defaults. The scaffolding commands check for a published stub first and fall back to the package stub if none is found.
### Available Placeholders
| Placeholder | Replaced with |
|---|---|
| `{{ namespace }}` | The generated class namespace (e.g., `App\Rules`) |
| `{{ class }}` | The generated class name (e.g., `SecurityHeaders`) |
| `{{ ruleId }}` | Kebab-case rule ID, rule stubs only (e.g., `security-headers`) |
| `{{ type }}` | Snake_case type name, action and condition stubs only (e.g., `cors_headers`) |
### Example: Customized Rule Stub
```php
order(10)
->when()
// Add conditions here
->then()
// Add actions here
->register();
}
}
```
## Next Steps
- **[Conditions Reference](/docs/acorn-millirules/04-reference/01-conditions)** — full reference for all Acorn conditions
- **[Actions Reference](/docs/acorn-millirules/04-reference/02-actions)** — full reference for all Acorn actions
- **[Route Context Reference](/docs/acorn-millirules/04-reference/03-route-context)** — all available route context keys
---
Canonical: https://www.millipress.com/docs/acorn-millirules/04-reference/01-conditions
---
title: 'Conditions Reference'
description: 'Complete reference for Acorn MilliRules route conditions: route_name, route_parameter, and route_controller with all operators and builder syntax.'
menu_order: 80
---
# Conditions Reference
This is the complete reference for all conditions provided by the Acorn package. Each condition checks a value from the [route context](/docs/acorn-millirules/04-reference/03-route-context).
## Route Name
Match the current Laravel route name.
| Property | Value |
|-----------------|------------------------------------------------------------------|
| **Type** | `route_name` |
| **Class** | `MilliRules\Acorn\Packages\Acorn\Conditions\RouteName` |
| **Context key** | `route.name` |
| **Operators** | `=`, `!=`, `LIKE`, `REGEXP`, `IN` |
### Builder Syntax
```php
->routeName(string $value, string $operator = '=')
```
### Examples
Exact match:
```php
Rules::create('docs-show-header')
->when()
->routeName('docs.show')
->then()
->setHeader('X-Page', 'docs-show')
->register();
```
Pattern match with `LIKE` (uses `*` as wildcard):
```php
Rules::create('all-docs-header')
->when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Section', 'docs')
->register();
```
Regular expression:
```php
Rules::create('docs-or-api-header')
->when()
->routeName('^(docs|api)\.', 'REGEXP')
->then()
->setHeader('X-App-Section', 'content')
->register();
```
Match one of several values with `IN`:
```php
Rules::create('special-pages-header')
->when()
->routeName(['docs.show', 'docs.index', 'blog.show'], 'IN')
->then()
->setHeader('X-Content', 'true')
->register();
```
### Array Syntax
```php
['type' => 'route_name', 'value' => 'docs.show']
['type' => 'route_name', 'value' => 'docs.*', 'operator' => 'LIKE']
```
---
## Route Parameter
Check the value of a named route parameter. This is a **name-based condition**: the first argument is the parameter name, the second is the expected value.
| Property | Value |
|----------------------|-----------------------------------------------------------------------|
| **Type** | `route_parameter` |
| **Class** | `MilliRules\Acorn\Packages\Acorn\Conditions\RouteParameter` |
| **Context key** | `route.parameters.{name}` |
| **Argument mapping** | `['name', 'value']` |
| **Operators** | `=`, `!=`, `LIKE`, `REGEXP`, `IN`, `EXISTS`, `NOT EXISTS` |
### Builder Syntax
```php
// Existence check (parameter exists and is not empty)
->routeParameter(string $name)
// Value check
->routeParameter(string $name, string $value, string $operator = '=')
```
### Existence Check
When only a parameter name is provided, the condition checks whether the parameter **exists** (is present and non-empty):
```php
Rules::create('has-product-param')
->when()
->routeParameter('product')
->then()
->setHeader('X-Has-Product', 'true')
->register();
```
Explicitly check that a parameter does **not** exist:
```php
Rules::create('no-product-param')
->when()
->routeParameter('product', '', 'NOT EXISTS')
->then()
->redirect('/products')
->register();
```
> [!NOTE]
> The existence check works by evaluating whether the parameter's value is a non-empty string. When no value argument is given, the default operator (`=`) behaves like `EXISTS` — it checks `actual !== ''`.
### Value Check
Compare the parameter value against an expected value:
```php
Rules::create('millicache-product')
->when()
->routeParameter('product', 'millicache')
->then()
->setHeader('X-Product', 'millicache')
->register();
```
Pattern match:
```php
Rules::create('milli-products')
->when()
->routeParameter('product', 'milli*', 'LIKE')
->then()
->setHeader('X-Product-Family', 'milli')
->register();
```
Regular expression:
```php
Rules::create('versioned-paths')
->when()
->routeParameter('path', '^v[0-9]+/', 'REGEXP')
->then()
->setHeader('X-Versioned', 'true')
->register();
```
### Array Syntax
```php
// Existence check
['type' => 'route_parameter', 'name' => 'product']
// Value check
['type' => 'route_parameter', 'name' => 'product', 'value' => 'millicache']
// Pattern match
['type' => 'route_parameter', 'name' => 'product', 'value' => 'milli*', 'operator' => 'LIKE']
```
---
## Route Controller
Match the fully qualified class name of the controller handling the current route.
| Property | Value |
|-----------------|------------------------------------------------------------------------|
| **Type** | `route_controller` |
| **Class** | `MilliRules\Acorn\Packages\Acorn\Conditions\RouteController` |
| **Context key** | `route.controller` |
| **Operators** | `=`, `!=`, `LIKE`, `REGEXP`, `IN` |
### Builder Syntax
```php
->routeController(string $value, string $operator = '=')
```
### Examples
Exact match with the full class name:
```php
Rules::create('docs-controller-header')
->when()
->routeController('App\Http\Controllers\DocsController')
->then()
->setHeader('X-Handler', 'docs')
->register();
```
Partial match with `LIKE`:
```php
Rules::create('any-api-controller')
->when()
->routeController('*Api*Controller', 'LIKE')
->then()
->setHeader('X-API', 'true')
->register();
```
Match one of several controllers with `IN`:
```php
Rules::create('content-controllers')
->when()
->routeController([
'App\Http\Controllers\DocsController',
'App\Http\Controllers\BlogController',
], 'IN')
->then()
->setHeader('X-Content', 'true')
->register();
```
### Array Syntax
```php
['type' => 'route_controller', 'value' => 'App\Http\Controllers\DocsController']
['type' => 'route_controller', 'value' => '*DocsController', 'operator' => 'LIKE']
```
> [!TIP]
> The controller value is the fully qualified class name as registered in the route (e.g., `App\Http\Controllers\DocsController`). For invokable controllers, the class name is returned without a method suffix.
---
Canonical: https://www.millipress.com/docs/acorn-millirules/04-reference/02-actions
---
title: 'Actions Reference'
description: 'Complete reference for Acorn MilliRules actions: redirect and set_header, with builder syntax, placeholder support, behavior notes, and examples.'
menu_order: 90
---
# Actions Reference
This is the complete reference for all actions provided by the Acorn package. Actions modify the outgoing HTTP response through the [ResponseCollector](/docs/acorn-millirules/03-customization/01-custom-conditions-and-actions#responsecollector-api).
## Redirect
Redirect the request to a different URL.
| Property | Value |
|-------------------------|--------------------------------------------------------------|
| **Type** | `redirect` |
| **Class** | `MilliRules\Acorn\Packages\Acorn\Actions\Redirect` |
| **Arguments** | `url` (string), `status` (int, default: `302`) |
| **Placeholder support** | Yes — `{route.parameters.*}`, `{route.name}`, etc. |
### Builder Syntax
```php
->redirect(string $url, int $status = 302)
```
### Behavior
- A redirect **replaces the entire original response**. The controller's response body is discarded.
- If multiple `redirect` actions fire, **the last one wins** — each call to `setRedirect()` overwrites the previous.
- Headers set by `setHeader` actions are applied to the redirect response as well.
- The redirect uses `Illuminate\Http\RedirectResponse` internally.
### Examples
Simple redirect with a permanent status:
```php
Rules::create('legacy-docs-redirect')
->when()
->routeName('docs.legacy')
->then()
->redirect('/docs', 301)
->register();
```
Temporary redirect (default 302):
```php
Rules::create('maintenance-redirect')
->when()
->routeName('docs.maintenance')
->then()
->redirect('/maintenance')
->register();
```
Dynamic redirect using placeholders:
```php
Rules::create('product-redirect')
->when()
->routeName('docs.old-product')
->then()
->redirect('/docs/{route.parameters.product}/latest', 301)
->register();
```
> [!WARNING]
> An empty URL (empty string) is silently ignored — no redirect occurs. Always ensure the URL argument resolves to a non-empty value.
### Array Syntax
```php
['type' => 'redirect', 'url' => '/docs', 'status' => 301]
['type' => 'redirect', 'url' => '/docs/{route.parameters.product}']
```
---
## Set Header
Add an HTTP response header.
| Property | Value |
|-------------------------|---------------------------------------------------------------|
| **Type** | `set_header` |
| **Class** | `MilliRules\Acorn\Packages\Acorn\Actions\SetHeader` |
| **Arguments** | `name` (string), `value` (string) |
| **Placeholder support** | Yes — `{route.parameters.*}`, `{route.name}`, etc. |
### Builder Syntax
```php
->setHeader(string $name, string $value)
```
### Behavior
- Headers are **additive** — multiple `setHeader` calls with different header names all apply.
- For the **same header name**, the last value wins — `addHeader()` overwrites previous values for a given key.
- Headers are applied to both normal responses and redirect responses.
- An empty header name is silently ignored.
### Examples
Single header:
```php
Rules::create('nosniff-header')
->when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Content-Type-Options', 'nosniff')
->register();
```
Multiple headers in one rule:
```php
Rules::create('security-headers')
->when()
->routeName('docs.*', 'LIKE')
->then()
->setHeader('X-Content-Type-Options', 'nosniff')
->setHeader('X-Frame-Options', 'DENY')
->setHeader('X-XSS-Protection', '1; mode=block')
->register();
```
Dynamic value using placeholders:
```php
Rules::create('product-header')
->when()
->routeParameter('product')
->then()
->setHeader('X-Product', '{route.parameters.product}')
->register();
```
Cache control headers:
```php
Rules::create('cache-docs')
->when()
->routeName('docs.show')
->then()
->setHeader('Cache-Control', 'public, max-age=3600')
->setHeader('Vary', 'Accept-Encoding')
->register();
```
### Array Syntax
```php
['type' => 'set_header', 'name' => 'X-Custom', 'value' => 'hello']
['type' => 'set_header', 'name' => 'X-Product', 'value' => '{route.parameters.product}']
```
> [!TIP]
> Use `setHeader` for standard HTTP headers like `Cache-Control`, `Vary`, security headers, and custom `X-*` headers. The header name and value are passed directly to `Symfony\Component\HttpFoundation\ResponseHeaderBag::set()`.
---
Canonical: https://www.millipress.com/docs/acorn-millirules/04-reference/03-route-context
---
title: 'Route Context Reference'
description: 'Reference for the Acorn MilliRules route context: Laravel route name, parameters, controller, URI, and middleware keys, with placeholder usage.'
menu_order: 100
---
# Route Context Reference
The Acorn package provides a `route` context that exposes metadata about the currently matched Laravel route. This context is used by route conditions internally and can be accessed in custom conditions, custom actions, and placeholders.
## Context Keys
The route context is loaded via `$context->load('route')` and provides the following keys:
| Key | Type | Description | Example |
|---------------------------|----------|-------------------------------------------|------------------------------------------------------------|
| `route.name` | `string` | The named route identifier | `'docs.show'` |
| `route.parameters` | `array` | All route parameters as key-value pairs | `['product' => 'millicache', 'path' => 'getting-started']` |
| `route.parameters.{name}` | `string` | A specific route parameter by name | `'millicache'` |
| `route.controller` | `string` | The fully-qualified controller class name | `'App\Http\Controllers\DocsController'` |
| `route.action` | `string` | The controller method name | `'show'` |
| `route.uri` | `string` | The route URI pattern (with placeholders) | `'/docs/{product}/{path?}'` |
| `route.middleware` | `array` | Middleware applied to the route | `['web', 'auth']` |
### Route Name
The route name as defined by `Route::name()` in your routes file. Returns an empty string if the route is unnamed.
```php
// Route definition
Route::get('/docs/{product}', [DocsController::class, 'show'])->name('docs.show');
// Context value
$context->get('route.name'); // 'docs.show'
```
### Route Parameters
All resolved route parameters as an associative array. Individual parameters can be accessed using dot notation:
```php
// Route definition
Route::get('/docs/{product}/{path?}', [DocsController::class, 'show']);
// Visiting: /docs/millicache/getting-started
$context->get('route.parameters'); // ['product' => 'millicache', 'path' => 'getting-started']
$context->get('route.parameters.product'); // 'millicache'
$context->get('route.parameters.path'); // 'getting-started'
```
### Controller and Action
The controller class name and method are extracted from the route's `uses` action:
```php
// Route definition: DocsController@show
$context->get('route.controller'); // 'App\Http\Controllers\DocsController'
$context->get('route.action'); // 'show'
// Invokable controller: DocsController (no @method)
$context->get('route.controller'); // 'App\Http\Controllers\DocsController'
$context->get('route.action'); // ''
```
### URI Pattern
The raw route URI pattern with parameter placeholders intact:
```php
$context->get('route.uri'); // '/docs/{product}/{path?}'
```
### Middleware
An array of middleware names or classes applied to the route:
```php
$context->get('route.middleware'); // ['web', 'auth']
```
## Using Context in Placeholders
Action arguments support `{context.key}` placeholders that are resolved at execution time. All route context keys are available:
```php
Rules::create('dynamic-redirect')
->when()
->routeParameter('product')
->then()
->redirect('/new-docs/{route.parameters.product}', 301)
->register();
Rules::create('dynamic-header')
->when()
->routeParameter('product')
->then()
->setHeader('X-Product', '{route.parameters.product}')
->setHeader('X-Route', '{route.name}')
->register();
```
## Using Context in Custom Code
In custom conditions and actions, load and access the route context through the `Context` object:
```php
use MilliRules\Context;
// In a custom condition's get_actual_value() or action's execute()
protected function get_actual_value(Context $context): string
{
// Load route context (idempotent — safe to call multiple times)
$context->load('route');
// Read a value with a default
$name = $context->get('route.name', '');
return is_string($name) ? $name : '';
}
```
```php
use MilliRules\Context;
// In a custom action
public function execute(Context $context): void
{
$context->load('route');
$product = $context->get('route.parameters.product', '');
if (is_string($product) && $product !== '') {
app('millirules.response')->addHeader('X-Product', $product);
}
}
```
> [!TIP]
> No need to call `$context->load('route')` before accessing route keys. You can use `$context->get('route')` directly. The load is lazy — route data is built only on the first call and cached for subsequent access.
## Empty Context Behavior
When there is no matched Laravel route (e.g., a 404 page or a request handled outside the router), the route context returns empty defaults:
| Key | Empty value |
|---------------------------|----------------------------------|
| `route.name` | `''` (empty string) |
| `route.parameters` | `[]` (empty array) |
| `route.parameters.{name}` | `''` (empty string, via default) |
| `route.controller` | `''` (empty string) |
| `route.action` | `''` (empty string) |
| `route.uri` | `''` (empty string) |
| `route.middleware` | `[]` (empty array) |
Route conditions will not match against empty values unless explicitly checking for empty strings. This means rules with route conditions naturally skip unmatched requests.
---
Canonical: https://www.millipress.com/docs/acorn-millirules/04-reference/04-changelog
---
title: 'Changelog'
description: 'Acorn MilliRules release history: new features, fixes, and breaking changes across versions of the rules engine integration for Acorn and Laravel.'
menu_order: 40
---
# Changelog
## [1.1.1](https://github.com/MilliPress/Acorn-MilliRules/compare/v1.1.0...v1.1.1) (2026-07-16)
### Bug Fixes
* **deps:** require MilliRules 1.2 for the shared rules engine ([703015b](https://github.com/MilliPress/Acorn-MilliRules/commit/703015b6979ec3d1242b92866f3aad61306ea1ea))
* Remove redundant is_object() check flagged by PHPStan 2.2 ([e92b5f2](https://github.com/MilliPress/Acorn-MilliRules/commit/e92b5f20f8e8dda9b3112a7d9f8e6951316bc34c))
## [1.1.0](https://github.com/MilliPress/Acorn-MilliRules/compare/v1.0.0...v1.1.0) (2026-03-31)
### Features
* **deps:** Require MilliRules ^1.0 and support Acorn 6.x ([8452671](https://github.com/MilliPress/Acorn-MilliRules/commit/8452671bf8a8cbc7912a16a148266ba9c41a356b))
## 1.0.0 (2026-02-13)
### ⚠ BREAKING CHANGES
* The PHP namespace changed from MilliPress\AcornMilliRules to MilliRules\Acorn, and AcornMilliRulesServiceProvider was renamed to ServiceProvider. The Composer package name (millipress/acorn-millirules) remains unchanged.
### Features
* Add execution layer with ResponseCollector, built-in actions, and make commands ([e750afb](https://github.com/MilliPress/Acorn-MilliRules/commit/e750afbd3b2a752c2b69353fd6f52de4ab95bf13))
* Add rules:actions and rules:conditions CLI commands ([cc8e0a5](https://github.com/MilliPress/Acorn-MilliRules/commit/cc8e0a5288daa506c4b8a422ccf36d735d4337db))
### Bug Fixes
* **cli:** Deduplicate cross-package rules in rules:list output ([58987a6](https://github.com/MilliPress/Acorn-MilliRules/commit/58987a6a4f054d705f471dc5bba5899ce6d89b15))
* **cli:** Preserve wildcard types in builder column display ([485adc4](https://github.com/MilliPress/Acorn-MilliRules/commit/485adc4c609a015d5b92c88ce0e29b948a4199c8))
* Use project's Composer ClassLoader instead of first registered ([d00ea00](https://github.com/MilliPress/Acorn-MilliRules/commit/d00ea0083b97384e75a5785b13378c3d54e34686))
### Refactoring
* Move app action/condition namespaces under App\Rules ([f48d418](https://github.com/MilliPress/Acorn-MilliRules/commit/f48d418f2aeddb272850987d313b3271845765c8))
* Rename namespace to MilliRules\Acorn and class to ServiceProvider ([2d09b6f](https://github.com/MilliPress/Acorn-MilliRules/commit/2d09b6fb4c9d8b93b8b8aceac40d311c277fb632))
* Simplify type discovery using MilliRules 0.7.1 getters ([9cab3ae](https://github.com/MilliPress/Acorn-MilliRules/commit/9cab3aec01237187af5a928e4a772ae0a587360d))