Syncacc Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package> and publish the package assets: php artisan vendor:publish --tag=acl-config and --tag=acl-migrations (run php artisan migrate afterwards).
• Look first at config/acl.php (model/entity bindings, table names, cache settings) and the role/permission entities under src/Models (or src/Entities if the package uses Doctrine). The AclRole class is where the v3.0.1 change lands.
• Bind the package contracts in a service provider if you need custom models: AclRoleContract, AclPermissionContract, and the user-trait/has-roles interface.
• First use case: seed a role and a permission, attach them, and gate a route.

$role = AclRole::create(['id' => 'admin', 'name' => 'Administrator']); // note: explicit id required since v3.0.1
$permission = AclPermission::create(['id' => 'posts.edit', 'name' => 'Edit posts']);
$role->permissions()->attach($permission->id);
$user->assignRole('admin');

Gate::allows('posts.edit'); // or $user->can('posts.edit')

• For a quick smoke test, use php artisan tinker and verify $user->hasRole('admin') and $user->can('posts.edit') before wiring middleware or Blade directives.

Implementation Patterns

• Explicit identifiers for roles. Since v3.0.1 the AclRole entity no longer carries #[ORM\GeneratedValue], so role IDs are application-assigned. Treat the role ID as a stable slug (admin, editor, billing-manager) rather than an auto-increment integer, and use it everywhere: seeders, assignRole(), config-driven default roles, and tests.
• Seeder-driven role catalogue. Keep a single RolePermissionSeeder that upserts roles and permissions by ID, so re-running is idempotent and never depends on database-generated IDs:

foreach (config('acl.roles') as $id => $definition) {
    $role = AclRole::updateOrCreate(['id' => $id], ['name' => $definition['name']]);
    $role->permissions()->sync($definition['permissions']);
}

• Config as the source of truth. Define roles/permissions in a config array and have the seeder consume it; this avoids hard-coded IDs sprinkled through migrations and tests, which is especially important now that IDs are manual.
• Gate/Policy integration. Map permissions to Laravel gates in a AuthServiceProvider loop, then use standard $user->can() / @can in Blade and can: middleware on routes. This keeps the package out of your controllers.
• Caching the permission map. The package typically resolves a user's permission set per request. Cache the role→permission mapping (Cache::rememberForever('acl.map', ...)) and flush it on role/permission writes via model events or an observer.
• Multi-guard support. If you have admin and customer guards, resolve the correct user model per guard and confirm the package's pivot table can distinguish them; otherwise use separate role sets per guard.
• Testing. Use a trait/factory helper that creates a user, assigns a role by ID, and asserts assertTrue($user->can('...')). Seed the role catalogue in setUp or via RefreshDatabase + seeder so tests never rely on generated IDs.

Gotchas and Tips

• Breaking in v3.0.1: no auto-generated AclRole id. Creating a role without an explicit id will now fail (NOT NULL / identifier required) instead of silently getting an auto-increment value. Audit every AclRole::create([...]), factory, and seeder call to supply an ID. If you were relying on $role->id being numeric, switch to string slugs.
• Existing data migration. Rows created before the upgrade already have numeric IDs. If you want slug IDs, write a migration that maps old IDs to new string identifiers and updates the role-user pivot table in the same transaction; otherwise keep the existing numeric IDs as your manual values and don't mix conventions.
• Doctrine vs Eloquent. #[ORM\GeneratedValue] is a Doctrine ORM attribute. If your app is Eloquent-based, the change is invisible to you but signals the entity layer is Doctrine-first — check which mapper/entity manager the package expects before overriding models.
• Cache staleness. Manual IDs plus cached permission maps means a renamed or re-seeded role can leave stale entries. Always bust the ACL cache after seeding, and prefer updateOrCreate over create in seeders to avoid duplicate-key exceptions on redeploy.
• Duplicate-key errors on redeploy. With application-assigned IDs, a second create() for the same role ID throws instead of creating a new row. Use upserts, or guard with firstOrCreate.
• Config quirks. Verify acl.models.role points at your class (not the vendor default) if you extended AclRole; a stale binding is the most common cause of "role not found" after an upgrade.
• Extension points. Override the role/permission models and register them via the config binding, and hook the package's events (role assigned / permission granted) for audit logging rather than editing vendor code.
• Debugging tip. When can() returns false unexpectedly, dump the resolved permission map (app(AclManager::class)->getPermissions($user)) before suspecting the gate — missing pivot rows after a manual-ID migration are the usual culprit.