Spiggle Rules Engine

• Why use Rules Engine?
• Features
• Requirements
• Installation
  • 1. Require the package
  • 2. Publish config & migrations, then migrate
  • 3. Register the Filament plugin
• Quick start
• Preset triggers
• Actions
• Host wiring
• Related Spiggle packages
• License

Tenant-scoped lifecycle rules for Laravel Filament — fire actions when members hit age milestones, tenure, inactivity, or spend thresholds.

#Why use Rules Engine?

• Zero-code automation — build lifecycle rules in Filament, no custom artisan commands per trigger
• Preset triggers — age milestones, tenure, inactivity, metric thresholds, and custom field matching out of the box
• Idempotent execution — rules fire at most once per subject per rule, tracked in an audit log
• Visual conditions — AND conditions filter subjects after the preset matches, configurable in the UI
• Tenant-scoped — each scope (organisation / family / team) manages its own rule set
• Host-wired actions — notify admins, create reminders, and dispatch events through your own callbacks

#Features

#Requirements

• PHP 8.2+
• Laravel 11+
• Filament ^5

#Installation

#1. Require the package

composer require spiggle/rules-engine

#2. Publish config & migrations, then migrate

php artisan vendor:publish --tag=rules-engine-config
php artisan vendor:publish --tag=rules-engine-migrations
php artisan migrate

#3. Register the Filament plugin

In your panel provider (e.g. app/Providers/Filament/AdminPanelProvider.php):

use Spiggle\RulesEngine\Filament\RulesEnginePlugin;

$panel->plugin(RulesEnginePlugin::make());

#Quick start

1. Sign in to your Filament panel.
2. Navigate to Rules Engine → Rules.
3. Create a rule, choose a preset trigger and configure its parameters.
4. Add optional AND conditions to narrow the subject set.
5. Add one or more actions to fire when the rule matches.
6. Set the rule to Active.

The engine evaluates all active rules whenever you call:

app(\Spiggle\RulesEngine\Services\RuleEvaluator::class)
    ->evaluateAllActiveRules('scheduled');

Wire this into your Laravel scheduler:

Schedule::call(function () {
    app(\Spiggle\RulesEngine\Services\RuleEvaluator::class)
        ->evaluateAllActiveRules('scheduled');
})->dailyAt('01:15');

#Preset triggers

metric_threshold requires a host-provided binding for MetricProviderInterface.

#Actions

#Host wiring

Configure config/rules-engine.php to connect the engine to your application's models and callbacks:

return [
    // The Eloquent model that represents a "subject" (e.g. a member/user)
    'subject_model' => \App\Models\Member::class,

    // The Eloquent model that represents a "scope" (e.g. a family/organisation)
    'scope_model' => \App\Models\Family::class,

    // Resolves the current subject from a context array
    'subject_resolver' => function (array $context): ?\App\Models\Member {
        return \App\Models\Member::find($context['subject_id'] ?? null);
    },

    // Resolves the current scope from a context array
    'scope_resolver' => function (array $context): ?\App\Models\Family {
        return \App\Models\Family::find($context['scope_id'] ?? null);
    },

    // Gates who can manage rules in the Filament UI
    'can_manage_rules' => function (\App\Models\User $user): bool {
        return $user->hasRole('admin');
    },

    // Called by the notify_scope_admins action
    'notify_scope_admins' => function ($scope, array $payload): void {
        // send your notification here
    },

    // Called by the create_reminder action
    'create_reminder' => function ($subject, $scope, array $payload): void {
        // create your reminder here
    },

    // Optional: bind a MetricProviderInterface implementation for metric_threshold presets
    'metric_provider' => null,
];

#Related Spiggle packages

#License

MIT — free and open source forever. See LICENSE.