Sam Ecore Security Manager Bundle Laravel Package

Getting Started

Confirm the framework before doing anything else. This is a Symfony bundle, not a Laravel package. There is no service provider, no config file to publish, and no facade. If you are on Laravel, stop here: the only practical day-to-day leverage is reading the repository as a reference implementation of an authorization model, not installing it. Do not spend a sprint trying to make a Symfony kernel bundle boot inside a Laravel container — the payoff is zero and the maintenance cost is permanent.

Where to look first, in this order:

1. composer.json — the PHP and symfony/* constraints tell you immediately whether it can even resolve against your runtime. Look specifically for symfony/security-acl and any canaltp/* siblings. If those are pinned to ~2.x/~3.x, this is a Symfony 3.4-era artifact and will not install on a modern stack.
2. The *Bundle class and DependencyInjection/*Extension.php — this is the entire surface area. Everything the package does is services registered here and parameters read from the extension.
3. Resources/config/services.yml (or services.xml) — the definitive list of what gets wired into the container. This is your real documentation.
4. Security/ — the authenticator, user provider, and any voters/listeners. This is the code path that actually runs on a request.
5. LICENSE — confirm it before you copy a single line. CanalTP's Navitia lineage includes AGPL-family licensing, and vendoring without clarity is a compliance finding, not a style issue.

First use case. The only scenario where you "use" this bundle rather than read it is: you already operate a Symfony ≤3.4 application that speaks the Sam e-core data model, and you need requests authenticated against ECORE services. The minimal wiring is a firewall entry in security.yaml that names the bundle's authenticator and user provider, plus a provider definition pointing at the bundle's service ID. Start by running bin/console debug:container --tag=security.authenticator and bin/console debug:config security in the host app to confirm the bundle's services actually registered and that your firewall picks them up. If they do not appear, the bundle was not enabled in config/bundles.php (or AppKernel.php) and nothing downstream will work.

If you are on Laravel, the first use case is different and cheaper: open the voters and permission checks, write down the permission model as a one-page spec (entity-scoped roles, ownership, hierarchical referential permissions over lines / networks / stop areas / vehicle journeys), then implement that spec with Gate/Policy and spatie/laravel-permission. That is a day or two of reading and gives you the only genuinely transferable asset in the repository.

Implementation Patterns

Configuration over listeners. The bundle's whole value proposition is that you declare authenticators, user providers, and access rules in configuration and the container wires the services. Lean into that: keep your security.yaml firewalls declarative, and resist the urge to hand-write a kernel event listener that duplicates what the bundle already registers. If you find yourself writing a listener, you have probably mis-scoped the config.

Sit alongside, don't replace. The bundle is designed to coexist with Symfony's standard security.yaml. The practical pattern is a dedicated firewall for the ECORE-authenticated paths (API routes, service endpoints) while leaving your existing form-login or session firewall untouched for the rest of the app. Do not try to retrofit the ECORE authenticator onto the main firewall your users already log into — authenticator ordering and entry_point conflicts are the fastest way to break interactive login.

Override by decoration, not by patching. The description explicitly calls out DI-friendly services that are easy to override or decorate. If you need different credential handling or a different user loading strategy, define a service in your app that decorates the bundle's service ID (or replaces the parameter via your own extension that loads after the bundle's). This keeps the vendor directory swappable and means a Composer update won't silently eat your changes. Concretely: decorates: sam_ecore_security.<service_id> with the bundle's ID as the inner service argument.

Environment-specific swapping. The intended pattern is to swap implementations per environment — a stub or in-memory provider in dev and test so you don't need a live ECORE endpoint to run the suite, and the real provider in prod. This is the single highest-leverage use of the bundle's DI design: define your firewall config per environment in config/packages/dev/security.yaml etc., and keep the ECORE authenticator out of test entirely.

Treat it as a spec, not a dependency (Laravel and greenfield Symfony alike). The permission semantics — who may read or edit which referential object — map cleanly onto Laravel policies. Read the voter logic, extract the rules as a written spec, and rebuild on native primitives. You get the domain knowledge without inheriting an unmaintained authentication dependency on your critical path.

Pin and vendor if you must depend. If a hard dependency is genuinely unavoidable, add it to your repository (not just Packagist), pin the exact SHA, and write the ACL table migrations in your own database/migrations so they survive removing the bundle later. Bundle-managed Doctrine mappings that you don't control are a schema-drift trap.

Gotchas and Tips

Zero stars, zero dependents is the headline, not a footnote. There is no CVE watch, no upstream fix path, no issue triage, and nobody to ask when behaviour is surprising. Any vulnerability in the pinned transitive tree becomes yours to patch. If this sits in your authentication path, that is a standing finding that needs a named owner and a documented risk acceptance — not a silent composer require.

The ACL dependency is the killer. symfony/security-acl was deprecated in Symfony 3.4 and removed in 4.0. A bundle of this vintage typically pins symfony/symfony ~2.3|~2.7 and PHP 5.5–7.0. On a modern PHP 8 / Symfony 6–7 host, Composer resolution will almost certainly fail, and the failure will block unrelated upgrades across the whole application — the highest-probability and most expensive failure mode. Run a timeboxed dependency-resolution spike on a throwaway branch (composer why-not) before committing to anything.

The transitive tree is the real cost centre, not the bundle. The bundle's own code is thin glue; the old Doctrine ORM, old ACL schema, and possibly abandoned canaltp/* siblings are what you actually take ownership of. Price that, not the package.

Debugging a firewall that "doesn't authenticate": work outward. bin/console debug:container --tag=security.authenticator to confirm registration, debug:config security to confirm your firewall actually references the right provider/authenticator ID, then debug:firewall <name> for the resolved chain. In dev, the security profiler's "Access Decision" and "Authenticators" panels will show which voter or authenticator returned what — far faster than adding dump() calls to vendor code.

Authorization bugs fail open. Silent permission drift after a framework or dependency upgrade is the classic failure here: the voter stops being invoked, the ACL returns nothing, and access is granted rather than an exception thrown. Write explicit tests for the "should be denied" case, not just the happy path — a passing login test tells you nothing about whether the object-level check still runs.

Config quirks. Check whether the bundle's extension loads before or after yours before relying on parameter overrides — Symfony extension load order is by bundle registration order, and an override that "worked" in one app can be clobbered by bundle ordering in another. Also verify the firewall's provider key is set: an authenticator without an explicit provider silently falls back to the first configured provider, which is a common source of "it authenticates the wrong user" reports.

Extension points worth knowing. Service decoration, parameter overrides via a compiler pass, and replacing the user provider are the three supported seams. Anything deeper — changing how tokens are built, altering the voter logic — is a fork, and a fork means you own it: put it in your VCS with CI, a PHP version matrix, and dependency scanning, none of which exist upstream.

Do not sequence this ahead of a working auth model. The bundle assumes a populated e-core schema. Without that schema it has nothing to guard, and you will burn time on integration that proves nothing.