Centaur Laravel Package

Getting Started

• Install: composer require srlabs/centaur. Add Centaur\CentaurServiceProvider::class to config/app.php (or rely on package discovery on newer Laravel). Publish the config and assets:

  php artisan vendor:publish --provider="Centaur\CentaurServiceProvider"
  

  Then run the package migrations (php artisan migrate) and set up mail/queue for activation and reminder emails.
• Where to look first:
  1. config/centaur.php — this is the control panel. It maps route prefixes, middleware groups, and which controller class handles auth, registration, profile, users, roles, permissions, throttling, and reminders. If something behaves unexpectedly, it is almost always here.
  2. routes/ (published or package routes) — see the exact URIs, names, and middleware for every auth and admin action.
  3. src/Http/Controllers/ — the default controller behaviour you will extend or override.
  4. src/User.php (the Centaur\User model) and the Sentinel migrations — the schema you will live with.
• First use case: registration → activation → login → role/permission-gated routes.
  1. Configure mail so activation emails actually send (or disable email activation in config for local work).
  2. Seed a superuser / admin role + permissions, then assign it to your first user via php artisan tinker and Sentinel::findUserById(1)->roles()->attach($role).
  3. Protect application routes with the Sentinel middleware (auth, role, permission) that Centaur registers, rather than Laravel's default auth middleware.
  4. Use Sentinel::check(), Sentinel::getUser(), and $user->hasAccess('slug') in views/controllers.

If an centaur:install command is present in your version, prefer it — it publishes config, migrations, views and routes in one step and avoids hunting for publish tags.

Implementation Patterns

Extend the User model rather than editing the vendor one.

namespace App;

use Centaur\User as CentaurUser;

class User extends CentaurUser
{
    protected $fillable = ['first_name', 'last_name', 'email', 'password', 'permissions'];
}

Point config/centaur.php and Sentinel's config (config/cartalyst.sentinel.php, users.model) at App\User. All Sentinel relations (roles, activations, persistences, throttling) are inherited.

Override controllers through config, not by editing vendor files. Extend a Centaur controller, override only the methods you need, then swap the class name in config/centaur.php:

'controllers' => [
    'registration' => App\Http\Controllers\Auth\RegistrationController::class,
],

Keep constructor signatures compatible — Centaur controllers often inject Sentinel-related dependencies; changing them breaks container resolution.

Customize routes by disabling the package defaults. Most configs let you set a routes toggle or prefix. Publish/define your own routes with the same controller methods when you need custom URIs, throttles, or middleware composition. Keep route names stable if your views use route('login') etc.

Use Sentinel directly for domain logic. Centaur gives you scaffolding; Sentinel gives you the API. Typical day-to-day calls:

Sentinel::register($credentials);
Sentinel::registerAndActivate($credentials);
Sentinel::authenticate($credentials, $remember);
Sentinel::check(); Sentinel::getUser();
$user->hasAccess('posts.edit');
$user->hasAnyAccess(['posts.edit', 'posts.delete']);
$user->roles()->attach($roleId);
Sentinel::findRoleBySlug('admin')->users()->attach($userId);

Gate features with the right middleware, in the right order. Authenticate first, then role/permission. Compose per route:

Route::group(['middleware' => ['web', 'sentinel.auth']], function () {
    Route::get('/dashboard', ...);
});
Route::group(['middleware' => ['web', 'sentinel.auth', 'sentinel.permission:admin.access']], function () { ... });

Middleware aliases come from the provider/config — verify the actual names in Kernel.php or the package docs for your version.

Hook into events for side effects. Use Centaur/Sentinel events (registration, activation, login, logout) to attach your own listeners — send onboarding mail, create profiles, log audits. Do not put this logic inside overridden controllers unless it is controller-specific.

Blade integration. Check access in views via Sentinel::check() and Sentinel::getUser()->hasAccess('slug'), or add a helper/blade directive wrapping the same. Cache the user in the view composer if you render dozens of permission checks.

Admin UI pattern. Centaur ships user/role/permission management screens. Treat them as an internal admin scaffold: publish views, restyle to your app, and audit the controller actions (especially user deletion and role reassignment) before exposing them. Lock the admin routes down with a superuser role in config.

Testing. Because everything routes through Sentinel, use Sentinel::authenticate($user) or the package's test helpers (if provided) to log in inside tests; do not rely on $this->actingAs() unless your App\User also implements Laravel's Authenticatable guard contract. Use RefreshDatabase and seed roles/permissions per test.

Gotchas and Tips

• Sentinel is not Laravel's Auth guard. Auth::user() will be null; use Sentinel::getUser(). The auth middleware and Sentinel's auth middleware are different. Mixing them causes "logged in but unauthorized" bugs that are painful to trace.
• Do not run the package migrations on a database that already has users. Rename or guard the migration, or adopt Centaur from a fresh schema. The users, activations, reminders, persistences, throttle, roles, role_users, permissions tables are Sentinel's fixed schema.
• Activation flow is mail-driven. Local dev silently fails if mail is misconfigured. Either set MAIL_MAILER=log, override registerAndActivate in your controller, or toggle activation off in config. Test the full register → click activation → login path before shipping.
• Config caching bites. After editing config/centaur.php, run php artisan config:clear (and route:clear if routes were published). Changes to controller bindings won't take effect with a stale cache.
• Route/model binding and controller overrides. If you override a controller method that relied on implicit binding or a package middleware, you can accidentally drop authorization checks. Copy the original method body rather than rewriting from scratch.
• Views are published, not inherited. Once published into resources/views/vendor/centaur, updates to the package won't reach them. Keep a changelog note and diff on upgrades.
• Throttling surprises test suites. Repeated login attempts in feature tests hit Sentinel's throttle table. Clear it between tests or configure higher limits in test env.
• Permissions caching. Sentinel caches permissions on the user object; after attaching/detaching roles or permissions in the same request, re-fetch the user (Sentinel::findUserById) or call the appropriate refresh method, otherwise hasAccess returns stale results.
• Remember-me and persistences. Session/persistence behaviour is Sentinel-specific. If you use a custom session driver or token auth, verify the persistences table is being written and cleared correctly.
• Deleting users leaves pivot rows. Wrap user deletion in a transaction and detach roles/persistences (or use model events) before deleting, or enable soft deletes consistently across Sentinel relations.
• Opinionated defaults are a feature and a trap. Bootstrap-flavoured views, fixed route names, and an admin UI you may not want. Budget time to override controllers, routes, and views — not to fight the package's assumptions.
• Maintenance risk. Sentinel itself is legacy-leaning and the package is small (59 stars). Pin versions, watch Laravel/PHP compatibility, and consider whether spatie/laravel-permission plus Laravel's native auth would be a lower-friction long-term fit if you don't need Sentinel's activation/reminder/throttle stack.
• Extension points to remember: config controller bindings, Sentinel events/listeners, your App\User overrides, published views/routes, and Sentinel's own config. Almost any behaviour change belongs in one of those five places — not in vendor/.