Permissions Admin Laravel Package

Getting Started

1. Install the package (composer require ...) and run any publish steps (php artisan vendor:publish --tag=...) if the package exposes config, migrations, or routes.
2. Look first at the package service provider and any routes/*.php files. As of 1.0.1, the package registers its routes behind the auth middleware, so route registration and middleware assignment are the primary integration points.
3. First use case: after installation, run php artisan route:list and confirm the package routes show auth middleware. Then visit one of those routes as a guest — you should be redirected to the login page — and again as an authenticated user to confirm normal behavior.

Implementation Patterns

• Authenticated-only routes by default. Since 1.0.1 the package applies auth to its routes. In day-to-day use, treat every package route as requiring a logged-in user. Wrap links, navigation items, and UI actions in @auth checks so users are not sent to a login redirect unexpectedly.
• Guard alignment. The default auth middleware uses your application’s default guard. If the package is used in an API or token-based context, configure the guard explicitly (for example auth:sanctum) by wrapping the package routes in your own middleware group or by overriding the package’s route registration if it exposes that option.
• Layered authorization. The package’s auth middleware only authenticates. Add policies, gates, or route-model binding checks for per-resource authorization. Do not rely on the package middleware alone for “can this user see this record?” decisions.
• Testing pattern. Use Laravel’s actingAs($user) for happy-path feature tests and assert guest requests redirect to /login. Keep a dedicated test that hits each package route unauthenticated — this is the regression test that 1.0.1 effectively introduced.
• Customization workflow. Prefer the package’s published config or route override hooks over editing vendor files. If middleware customization is not configurable, wrap the package routes in a route group in your own service provider or use a global middleware adjustment.

Gotchas and Tips

• 1.0.1 is a behavior change for unauthenticated consumers. Any existing integration that relied on package routes being publicly reachable — webhooks, health checks, callback endpoints, or embedded public pages — will now redirect guests to login. Audit those flows immediately after upgrading.
• Clear route caches after upgrading. Middleware changes are compiled into the route cache. Run php artisan route:clear and, in production, php artisan route:cache again. Stale caches can make the new auth middleware appear absent or partially applied.
• Guard mismatch is the most common failure. If your app uses multiple guards, auth may pick the wrong one and reject valid users. Check config/auth.php defaults and explicitly set the guard where needed.
• Debugging middleware. Use php artisan route:list --path=<package-prefix> -v to see exactly which middleware is attached. If guests are not redirected as expected, inspect the route’s middleware stack before assuming the package is at fault.
• Do not use withoutMiddleware as a fix. Disabling middleware in tests or controllers hides auth regressions and undermines the security fix in 1.0.1. Fix the guard or route grouping instead.
• Extension points to check. Published routes, config flags for middleware, and service-provider route macros are the safe customization surfaces. If none exist, open an issue requesting configurable middleware rather than patching vendor code.
• Upgrade note. Treat 1.0.1 as a security-hardening release. Pin the version in composer.json, review the diff if the package is public, and add the guest-redirect assertion to your test suite so future releases cannot silently remove route protection.