Event Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require chill-project/event
   

   Publish the migration and config files:

   php artisan vendor:publish --provider="ChillProject\Event\EventServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="ChillProject\Event\EventServiceProvider" --tag="config"
   

   Run the migrations:

   php artisan migrate
   

2. First Use Case: Creating an Event Define an event in your database or via a seeder:

   use ChillProject\Event\Models\Event;
   
   $event = Event::create([
       'title' => 'Summer Hackathon',
       'description' => 'Join us for a weekend of coding!',
       'start_at' => now()->addDays(7),
       'end_at' => now()->addDays(8),
       'max_participants' => 50,
   ]);
   

3. Registering a User to an Event Use the register() method on the event model:

   $user = auth()->user();
   $event->register($user);
   

4. Checking Participation Verify if a user is registered:

   if ($event->isRegistered($user)) {
       // User is registered
   }
   

Implementation Patterns

Core Workflows

1. Event Management

   • CRUD Operations: Use Eloquent methods (create, update, find, etc.) on the Event model.
   • Event States: Leverage the status field (e.g., draft, published, cancelled) to control visibility and participation.

     $event->publish(); // Manually set status to 'published'
     

2. Participation Handling

   • Bulk Registration: Register multiple users at once:

     $event->registerMany([$user1, $user2, $user3]);
     

   • Cancellation: Allow users to unregister:

     $event->unregister($user);
     

3. Event Validation

   • Use Laravel’s validation rules to enforce constraints (e.g., max_participants):

     use Illuminate\Support\Facades\Validator;
     
     $validator = Validator::make($eventData, [
         'max_participants' => 'integer|min:1',
         'start_at' => 'required|date|after:today',
     ]);
     

4. Event Listeners and Observers

   • Extend functionality with observers (e.g., send notifications when a user registers):

     // app/Observers/EventObserver.php
     class EventObserver {
         public function registered($event) {
             Notification::send($event->user, new EventRegistered($event));
         }
     }
     

   • Register the observer in EventServiceProvider:

     Event::observe(EventObserver::class);
     

5. API Integration

   • Expose endpoints for event participation:

     // routes/api.php
     Route::post('/events/{event}/register', [EventController::class, 'register']);
     

   • Example controller:

     public function register(Event $event) {
         $event->register(auth()->user());
         return response()->json(['message' => 'Registered successfully']);
     }
     

6. Custom Event Types

   • Extend the Event model to support custom fields (e.g., virtual, location):

     class CustomEvent extends Event {
         protected $casts = [
             'is_virtual' => 'boolean',
             'location' => 'string',
         ];
     }
     

Gotchas and Tips

Pitfalls

1. Participation Limits

   • Ensure max_participants is validated before registration to avoid database constraint errors. Override the register() method if custom logic is needed:

     public function register(User $user) {
         if ($this->participants()->count() >= $this->max_participants) {
             throw new \Exception("Event is full.");
         }
         $this->participants()->attach($user);
     }
     

2. Time Zone Handling

   • Store start_at and end_at in UTC and convert to user time zones when displaying:

     $event->start_at->setTimezone($user->timezone);
     

3. Observer Conflicts

   • If using multiple packages with observers, ensure namespacing avoids collisions. Prefix observer classes (e.g., App\Observers\EventObserver).

4. Migration Conflicts

   • If extending the events table, run php artisan migrate:fresh cautiously to avoid data loss. Backup first.

5. Soft Deletes

   • The Event model uses soft deletes by default. Use withTrashed() or forceDelete() explicitly if needed:

     Event::withTrashed()->where('title', 'Hackathon')->get();
     

Debugging Tips

1. Participation Queries

   • Debug participation counts with:

     dd($event->participants()->count());
     

2. Event Status Logic

   • Add a scope to filter events by status:

     public function scopePublished($query) {
         return $query->where('status', 'published');
     }
     

     Usage:

     Event::published()->get();
     

3. Logging Registrations

   • Log registration events for auditing:

     \Log::info("User {$user->id} registered for event {$event->id}");
     

Extension Points

1. Custom Participation Rules

   • Override the canRegister() method to add logic (e.g., age restrictions):

     public function canRegister(User $user) {
         return $user->age >= 18 && parent::canRegister($user);
     }
     

2. Event Categories/Tags

   • Add a many-to-many relationship with a Category model:

     public function categories() {
         return $this->belongsToMany(Category::class);
     }
     

3. Webhook Notifications

   • Trigger webhooks on event updates (e.g., using laravel-webhooks):

     Event::updated(function ($event) {
         \Webhook::send('event_updated', $event);
     });
     

4. Recurring Events

   • Extend the model to support recurrence rules (e.g., using spatie/laravel-calendar):

     public function occurrences() {
         return (new RecurrenceRule($this->recurrence_rule))
             ->occurrences($this->start_at, $this->end_at);
     }