Security Bundle Laravel Package

Getting Started

Install and register the bundle. With such a small dependency footprint (0 dependents), you're effectively the first integrator, so treat the install as a spike rather than a plug-in:

composer require netbull/security-bundle

Then register it in config/bundles.php:

return [
    // ...
    NetBull\SecurityBundle\NetBullSecurityBundle::class => ['all' => true],
];

If the class name doesn't resolve, list what actually shipped in vendor/netbull/security-bundle/ and read composer.json's autoload.psr-4 block — the namespace may not match the package name.

Where to look first, in this order:

1. vendor/netbull/security-bundle/DependencyInjection/Configuration.php — this is the single most valuable file in an under-documented bundle. It gives you the exact config root key and every option, typed.
2. vendor/netbull/security-bundle/DependencyInjection/*Extension.php — shows which services get registered and under what conditions (usually feature flags in config).
3. Resources/config/services.yaml (or services.xml) — reveals the service IDs and tags you'll need for decoration and autowiring.
4. README.md — assume it's thin; the code is the source of truth.

Dump the live config reference rather than guessing:

bin/console config:dump-reference netbull_security

The extension alias is derived from the bundle name (NetBullSecurityBundle → netbull_security), but confirm it in the extension class's getAlias().

First use case. The typical entry point for a bundle like this is one of two things: (a) it ships a User entity / user provider you plug into a firewall, or (b) it layers role/permission checks on top of Symfony's existing security.yaml. Determine which by grepping for UserProviderInterface, Voter, and Entity/ in the package:

find vendor/netbull/security-bundle -type d -name Entity
grep -rl "UserProviderInterface\|extends Voter" vendor/netbull/security-bundle

If it ships entities, the fastest win is mapping them and running a migration against a scratch database. If it ships a Voter, wire it into one controller action with a known role and confirm the deny path returns 403 before you build anything on top of it.

Implementation Patterns

Doctrine-backed user/permission entities. If the bundle ships entities, the standard pattern is to import its mapping rather than hand-copy the classes:

// config/packages/doctrine.yaml
doctrine:
    orm:
        mappings:
            NetBullSecurityBundle:
                is_bundle: true
                type: attribute
                dir: 'Entity'
                prefix: 'NetBull\SecurityBundle\Entity'
                alias: NetBullSecurity

Then bin/console doctrine:migrations:diff and inspect the generated schema before applying. If you need to extend the User, the bundle almost certainly provides an MappedSuperclass or a resolve_target_entities block in its config — override the target entity in your config rather than subclassing the concrete class, or Doctrine will create two tables.

Permission checks in controllers. The idiomatic Symfony integration is #[IsGranted], and a well-built security bundle registers a voter that understands whatever permission string format it uses:

#[IsGranted('ROLE_ADMIN')]
#[Route('/admin/reports', name: 'admin_reports')]
public function reports(): Response { /* ... */ }

If the bundle uses an ACL-style resource.action syntax, keep the strings in a PHP enum or const map so you get autocompletion and a single place to grep when the naming scheme changes.

Centralise authorization behind your own facade. This bundle is at 1 star with no dependents — treat it as an implementation detail you may need to swap. Wrap it:

final class PermissionChecker
{
    public function __construct(private Security $security) {}

    public function can(string $permission, mixed $subject = null): bool
    {
        return $this->security->isGranted($permission, $subject);
    }
}

Now a future migration to Symfony's native voters or symfony/security-guard-style attributes is a one-file change.

Reuse the bundle's security events. If it dispatches authentication/permission events, subscribe in config/services.yaml with kernel.event_subscriber auto-configuration and log denials. This is how you get observability on a black-box bundle:

#[AsEventListener(event: 'netbull.security.access_denied')]
public function onDenied(AccessDeniedEvent $event): void
{
    $this->logger->warning('Denied', ['user' => $event->getUser()?->getUserIdentifier()]);
}

Verify the real event name with bin/console debug:event-dispatcher.

Firewall integration. Most bundles in this space expect a custom authenticator or provider. Wire it in security.yaml incrementally — one firewall, one provider — and check bin/console debug:firewall <name> after each change. Do not replace your whole security.yaml from a README snippet on a bundle this small; graft it in.

Testing. In functional tests, loginUser() works only if the bundle's user class implements UserInterface and PasswordAuthenticatedUserInterface. Create a fixture user through the entity manager, not a mock, so the voter's real code path runs.

Gotchas and Tips

AGPL-3.0 is the biggest gotcha here. This is a strong copyleft license. If you distribute the application, or if you expose it over a network (AGPL treats network use as distribution for modified versions), you may be obliged to release your source. For a proprietary SaaS product this is likely a non-starter without legal review. Check LICENSE in the vendor directory and get sign-off before it reaches production.

Assume the README is incomplete and stale. At this size, examples in the docs frequently reference class names or options that changed. Always confirm against Configuration.php and bin/console config:dump-reference. If a documented option throws InvalidConfigurationException: Unrecognized option, the docs are ahead of or behind the code.

Service IDs and autowiring. If the bundle's services aren't public and aren't registered with autoconfigure, injecting them by class name in your constructor will fail with "cannot autowire." Fix it in your services.yaml with an explicit binding, or use service('netbull_security.some_service_id') in YAML. Find the real ID with:

bin/console debug:container --show-private | grep -i netbull

Config cache is not invalidated by package updates. After changing bundle config or updating the package, run bin/console cache:clear before debugging — stale DI containers produce misleading "service does not exist" errors. In dev this is usually fine; in a Docker image build, make sure the cache dir isn't baked into the image.

Entity mapping drift. If you map the bundle's entities and later update the package, doctrine:schema:validate may start failing on new columns. Pin the version ("netbull/security-bundle": "1.*" or an exact tag) and re-run doctrine:migrations:diff as part of your upgrade checklist.

Extension points to prefer. When you need to change behaviour, prefer in this order: (1) config options, (2) resolve_target_entities / interface substitution, (3) event subscribers, (4) service decoration (decorates: netbull_security.x, keeping the original injected as .inner). Avoid forking — with 0 dependents and a single maintainer, a fork means you own the maintenance.

Debugging access denials. bin/console debug:container --tag=security.voter shows whether the bundle's voter is registered and what its priority is. A common failure is the voter being registered but not called because another voter with higher priority returns early — check security.access_decision_manager.strategy too. Enable the profiler's Security panel in dev; it lists every voter that was consulted and its vote.

Maintenance risk. Last release 2025-11-21 with 1 star and 0 dependents means a very thin signal on production usage. Budget for the possibility that you become the de facto maintainer. Keep your authorization logic behind an interface (see the facade pattern above) and keep the bundle's surface area confined to one or two files in your codebase.