User Consent Laravel Package

Getting Started

Minimal Steps

1. Install the Package:

   composer require visualbuilder/user-consent:^5.0
   

   Ensure your composer.json locks to compatible Filament (5.x) and Laravel (11.x/12.x) versions.

2. Publish Assets: Run migrations and config:

   php artisan vendor:publish --tag="user-consent-migrations"
   php artisan vendor:publish --tag="user-consent-config"
   php artisan migrate
   

   Optionally publish views for customization:

   php artisan vendor:publish --tag="user-consent-views"
   

3. Configure Consent Options: Edit config/user-consent.php to define consent types (e.g., marketing, analytics):

   return [
       'options' => [
           'marketing_emails' => [
               'label' => 'Marketing Emails',
               'description' => 'Receive promotional emails.',
               'required' => false,
           ],
           'analytics_tracking' => [
               'label' => 'Analytics Tracking',
               'description' => 'Allow tracking of your usage.',
               'required' => true,
           ],
       ],
   ];
   

4. Integrate with Filament Registration: Extend Filament’s registration form to include consent fields. Example in a custom Registration class:

   use VisualBuilder\UserConsent\Concerns\HandlesUserConsent;
   
   class CustomRegistration extends Filament\Panels\Registration
   {
       use HandlesUserConsent;
   }
   

5. Test the Flow:

   • Register a new user to trigger the consent form.
   • Verify the consent record is saved in the consents table.
   • Check the user’s email for a copy of their consents.

Implementation Patterns

Core Workflows

1. Consent Collection During Registration

• Pattern: Use the HandlesUserConsent trait in Filament’s Registration class to auto-attach consent fields.
• Example:

  // app/Filament/Panels/CustomRegistration.php
  use VisualBuilder\UserConsent\Concerns\HandlesUserConsent;
  
  class CustomRegistration extends Filament\Panels\Registration
  {
      use HandlesUserConsent;
  
      protected function getConsentOptions(): array
      {
          return config('user-consent.options');
      }
  }
  

• Tip: Override getConsentOptions() to dynamically fetch options from a database if needed.

2. Admin Panel for Consent Management

• Pattern: Leverage Filament’s resource system to create a Consent resource.
• Example:

  php artisan make:filament-resource Consent
  

  Then extend the resource to query consents:

  // app/Filament/Resources/ConsentResource.php
  public static function getRelations(): array
  {
      return [
          'user' => UserResource::getEloquentQuery(),
      ];
  }
  

• Integration: Link to the "My Consents" page in the user’s profile:

  // In a Filament UserResource
  public static function getPages(): array
  {
      return [
          'consents' => Pages\ConsentsPage::route('/consents'),
      ];
  }
  

3. Retroactive Consent Requests

• Pattern: Use Filament’s Action to trigger consent updates for existing users.
• Example:

  // In a Filament UserResource Table
  public static function getTableActions(): array
  {
      return [
          Action::make('requestConsent')
              ->label('Request Consent Update')
              ->action(function (User $user) {
                  // Trigger email or redirect to consent form
                  return redirect()->route('filament.admin.pages.user-consents.show', ['user' => $user]);
              }),
      ];
  }
  

4. Email Notifications

• Pattern: Customize the email template published by the package.
• Steps:
  1. Publish views:

     php artisan vendor:publish --tag="user-consent-views"
     

  2. Override the email template at resources/views/vendor/user-consent/emails/consent-notification.blade.php.
  3. Extend the ConsentNotification class to modify logic:

     // app/Providers/UserConsentServiceProvider.php
     use VisualBuilder\UserConsent\Mail\ConsentNotification;
     
     class UserConsentServiceProvider extends ServiceProvider
     {
         public function boot(): void
         {
             ConsentNotification::macro('customize', function ($user) {
                 $this->subject("Updated Consents for {$user->name}");
                 // Add custom logic
             });
         }
     }
     

5. Dynamic Consent Options

• Pattern: Fetch consent options from a database table instead of config.
• Example:

  // app/Models/ConsentOption.php
  class ConsentOption extends Model
  {
      protected $fillable = ['label', 'description', 'required'];
  }
  

  Then override getConsentOptions():

  protected function getConsentOptions(): array
  {
      return ConsentOption::all()->pluck('label', 'key')->toArray();
  }
  

Integration Tips

Filament Panel-Specific Consents

• Use middleware to scope consents to a specific Filament panel:

  // app/Providers/Filament/AdminPanelProvider.php
  public function panel(Panel $panel): Panel
  {
      $panel
          ->middleware([
              \VisualBuilder\UserConsent\Http\Middleware\CheckPanelConsent::class,
          ])
          ->consentOptions(function () {
              return config('user-consent.options.panel_'.request()->panel);
          });
  }
  

Conditional Consent Requirements

• Dynamically set required based on user roles:

  protected function getConsentOptions(): array
  {
      $options = config('user-consent.options');
      if (auth()->user()->isAdmin()) {
          foreach ($options as &$option) {
              $option['required'] = false;
          }
      }
      return $options;
  }
  

Bulk Consent Updates

• Use Laravel queues to process bulk consent updates asynchronously:

  // Dispatch a job to update consents for a user batch
  UpdateConsentsJob::dispatch($userIds, $newOptions);
  

  Then create a job:

  // app/Jobs/UpdateConsentsJob.php
  public function handle()
  {
      foreach ($this->userIds as $userId) {
          $user = User::find($userId);
          $user->updateConsents($this->newOptions);
      }
  }
  

Localization

• Extend the package’s language lines for multilingual support:

  // config/app.php
  'locale' => 'fr',
  

  Then publish and override language files:

  php artisan vendor:publish --tag="user-consent-lang"
  

  Edit resources/lang/fr/user-consent.php.

Gotchas and Tips

Pitfalls

1. Filament Version Mismatch

• Issue: Installing 5.x with Filament 4.x or vice versa will break the package.
• Fix: Pin versions in composer.json:

  "require": {
      "filament/filament": "^5.0",
      "visualbuilder/user-consent": "^5.0"
  }
  

2. Missing hasConsents() Method

• Issue: If the User model lacks the hasConsents() method, consent checks fail.
• Fix: Add the trait to your User model:

  use VisualBuilder\UserConsent\Concerns\HasConsents;
  
  class User extends Authenticatable
  {
      use HasConsents;
  }
  

3. Email Notifications Failing

• Issue: Consent emails not sending due to queue misconfiguration.
• Debug:
  • Check failed_jobs table for queue failures.
  • Verify .env mail settings (e.g., MAIL_MAILER=smtp).
  • Test with a simple email job first:

    Mail::to($user)->send(new \App\Mail\TestMail());
    

4. Consent Form Not Rendering

• Issue: The consent form doesn’t appear in Filament’s registration.
• Debug:
  • Ensure HandlesUserConsent is used in the Registration class.
  • Check for JavaScript errors in Filament’s console (Livewire dependencies).
  • Verify the consent_options config key exists and is an array.

5. Database Schema Conflicts

• Issue: Migration fails due to existing consents table.
• Fix: Backup and drop the table before re-running migrations:

  php artisan