Wirefence Laravel Package

Getting Started

Wirefence is a Laravel package for declaring "fences" — explicit boundaries around parts of your application (routes, Livewire components/actions, or service-layer entry points) that control who can cross them and under what conditions. Version 1.0.0 is the first stable release, so the public API is now the one to build against.

Start here, in order:

1. composer.json — confirm the PHP and Laravel version constraints before installing. At 1.0.0 the support matrix is now fixed; don't assume it matches your app.
2. README — the install snippet, the config publish tag, and the "quick start" example are the canonical entry points. The 1.0.0 changelog is only a commit link, so the README and the test suite are your real documentation.
3. The service provider (src/*ServiceProvider.php) — this tells you what the package actually registers: config merge/publish, middleware aliases, facade or singleton bindings, Blade/Livewire directives, and any artisan commands. Read this before wiring anything up.
4. tests/ — at a 1.0.0 with a sparse changelog, the tests are the most reliable description of intended behavior. Look for the feature tests that assert allow/deny outcomes; they double as copy-paste examples.

Minimal first use case: install, publish the config (php artisan vendor:publish --tag=wirefence-config — confirm the tag in the README), and fence a single low-risk route or component in a local environment. Verify the default decision (deny-by-default vs. allow-by-default) on that one boundary before rolling fences out anywhere else. Getting the default posture right up front prevents a silent open door.

Implementation Patterns

Fence at the boundary, not in the middle. Apply fences where requests enter — route middleware, a Livewire lifecycle hook, a form request, or a controller/action trait — rather than sprinkling checks through your domain code. Domain services should stay fence-agnostic so they remain testable in isolation.

Layer with native authorization. Use Laravel gates and policies for "who is this user and what may they do," and use Wirefence for "is this entry point open, from where, and how often." Treating the fence as a second, coarser layer keeps your policies reusable and your fences declarative.

Define rules centrally. Prefer config- or attribute-driven fence definitions over inline closures scattered across controllers. Central definitions are auditable, diffable in review, and cacheable. If the package supports class-based rules/resolvers, use those for anything with branching logic.

Test the fence, not just the happy path. For every fenced boundary, write a feature test for the allowed case and the denied case, asserting the actual response (403 vs. redirect vs. silent abort). If the package ships testing helpers, use them; otherwise assert at the HTTP/Livewire level so you're testing real behavior.

Environment-specific posture. Keep fences strict in production and staging, and consider an explicit permissive profile for local/CI so local development isn't friction-heavy. Make that difference visible in config rather than hidden in conditionals.

Integration points to check deliberately: queued jobs and scheduled commands (does the fence apply outside HTTP?), API routes versus web routes, and any place you call an action directly rather than through the framework — a fence enforced by middleware will not protect a direct in-process call.

Gotchas and Tips

• 1.0.0 with an empty changelog. There's no migration narrative to rely on, so pin the exact version ("edulazaro/wirefence": "1.0.0") and read the diff between 1.0.0 and any 1.0.x patch before upgrading. Don't float on ^1.0 blindly during the first weeks of a new stable line.
• Config caching. If fence definitions live in config, run php artisan config:cache in your deploy pipeline and verify the fences still apply. Closures in config files break config:cache — convert them to class references if you hit LogicException: Your configuration files are not serializable.
• Middleware order. Register the fence middleware after session/auth middleware, otherwise it evaluates against an unauthenticated request and every fenced route denies (or worse, allows). Verify ordering in bootstrap/app.php or Kernel.php depending on your Laravel version.
• Livewire hydration. If fences cover Livewire actions, remember the fence is evaluated on the subsequent component request, not the initial page render. Test an actual ->call() or action invocation, not just the initial mount — a fence that looks fine on render can be bypassed on update.
• Deny semantics. Determine early whether a denied fence throws an exception, aborts with 403, or redirects. This determines how your exception handler and error pages behave, and whether you need a custom render for API clients (JSON vs. HTML).
• Debugging. When a fence unexpectedly denies, check in this order: is the fence registered at all (middleware alias resolved?), is the rule matching the right route/component name, is the config cached from a stale build, and does the request satisfy the fence's conditions (IP, guard, role)? Add temporary decision logging rather than guessing.
• Extension points. Look for contracts or bindings in the service provider that let you swap the rule resolver or decision reporter. If you need custom logging/telemetry on denials, that's usually the intended hook — subclass or rebind there rather than forking the package.
• Upgrade hygiene. Keep your fence definitions in version control alongside the pinned package version so that a future breaking change is a config diff, not an archaeology exercise.