Download the PHP package fedale/access-control-bundle without Composer

Fedale AccessControl Bundle

Rule-based HTTP access control for Symfony. The bundle inspects every incoming request and allows or denies it according to a set of rules matched on path, host, HTTP method, client IP and user roles. Rules can come from any source — Doctrine (built-in), a YAML/array, a remote API, MongoDB… — because the lookup sits behind a single interface. An optional PSR-6 cache layer keeps rule loading cheap.

Features

• Allow/deny rules matched on path (regex), host (regex), HTTP methods, client IP / CIDR and roles.
• First-match-wins evaluation, ordered by an explicit sort field.
• Source-agnostic: rules are read through RuleProviderInterface. Doctrine is the default; any service can replace it.
• Super-admin bypass and configurable anonymous-access gating.
• Default policy (allow/deny) applied when no rule matches.
• Optional PSR-6 caching of the rule set, configurable from YAML.
• Built on Symfony's native ChainRequestMatcher — no deprecated APIs.

Requirements

• PHP 8.2+
• Symfony 6.4 or 7.x (http-kernel, http-foundation, security-bundle, security-core)
• psr/cache ^3.0
• Doctrine ORM is only required when you use the default doctrine rule provider (doctrine/orm, doctrine/doctrine-bundle). It is a require-dev/suggest dependency, not a hard one.

Installation

Not on Packagist yet. Until the package is published, point Composer at the repository directly in your application's composer.json:

then run composer require fedale/access-control-bundle:dev-main.

If you use Symfony Flex, the bundle is registered automatically. Otherwise, add it to config/bundles.php:

Quick start

1. Create the configuration file:

2. Create the database table and add a rule (see Doctrine provider). For example, a rule that blocks /admin for everyone except ROLE_ADMIN:

3. That's it. A request to /admin from an anonymous user now receives:

while a user with ROLE_ADMIN (or ROLE_SUPER_ADMIN) passes through.

Configuration reference

All options with their defaults:

How it works

The bundle registers a listener on the kernel.request event (priority -10). For every main request it calls AccessDecisionManager::decide(), which evaluates:

1. Bundle disabled? (enabled: false) → allow.
2. Super admin? (current user is granted super_admin_role) → allow.
3. Find the first matching rule (rules are evaluated in sort order, first match wins):
   • rule found and allow = false → deny;
   • rule found, allow = true, no roles required → allow;
   • rule found, allow = true, roles required → allow if the user is granted any of them, otherwise deny.
4. No rule matched (fallback):
   • user is not authenticated and anonymous_access = false → deny;
   • otherwise apply default_policy (allow → allow, deny → deny).

When the decision is deny, the listener dispatches an AccessDeniedEvent and then short-circuits the request with a 403 Forbidden response. If no listener provides its own response, the body is content-negotiated: clients that send Accept: application/json get {"error":"Access denied"}, everyone else gets the plain text Access denied.

The bundle stays outside Symfony's firewall: a denied request always yields a 403, it is never redirected to the login page. Authentication-driven redirects remain the firewall's job — this layer only answers "may this request proceed?".

Reacting to a denial (AccessDeniedEvent)

To log denials, emit metrics, or return a custom response (a branded error page, a redirect, a different JSON shape), listen for AccessDeniedEvent. Setting a response on the event overrides the default one:

Defining rules

A rule is described by the AccessRule DTO. Whatever the source, it produces objects with these fields:

Matching is delegated to Symfony's ChainRequestMatcher: path and host are treated as regular expressions, while methods and ips only constrain the request when non-empty. Invalid path/host regular expressions are rejected as soon as the rule is built, with an InvalidArgumentException naming the offending rule.

Client IP behind a proxy. The ips field matches against Request::getClientIp(). If your app sits behind a reverse proxy or load balancer, configure Symfony's trusted proxies (framework.trusted_proxies / trusted_headers) — otherwise getClientIp() returns the proxy's address and your IP rules will match the wrong client.

Rule sources (providers)

The decision logic never talks to a database directly — it depends only on RuleProviderInterface:

The provider option selects which implementation is wired.

Doctrine (default provider)

With provider: doctrine the rules are read from the access_control table, mapped by the AccessControlEntity. Only active rules are returned, ordered by sort.

The bundle registers its own Doctrine ORM mapping automatically (via prependExtension) when provider: doctrine and DoctrineBundle is installed — you do not need to add a doctrine.orm.mappings entry pointing into vendor/ in your application. The mapping is skipped automatically if you switch to a custom provider.

Create the schema with a migration (recommended):

or, in development:

Add rules like any other entity:

The setters normalise input for you (trim strings, de-duplicate roles/IPs, upper-case methods).

Custom provider (YAML, API, Mongo, …)

To read rules from anywhere else, implement RuleProviderInterface and point provider at your service id. Here is a provider that returns rules defined in plain PHP:

If autowiring/autoconfiguration is on (the Symfony default), the service id equals the class name. Select it:

With a custom provider you do not need Doctrine at all.

The selected provider must resolve to a real service; otherwise the RuleProviderInterface alias is missing and the container fails to boot.

Caching

When cache.enabled is true, the selected provider is transparently wrapped in a CachedRuleProvider that stores the materialised rule list in a PSR-6 pool. This works for any source (Doctrine, custom, …) because it decorates the interface, not the implementation.

Invalidation. With ttl: null the cache never expires, so after changing your rules you must clear it. Either clear the configured pool, or delete the single cache key used by the bundle:

To turn caching off entirely, set cache.enabled: false.

Super admin & anonymous access

• Super admin — any user granted super_admin_role (default ROLE_SUPER_ADMIN) bypasses every rule. Set super_admin_role: '' to remove the bypass.
• Anonymous access — only affects requests that match no rule. With anonymous_access: false, unauthenticated users are denied on an unmatched request even if default_policy: allow. Authenticated users instead fall through to default_policy.

Example — site that is open by default, but never to anonymous users on unknown routes:

Explicit allow rules (e.g. for ^/login) are always evaluated first, so public routes keep working.

Architecture / extension points

Everything is wired through small contracts under src/Contract/, so you can override any piece:

On every denial the listener dispatches AccessDeniedEvent, so you can hook in logging, metrics or a custom response without replacing any of the above (see Reacting to a denial).

Default implementations live in src/Matcher/, src/Security/ and src/Cache/. To replace one, register your own service aliased to the relevant interface.

Console

List the effective rules as the bundle sees them (read-only, works with any provider):

With the Doctrine provider only active rules are listed; with caching enabled you see the materialised (cached) list. Enabling/disabling rules is plain entity manipulation — see Doctrine provider.

A Symfony Profiler data collector (showing which rule matched and the resulting decision) is a natural next extension but is not bundled yet, to keep the dependency surface small.

Testing

The suite covers unit (matchers, decision manager, cache), DI wiring, a functional test booting a real HttpKernel, and ORM mapping validation.

License & contributing

Released under the MIT License. Issues and pull requests are welcome.