Biz Role Bundle Laravel Package

Getting Started

tourze/biz-role-bundle is the role/RBAC bundle from the Tourze package family — business-role assignment and role-based checks, released in lockstep with the rest of the tourze/* ecosystem. Release 1.0.2 is a patch bump from 1.0.1; the only published note is the compare link, which is Tourze's usual signature for a dependency-lockstep/no-API-change release. There is no prior assessment to amend, so treat this as a first-look evaluation rather than an upgrade decision.

First steps, in order:

1. composer require tourze/biz-role-bundle and immediately read the resolved constraints in composer.json (PHP version, illuminate/* range, and any symfony/* or doctrine/* requirements). Because Tourze releases move together, note which other tourze/* packages get pulled in transitively — that set, not this package alone, defines your upgrade surface.
2. Check whether a Laravel service provider is auto-discovered (php artisan about / vendor/tourze/biz-role-bundle/composer.json → extra.laravel.providers). If there is none, the bundle is Symfony-first and you will be wiring it manually.
3. Look at the package root before writing any code: README, src/, config/, migrations/ or Resources/, and any *Interface files. In this ecosystem the interfaces are the contract — role and role-assignment are usually expressed as interfaces with concrete implementations you are expected to bind or extend.
4. Confirm the persistence layer. If the entities are Doctrine-annotated rather than Eloquent models, stop and decide: adopt the package's repositories as-is, or wrap the role logic in your own Eloquent model and use the package only for role semantics.

First use case worth proving end-to-end: seed two roles, attach one to a user, and assert hasRole('admin') returns true. If that loop works without you writing a custom repository, the package fits your app; if it does not, that is the signal to evaluate before building on it.

Implementation Patterns

Bind interfaces at the container level. Tourze packages typically ship interfaces plus default implementations. Register your binding in a RoleServiceProvider rather than sprinkling new calls; that keeps the swap to your own implementation a one-line change when the package's assumptions diverge from your schema.

Wrap role checks behind an authorization seam. Do not let controllers call the package directly. Expose hasRole / hasPermission through a small AccessService or a Laravel Gate::before hook, so route middleware, policies, and Blade directives all resolve through one path. When the package changes, you patch one class.

Route protection via middleware. A role:admin,editor middleware that resolves the authenticated user, delegates to your seam, and aborts 403 is the durable pattern. Keep the middleware dumb — parameter parsing only, decision in the service.

Seeding and fixtures. Put role definitions in a dedicated seeder or a config-driven roles.php map (name => permissions), and have the seeder idempotently firstOrCreate. Hard-coded role names scattered across tests are the most common source of drift in RBAC code.

Per-request caching. Role lookups are cheap but frequent — sidebar rendering, every policy check, every middleware. Memoize the role collection on the user instance for the request lifetime, and flush explicitly after any assignment in the same request.

Testing. Use RefreshDatabase plus a factory that creates users with attached roles. Assert negative cases (user without role gets 403) alongside the positive one; role packages frequently return permissive defaults when a role is missing, and 1.0.x patch bumps are not the place to discover that.

Upgrade discipline. Pin to 1.0.* and diff 1.0.1...1.0.2 in the vendor tree (git diff on the extracted package, or composer update --dry-run to see what moved). Because Tourze bumps siblings in lockstep, a "patch" in this package can still shift a transitive dependency that another tourze/* package depends on.

Gotchas and Tips

• The 1.0.2 changelog is empty. "Full Changelog" with no prose is not evidence of no change. Diff the tag before upgrading in production; at minimum confirm only composer.json/lockstep version strings moved.
• Symfony-first assumptions. The -bundle suffix is a strong hint: configuration via bundle extension classes, Doctrine entities, and event-dispatcher integration that does not map cleanly onto Laravel's container or Eloquent. Budget discovery time for this; it is the single most likely reason the package does not drop in.
• No published config or migrations. If config/ and migrations/ exist but nothing is auto-published, run php artisan vendor:publish --provider="Tourze\..." and check the output. Silent absence of a published migration is a common cause of "table not found" on first use.
• Transitive version pinning. Tourze packages sometimes pin sibling packages to exact versions. Conflicts surface as composer why-not tourze/biz-role-bundle 1.0.2 — use that before assuming the package itself is at fault.
• Debugging role resolution. Log the resolved role set and the decision point (role=X, permission=Y, result=deny) at debug level in your seam, not inside vendor code. Vendor debugging gets lost on the next composer update.
• Extension points to prefer. Interfaces, the service provider binding, and any event/listener hooks the package dispatches. Avoid subclassing vendor concrete classes — that is the surface most likely to break in a 1.0.x patch.
• Version ceiling risk. At 1.0.x, treat every release as potentially behavioural until the compare diff says otherwise, and keep the upgrade behind your test suite rather than deploying it cold.