Laravel Policy Engine Laravel Package

Getting Started

• Install with composer require dynamik-dev/marque, then publish the package config (php artisan vendor:publish --tag=marque-config) and run any shipped migrations before touching the API — most first-run confusion comes from a missing config file or un-migrated tables.
• Look first at the facade and the published config file, not the README's older snippets. v0.2.4's docs fix (PR #11) standardised everything on the facade as the canonical entry point, so any blog post or cached doc referencing a helper function or direct class instantiation may be out of date.
• First use case: wire the facade into a single controller or artisan command, exercise one write then one read, and confirm the read is served from cache. That single loop validates install, config, migrations, and the cache layer in one go.
• If you are on ≤ 0.2.3 and have caching enabled, treat upgrading to 0.2.4 as the first step rather than the last — see Gotchas.

Implementation Patterns

• Facade-first, but resolve from the container in tests. Call the facade in application code for readability, but inject the underlying contract/binding in unit tests so you can swap in a fake without touching the facade root. v0.2.4 makes the facade the documented surface, so leaning on it is now the supported path.
• Treat the cache as an optimisation, not a source of truth. With the cache key collision fixed in 0.2.4, cached reads are safe to rely on again, but writes should still invalidate explicitly. Pattern: write → assert the cache entry is gone → read → assert it repopulates.
• Scope cache keys yourself when you are multi-tenant. The collision fix addresses the package's own key generation, but if you run several tenants, stores, or databases against one cache backend, add your tenant/connection discriminator to the config prefix. This is cheap insurance and independent of package fixes.
• Use events for side effects, not internals. If you need to notify, index, or audit, attach a listener rather than overriding service methods. This keeps you insulated from the "duplicated logic" cleanup in PR #12, which changed internal call paths without changing the public contract.
• Wrap write paths in a transaction when a mark/state change is paired with your own model updates, and dispatch-dependent listeners should be queueable if they do I/O — event ordering is now deterministic, but that does not make listeners free.
• Cache warming in seeders/commands. If reads are hot on page load, warm the cache once in a scheduled command instead of letting the first request per key take the hit.

Gotchas and Tips

• Upgrade if you cache. The cache key collision fix (PR #12) is the headline item: on ≤ 0.2.3, distinct inputs could resolve to the same key and return stale or incorrect results. This is a silent-correctness bug, not a performance one — audit any code that "worked" on 0.2.3 but produced odd reads.
• Event timing changed. PR #12 also adjusted when events fire. Re-run any test suite or listener that assumed the old ordering; specifically, listeners that read persisted state inside the event may now see a different picture. Assert on event payloads rather than on database state read inside the handler.
• Internal duplication removed. If you extended or monkey-patched internals rather than using the facade or events, check those extensions after upgrading. Public API is unchanged; private surface is not guaranteed.
• Config caching bites. After publishing or editing the config, run php artisan config:clear (and cache:clear if you have been debugging cache keys). A stale cached config is the most common false-positive when a key-prefix change "doesn't work".
• Debugging cache issues: log the resolved cache key and store name from the config at boot in a local environment; if two logically distinct calls produce the same key, you have a prefix problem, not a package problem.
• Extension points to prefer: the facade, the events, and the config prefix. Avoid subclassing the internal service — that is the surface most likely to shift between patch releases.
• Version pinning: this is a 0.x package, so patch releases can carry behavioural fixes like the event-timing change. Pin to ^0.2.4 and read the changelog on every bump rather than relying on semver assumptions.