Sentry Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cartalyst/sentry
   

   (Note: As of Laravel 8+, consider migrating to Laravel's built-in auth system or spatie/laravel-permission for authorization.)

2. Publish Config:

   php artisan vendor:publish --provider="Cartalyst\Sentry\SentryServiceProvider"
   

   Edit config/sentry.php to match your database schema (default tables: users, groups_users, groups, permissions).

3. First Use Case:

   • Authenticate a User:

     use Cartalyst\Sentry\Sentry;
     
     $user = Sentry::authenticate(['email' => 'user@example.com', 'password' => 'password']);
     

   • Check Authorization:

     if (Sentry::check()) {
         if (Sentry::getUser()->hasAccess(['create_post'])) {
             // Grant access
         }
     }
     

4. Key Files:

   • config/sentry.php: Configuration (drivers, table names, etc.).
   • app/Providers/SentryServiceProvider.php: Service binding (if customized).
   • app/Providers/AuthServiceProvider.php: Override boot() to integrate with Laravel’s auth if needed.

Implementation Patterns

Core Workflows

1. User Management:

   • Create User:

     $user = Sentry::createUser(['email' => 'user@example.com', 'password' => 'password']);
     

   • Update User:

     Sentry::getUser()->setFirstName('John')->save();
     

   • Delete User:

     Sentry::getUser()->delete();
     

2. Group & Permission Handling:

   • Assign Group to User:

     $group = Sentry::findGroupByName('Admins');
     Sentry::getUser()->addGroup($group);
     

   • Check Group Membership:

     if (Sentry::getUser()->inGroup('Admins')) { ... }
     

   • Grant Permissions:

     $group->addPermission('edit_posts');
     

3. Authentication:

   • Login/Logout:

     Sentry::authenticate($credentials);
     Sentry::logout();
     

   • Remember Me:

     Sentry::authenticate($credentials, true); // Persistent session
     

4. Middleware Integration:

   • Use Sentry::check() in middleware to restrict routes:

     public function handle($request, Closure $next) {
         if (!Sentry::check()) return redirect('login');
         return $next($request);
     }
     

5. Custom Guards:

   • Bind Sentry to Laravel’s auth system in AuthServiceProvider:

     public function boot() {
         $this->app['auth']->extend('sentry', function($app) {
             return new SentryGuard(Sentry::getUserProvider());
         });
     }
     

Integration Tips

• Laravel 5.5+: Use Auth::guard('sentry')->user() for consistency.
• APIs: Combine with laravel/passport for token-based auth:

  $token = Sentry::getUser()->createToken('API Token')->accessToken;
  

• Events: Listen to sentry.user.created or sentry.login via Laravel’s event system.
• Testing: Use Sentry::getUserProvider() to mock users in tests:

  $this->actingAs(Sentry::findUserById(1));
  

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The package is deprecated (last update: 2017). Avoid for new projects; migrate to Laravel’s auth + spatie/laravel-permission or zizaco/entrust.

2. Database Schema Conflicts:

   • Default tables (users, groups_users) may clash with Laravel’s migrations. Override in config/sentry.php:

     'table_users' => 'custom_users',
     'table_groups_users' => 'custom_groups_users',
     

3. Session Handling:

   • Sentry uses its own session driver. For Laravel’s session, ensure config/session.php matches Sentry’s storage (e.g., database or file).

4. Password Hashing:

   • Sentry uses bcrypt by default. If using Laravel’s Hash facade, ensure consistency:

     Sentry::hashPassword($password); // Uses Sentry’s hasher
     

5. Permission Caching:

   • Permissions are cached. Clear cache after changes:

     Sentry::getUser()->permissions()->flushCache();
     

Debugging

• Enable Logging:

  Sentry::setLogLevel(\Monolog\Logger::DEBUG);
  

• Common Issues:
  • "User not found": Verify config/sentry.php table names and users table structure.
  • Permission errors: Check groups_permissions table or run php artisan sentry:permissions:list.
  • Session timeout: Extend in config/sentry.php:

    'remember' => 1209600, // 2 weeks in seconds
    

Extension Points

1. Custom User Model:

   • Extend Cartalyst\Sentry\Users\Eloquent\User:

     class CustomUser extends User {
         public function roles() { return $this->belongsToMany(Role::class); }
     }
     

   • Bind in SentryServiceProvider:

     $this->app->bind('sentry.user.model', function() {
         return new CustomUser();
     });
     

2. Custom Drivers:

   • Implement Cartalyst\Sentry\Drivers\DriverInterface for non-database auth (e.g., OAuth).

3. Events:

   • Extend core events (e.g., sentry.user.created) in EventServiceProvider:

     protected $listen = [
         'sentry.user.created' => ['App\Listeners\SendWelcomeEmail'],
     ];
     

4. API Tokens:

   • For Laravel Passport, override SentryUserProvider to return HasApiTokens:

     class SentryUserProvider extends \Cartalyst\Sentry\Users\Eloquent\UserProvider {
         public function retrieveByToken($identifier, $token) {
             return parent::retrieveByToken($identifier, $token)->first();
         }
     }