Security Bundle Laravel Package

Getting Started

Read this before you composer require anything: norsys/security-bundle is a Symfony bundle, not a Laravel package. It extends symfony/security-bundle and hooks into Symfony's firewall/security.yaml pipeline. Laravel does not use the Symfony Security component — it ships its own Illuminate\Auth guards, Gate, and Policy system. There is no service provider to register, no config/security-bundle.php to publish, and no facade. Installing it into a Laravel app will at best be dead weight and at worst drag in a conflicting Symfony dependency tree.

So there are two honest ways a Laravel developer "gets started" here:

1. You maintain a Symfony service somewhere in the estate (legacy admin, back-office, an acquired product). Then the bundle is directly usable, and the steps below apply.
2. You are evaluating it as a reference implementation for how to structure authorization in a Laravel app. In that case the deliverable is a design note, not a dependency.

If you are on Symfony:

composer require norsys/security-bundle

Register it in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3.x). Then look at these three places, in this order:

1. DependencyInjection/Configuration.php in the bundle source. With no README beyond a one-paragraph description and no changelog, this file is the documentation — it defines every config key, its type, and its default. Read it before reading anything else.
2. DependencyInjection/*Extension.php — shows which services get wired and which parameters are set from your config.
3. Your app's config/packages/security.yaml — the bundle layers on top of native security config rather than replacing it, so the interaction between the two is where all the behaviour lives.

First use case: take an existing hand-rolled firewall + duplicated access_control blocks and collapse them into the bundle's defaults, so that role hierarchy and access rules live in one environment-aware file instead of being copy-pasted across config/packages/dev/ and config/packages/prod/.

For the Laravel-side reader, the first use case is a translation exercise, and it's genuinely useful:

Implementation Patterns

Firewall-first configuration. Everything in Symfony security keys off firewall names. The bundle's value is that it gives you sensible defaults so you declare the intent (admin area requires ROLE_ADMIN, API area is stateless) rather than the full authenticator wiring. Pattern: one firewall per distinct auth strategy, not one per route. If you find yourself adding a firewall per controller, you want access_control entries instead.

Order-dependent access_control. Rules are evaluated top-to-bottom and the first match wins. The correct pattern is specific-before-general:

access_control:
    - { path: ^/admin, roles: ROLE_ADMIN }
    - { path: ^/api,   roles: ROLE_API }
    - { path: ^/,      roles: IS_AUTHENTICATED_ANONYMOUSLY }

Getting this backwards is the single most common way to accidentally expose an admin route, and it fails open, not closed.

Environment-aware config. Split shared rules into a base file and use when@dev / when@prod (Symfony 5.3+) or per-environment config/packages/{env}/ directories for the deltas. Typical deltas: security.access_control relaxed in dev, require_previous_session: false for stateless API firewalls, debug toolbar access.

Role + permission layering. Keep roles coarse (ROLE_ADMIN, ROLE_EDITOR) and permissions fine-grained. Roles go in security.yaml; permissions belong in voters, because voters are where the "can this specific user edit this specific object" logic lives. If your permission checks are all is_granted('ROLE_X') string comparisons scattered through controllers, you've built a boolean soup with no audit surface.

Wrap it behind your own interface. This is the pattern that matters most given the package's maturity profile. Put an internal adapter in front of anything the bundle provides — your controllers call $this->authorization->canEdit($user, $post), not bundle types directly. That turns a future replacement (or a migration to Symfony's native authenticator system, or a port to a Laravel gate) into a contained change.

For the Laravel port specifically: the pattern worth stealing is voters → policies, and the discipline of keeping authorization decisions in one declarative place rather than inline in controllers. Laravel's Gate::before() is the direct analogue of role_hierarchy (super-admin short-circuit), and access_control ordering maps cleanly onto the order of entries in a route group's middleware stack.

Gotchas and Tips

The 2018 release date is the headline risk. Last release 2018-07-17 puts this in the Symfony 3.4 / 4.x era. That means: no Symfony 5/6 support, no PHP 8 typed-property compatibility guarantees, and almost certainly the deprecated Guard authenticator system rather than Symfony 5.3+'s AuthenticatorInterface. Guard was removed in Symfony 6. If your Symfony service is on 6.x, this bundle will not install — treat that as a hard blocker, not something to patch around.

Zero stars, single maintainer, no changelog. There is no community signal, no release cadence, and no published backwards-compatibility policy. Treat it as an unmaintained internal library that happens to be on Packagist: read the source (it is small — that is the one thing in its favour), vendor it if you depend on it, and put it on the risk register with an owner and a review date tied to your next framework upgrade.

Missing docs are a debugging tax. With only a one-paragraph description, error messages like "unrecognized option under norsys_security" are your primary feedback loop. Use the console:

bin/console debug:config norsys_security   # what the bundle actually resolved
bin/console debug:container --tag=security.voter
bin/console debug:firewall admin            # which firewall a request hits

debug:firewall is the fastest way to answer "why is my route anonymous?" — it tells you the matched firewall, the provider, and the authenticators, which is usually three guesses you no longer have to make.

Cache invalidation. Symfony compiles security config into the container. Editing YAML without bin/console cache:clear in a non-dev environment produces ghost behaviour where your changes appear to do nothing. In dev, debug:config reflects the on-disk file; the running request may not.

Voter caching and security.access_decision_manager. If a permission check returns a surprising result, check strategy (affirmative / unanimous / priority). unanimous means one abstaining voter silently denies everything — a classic "my voter works in isolation but not in situ" bug.

Extension points to prefer over forking: custom Voter implementations, custom UserProvider, and a custom Authenticator/Guard. Wiring your logic into these means the bundle's config plumbing stays untouched and an upgrade (or removal) is mechanical. Forking the bundle's Security services is the path to a package you can never upgrade.

For the Laravel developer's decision log: this is not adoptable into a Laravel codebase, and on the Symfony side the version lag makes it a blocker on anything current. The realistic outcome is "read it for structural ideas, do not depend on it." If the goal was to reduce auth boilerplate in Laravel, the equivalent ground is already covered by laravel/breeze, laravel/fortify, and spatie/laravel-permission — all actively maintained, all with visible CI and a stated support policy.