Calendar Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require blairpaul09/calendar
   

2. Publish config and migrations:

   php artisan vendor:publish --provider="Calendar\Providers\CalendarServiceProvider"
   php artisan migrate
   

3. Attach the trait to your User model:

   use Calendar\Models\Traits\InteractsWithCalendar;
   
   class User extends Authenticatable {
       use InteractsWithCalendar;
   }
   

First Use Case: Creating a Recurring Event

$user = User::find(1);
$event = CalendarEventBuilder::for($user)
    ->startAt(now()->format('Y-m-d'))
    ->endAt(now()->addDays(30)->format('Y-m-d'))
    ->time('09:00', '10:00')
    ->daily()
    ->title('Daily Standup')
    ->save();

Implementation Patterns

Common Workflows

1. Event Creation

• One-time events:

  CalendarEventBuilder::for($user)
      ->startAt(now()->format('Y-m-d'))
      ->time('14:00', '15:00')
      ->title('Team Lunch')
      ->save();
  

• Recurring events (weekly, monthly, yearly):

  CalendarEventBuilder::for($user)
      ->startAt(now()->format('Y-m-d'))
      ->endAt(now()->addYears(1)->format('Y-m-d'))
      ->time('08:00', '09:00')
      ->weekly()
      ->title('Weekly Sync')
      ->save();
  

2. Fetching Events

• User’s events:

  $user->events()->get();
  

• Events in a date range:

  $user->events()
      ->whereBetween('start_at', [$startDate, $endDate])
      ->get();
  

3. Reminders

• Configure reminders in config/calendar.php:

  'allow_reminder' => true,
  

• Attach reminders to events:

  CalendarEventBuilder::for($user)
      ->startAt(now()->format('Y-m-d'))
      ->time('10:00', '11:00')
      ->reminders([
          ['type' => 'minutes', 'nth' => 30],
          ['type' => 'hours', 'nth' => 1],
      ])
      ->title('Meeting')
      ->save();
  

4. Timezones

• Specify timezone for events:

  $timezone = 'America/New_York';
  $event = CalendarEventBuilder::for($user)
      ->startAt(now($timezone)->format('Y-m-d'))
      ->time('10:00', '11:00')
      ->title('Timezone Test')
      ->save();
  

5. Integration with Frontend

• Serialize events for frontend (e.g., FullCalendar):

  $events = $user->events()
      ->get()
      ->map(fn ($event) => [
          'title' => $event->title,
          'start' => $event->start_at->format('Y-m-d\TH:i:s'),
          'end' => $event->end_at->format('Y-m-d\TH:i:s'),
          'timezone' => $event->timezone,
      ]);
  

Gotchas and Tips

Pitfalls

1. Timezone Handling:

   • Events are stored in UTC by default. Ensure timezone is explicitly set during creation to avoid ambiguity.
   • Debug timezone issues with:

     $event->start_at->setTimezone('Asia/Manila')->format('Y-m-d H:i:s');
     

2. Recurrence Rules:

   • The package uses rlanvin/php-rrule for recurrence. Complex rules (e.g., "every 2nd Monday") may require manual RRULE string input:

     ->recurrenceRule('FREQ=WEEKLY;BYDAY=2SU')
     

   • Test recurrence logic locally before deploying to production.

3. Migration Conflicts:

   • If the calendar_events table already exists, migrations may fail. Backup your database before running php artisan migrate.

4. Reminder Limitations:

   • Reminders are stored as metadata but require custom logic to trigger (e.g., Laravel Queues or Jobs). The package does not include a reminder system out of the box.

5. Performance:

   • Fetching events for large date ranges (e.g., 1+ year) may impact performance. Use whereBetween with reasonable ranges:

     $user->events()
         ->whereBetween('start_at', [now()->startOfMonth(), now()->endOfMonth()])
         ->get();
     

Debugging Tips

• Log Event Data:

  \Log::info('Event data:', $event->toArray());
  

• Validate RRULE: Use the RRULE validator to test recurrence rules before implementation.

Extension Points

1. Custom Event Models:

   • Extend the CalendarEvent model to add fields:

     class CustomEvent extends CalendarEvent {
         protected $casts = [
             'custom_field' => 'string',
         ];
     }
     

   • Update the trait to use your model:

     use Calendar\Models\Traits\InteractsWithCalendar as InteractsWithCustomCalendar;
     

2. Add Event Categories/Tags:

   • Add a pivot table and modify the trait:

     // Migration
     Schema::create('event_categories', function (Blueprint $table) {
         $table->id();
         $table->foreignId('event_id')->constrained();
         $table->string('category');
         $table->timestamps();
     });
     
     // Trait extension
     public function categories() {
         return $this->hasMany(EventCategory::class);
     }
     

3. Sync with External Calendars:

   • Use Laravel Queues to export events to Google Calendar or iCal:

     $event->toIcs(); // Hypothetical method; may require custom implementation.
     

4. Override Default Timezone:

   • Set a default timezone in config/calendar.php:

     'default_timezone' => 'UTC',
     

   • Override per-event:

     ->timezone('Asia/Tokyo')
     

5. Soft Deletes:

   • Enable soft deletes for events:

     use Illuminate\Database\Eloquent\SoftDeletes;
     
     class User extends Authenticatable {
         use InteractsWithCalendar, SoftDeletes;
     }
     

   • Update migrations to add deleted_at column.