Bouncer Laravel Package

Technical Evaluation

Architecture fit. mediapress/bouncer is an Eloquent roles-and-abilities package in the lineage of josephsilber/bouncer: a service provider, published migrations (roles, abilities, permissions, assigned_roles, entity_abilities), a Bouncer trait for models, and integration with Laravel's Gate so that existing can() / @can / authorize() calls resolve role- and ability-based checks. Architecturally this is a comfortable fit for a conventional Laravel monolith or modular monolith that already leans on Gate/Policy. It is a poor fit if the application has standardized on Spatie permissions, custom policy registries, or an external authorization service — mixing two authorization sources is a well-known source of privilege-escalation bugs.

Integration feasibility. The material constraint is distribution: this is a Bitbucket-hosted fork with no star count reported and zero dependents, so there is effectively no ecosystem validation and likely no Packagist presence. Adoption therefore requires a Composer VCS repository entry, Bitbucket credentials in CI (app password or SSH key with expiry management), and a pinned commit or tag. Before any code is written, verify the fork's composer.json for PHP/Laravel version constraints, license, autoload namespace (Mediapress\Bouncer vs Silber\Bouncer), and whether migrations and config are publishable. Confirm whether it is a straight mirror of upstream or contains local patches — the diff against upstream is the single most important artifact for evaluating long-term risk.

Technical risk.

• Supply chain: single Bitbucket namespace, unknown maintainer continuity, no security advisory channel, no CVE monitoring, and a hard build dependency on repository availability and credential validity.
• Divergence: an unmerged fork drifts from upstream fixes; you inherit maintenance of both the fork and the merge burden.
• Framework coupling: Bouncer relies on Gate before/after callbacks, the auth guard, and cache stores; Laravel major-version upgrades can break these internals silently rather than loudly.
• Schema coupling: the pivot and entity tables become part of your data model; replacing the package later means data migration, not just a Composer swap.
• Cache correctness: ability caching is per-user and per-scope; stale cache after role changes manifests as intermittent authorization failures that are hard to reproduce.
• Opportunity score of ~20.8 and zero dependents is a weak signal — treat it as a build-vs-adopt decision rather than a routine dependency addition.

Key questions.

1. Is this a fork of josephsilber/bouncer? What is the exact diff, and why does it exist (Laravel version support, multi-tenancy, bug fixes)?
2. Which Laravel and PHP versions are supported, and does that cover our upgrade roadmap?
3. What is the license, and does it permit internal mirroring?
4. Who owns mediaclickTR/mediapress internally, and what is the commitment to patch and security-fix?
5. Are there tests, CI, and a tagged release history — or is this a vendored snapshot?
6. Does it support tenant scoping (Bouncer::scope()), and does that match our tenancy model?
7. What is our exit path if the repository disappears or the maintainer goes silent?

Integration Approach

Stack fit. Suitable for a Laravel application using Eloquent, the default Gate, and a relational database (MySQL/PostgreSQL). It assumes the standard users-style authenticatable model and a single authorization source of truth. If the platform is multi-tenant, confirm scope support before committing; if it is API-only with token guards, confirm that Gate integration behaves as expected across guards.

Migration path. The recommended path is not to adopt the fork directly. In order of preference: (1) use upstream josephsilber/bouncer if version constraints allow; (2) if the fork contains required patches, mirror it into an internal Git host (or Private Packagist/Satis) and maintain it as an internal package with named owners; (3) if the fork's value is narrow, implement authorization with native Gate/Policy plus a thin role table, eliminating the dependency entirely. Direct Bitbucket VCS references in composer.json should be treated as a stopgap, not a steady state.

Compatibility. Validate the fork's composer.json against the application's Laravel and PHP constraints, and check for migration-name collisions with any existing auth tables. Confirm the package's config file is publishable and that the cache store it uses (default Laravel cache) is the same one used in production. Check whether the fork targets the same major Laravel version as the rest of the dependency graph — a single stale constraint can block framework upgrades for the whole application.

Sequencing.

1. Spike (1 sprint): clone the fork, diff against upstream, run its test suite, and stand it up in a throwaway Laravel app.
2. Decision gate: adopt upstream, internalize the fork, or build native — documented with the diff review as evidence.
3. Schema design review: agree on roles/abilities taxonomy and tenant scoping before migrations land.
4. Implementation: seed roles and abilities, wire Gate integration, and replace ad-hoc authorization checks.
5. Test harness: authorization matrix tests (role × ability × tenant), including negative cases.
6. Rollout: behind a feature flag, with a documented rollback (keep the legacy checks until the matrix passes in production).
7. Exit plan: record the replacement path and the data-migration steps in the ADR.

Operational Impact

Maintenance. The fork becomes an internal dependency the moment it is adopted. Budget ongoing effort for upstream merges, Laravel upgrade compatibility, and security triage — work that is invisible until an upgrade deadline forces it. Without an assigned owner, this package will silently rot while remaining load-bearing for authorization.

Support. There is no vendor, no commercial support, and no community of dependents to lean on. Documentation is effectively whatever upstream provides, which may not match the fork's behavior. Incident response depends entirely on internal engineers reading the source.

Scaling. Authorization checks are frequent and often in hot paths. Bouncer's caching helps, but the operational burden shifts to cache invalidation: role changes must trigger Bouncer::refresh() (or equivalent) or users retain stale permissions until TTL expiry. In multi-tenant deployments, scope correctness becomes a scaling concern as the number of scopes grows; verify query patterns and indexes on the assignment and entity tables under realistic tenant counts.

Failure modes.

• Bitbucket repository deleted, renamed, or made private → CI builds fail with no upstream fallback.
• CI credentials expire or are rotated without updating the pipeline → intermittent, confusing build failures.
• Stale ability cache after role changes → users with revoked permissions retaining access; the highest-severity failure mode for this package class.
• Gate before callback conflicts with existing global authorization logic → silent policy bypass.
• Migration collisions or ordering issues on existing databases → deployment failure or partial schema state.
• Framework upgrade breaks Gate internals → authorization fails open or closed depending on the code path; must be tested explicitly.

Ramp-up. Engineers familiar with upstream Bouncer transfer quickly; engineers who know Spatie or native policies face a modest learning curve around the allow/assign/scope API and the cache model. Plan for a short internal knowledge session and an authorization-matrix test suite as the durable onboarding artifact — the tests, not the docs, will be the reliable specification.