Laravel Conditional Actions Laravel Package

Getting Started

Treat this package as a rules engine: you define conditions (predicates over some context) and actions (side effects), persist the pairing as data, and mutate that data through an HTTP API instead of deploying code. The day-to-day value is letting ops/product change "when X and Y, do Z" behavior without a release.

Minimum steps:

1. Pin your Laravel version first. The last release is Feb 2020 (Laravel 5.8/6.x era) and the repo is archived. Run composer require my-com/laravel-conditional-actions in a scratch branch and immediately check the resolved constraints in composer.lock. If you're on Laravel 9+, expect to fork and patch the service provider rather than install cleanly.
2. Publish and migrate. Run the provider's publish groups for config and migrations, then php artisan migrate. Read the generated migration before running it — the schema tells you more about the package's mental model than the README does.
3. Read three files in this order: the condition contract, the action contract, and the API route file. Those define the entire extension surface. Everything else is plumbing.
4. Ship one rule end-to-end before designing anything else: e.g. "order total > 500 AND customer is flagged → enqueue a review job." Create it via the API, trigger it from a model event, confirm the job dispatched. This validates auth, serialization, and evaluation in one pass.

If step 1 fails and you don't want to maintain a fork, stop here and reimplement the two-contract pattern yourself — it's a few hundred lines and you'll own the upgrade path.

Implementation Patterns

Trigger from domain events, not controllers. Evaluation belongs in a listener or observer (OrderPlaced, UserUpdated), so every entry point — API, queue, console — gets the same rule behavior. Pass a well-defined context object (the model plus relevant scalars), not the whole request.

Keep actions thin and idempotent. An action should resolve a job or service and hand off. If the package retries or a rule is evaluated twice, a non-idempotent action (sending mail inline, incrementing a counter) will bite you. Prefer dispatch(new ...) and let the queue own retries.

Isolate failures per action. Wrap evaluation so one throwing action doesn't abort the rest of the chain; log the rule ID, context hash, and exception. If the package doesn't do this for you, write a thin evaluator service around it.

Version your rules as data. Seed a baseline rule set in a seeder so fresh environments and CI aren't empty. Store the rule payload as JSON with a schema version, and validate at the API boundary — an unvalidated condition config is an unhandled exception waiting for a Friday deploy.

Cache the rule set, invalidate on write. Rules are read on every evaluation and written rarely. A tagged cache keyed by the rule table, busted by the API write endpoint or a model observer, removes the query from the hot path.

Testing pattern: feature-test the API (create rule → assert persisted shape), then unit-test each action in isolation with a fake context. Use RefreshDatabase and a factory for the rule model; don't test the engine through your checkout flow.

Good fits: approval routing, discount/pricing adjustments, notification targeting, feature gating, escalation thresholds. Bad fits: invariants that must never be violated (accounting totals, authz), anything needing sub-10ms latency, anything a code reviewer must see in a diff.

Gotchas and Tips

• Archived means no security patches. An API that rewrites business logic is a high-value target. Put it behind authentication and authorization, require an audit trail (who changed which rule, before/after), and consider a staging→prod promotion flow rather than editing prod rules directly.
• Logic in rows is invisible logic. Your rules won't appear in PRs, code search, or static analysis. Mitigate with a UI or CLI that dumps the active rule set, and a periodic export committed to the repo as a diffable snapshot.
• Rule ordering matters. If multiple rules match, evaluation order determines behavior. Confirm whether the package orders by ID, priority column, or insertion order, and make it explicit — non-deterministic rule order is the hardest bug class here to reproduce.
• Stale context and N+1s. Conditions evaluated against serialized models can lazy-load relations per rule. Eager-load what conditions touch, or evaluate against a plain DTO.
• Silent swallowing. Check whether action exceptions are caught and discarded. If so, add logging at the evaluator level and alert on failure rate — a silently broken rule is worse than a loud one.
• Extend via contracts and config, never by editing vendor files. Register your conditions/actions through the package's config or container bindings so a fork/upgrade stays tractable. If the package requires editing vendor/, that's your signal to vendor the code into app/.
• Watch for migration/table-name collisions and confirm whether published migrations are safe to re-run. Since the package is frozen, you'll be maintaining those migrations yourself.
• Date/timezone conditions are a classic footgun — store and compare in UTC, and test a rule crossing a DST boundary.
• Exit strategy: abstract the engine behind a RuleEvaluator interface in your own code on day one. If (when) you replace the package, only the binding changes.