Sentinel Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require winex/sentinel and execute php artisan sentinel:install followed by php artisan migrate. This sets up the core database tables for license management.

2. Filament Integration Register the SentinelProvider in your Filament panel configuration:

   public function panel(Panel $panel): Panel {
       return $panel
           ->requiresTenantSubscription()
           ->tenantBillingProvider(new SentinelProvider());
   }
   

3. First Use Case Add the SentinelPage to your Filament panel:

   ->pages([
       SentinelPage::class,
   ]);
   

   This immediately exposes a dashboard for managing licenses, trials, and billing.

Where to Look First

• Migrations: Inspect database/migrations/ for schema changes (e.g., licenses, subscriptions).
• Filament Page: Review Filament/Pages/SentinelPage.php for UI components and logic.
• Service Provider: Check SentinelProvider.php for core integration hooks.

Implementation Patterns

Core Workflows

1. License Management

   • Validation: Use Sentinel::validateLicense($licenseKey) to check license validity.
   • Activation: Call Sentinel::activateLicense($licenseKey, $user) to bind a license to a tenant/user.
   • Expiry: Automatically handle trial periods via Sentinel::checkTrialExpiry($user).

2. Billing Integration

   • Plan Configuration: Define plans in .env (e.g., MONTHLY_PLAN=30) and fetch them via:

     $monthlyPlan = config('sentinel.plans.monthly');
     

   • Subscription Events: Listen for tenant.subscription.created or tenant.subscription.cancelled events to trigger actions.

3. Filament-Specific Patterns

   • Tenant Subscription Check:

     if (auth()->user()->tenant->isSubscribed()) {
         // Grant access
     }
     

   • Dynamic UI: Use SentinelPage to display subscription status, upgrade buttons, and billing history.

4. API Endpoints

   • Expose license validation via a route:

     Route::post('/validate-license', [SentinelController::class, 'validate']);
     

Integration Tips

• Filament Policies: Extend SentinelPolicy to restrict access to resources based on subscription status.
• Webhooks: Integrate with Stripe/Paddle by extending SentinelServiceProvider and overriding handleWebhook().
• Localization: Override language strings in resources/lang/vendor/sentinel.

Gotchas and Tips

Pitfalls

1. Migration Timestamps

   • The sentinel:install command hardcodes the migration timestamp. If you modify migrations later, run:

     php artisan migrate:fresh --env=local
     

     to avoid conflicts.

2. Plan Configuration

   • .env values (MONTHLY_PLAN, ANNUAL_PLAN) must be integers. Non-numeric values will throw InvalidArgumentException.

3. Filament Tenant Sync

   • Ensure tenantBillingProvider is set before requiresTenantSubscription() in your panel configuration. Order matters.

4. License Key Format

   • The package expects keys in UUID format. Custom formats may require extending LicenseValidator.

Debugging

• Webhook Failures: Check logs/laravel.log for SentinelWebhook events. Enable debug mode:

  SENTINEL_DEBUG=true
  

• Database Issues: Use php artisan sentinel:prune to clean up expired trials/licenses (runs daily by default).

Extension Points

1. Custom Validators Override Winex\Sentinel\Contracts\LicenseValidator to add logic (e.g., domain validation):

   public function validate($licenseKey, $tenant) {
       // Custom logic
       return $this->validator->passes();
   }
   

2. Subscription Logic Extend Winex\Sentinel\Services\SubscriptionService to modify trial periods or pricing:

   public function calculateTrialDays(): int {
       return 14; // Override default
   }
   

3. Filament Widgets Add custom widgets to SentinelPage by publishing views:

   php artisan vendor:publish --tag=sentinel-views
   

   Then extend resources/views/vendor/sentinel/.

4. Multi-Tenant Support For multi-tenant setups, bind the license to the tenant model:

   Sentinel::activateLicense($key, auth()->user()->tenant);