Laravel Google Calendar Laravel Package

Getting Started

1. Install the package via Composer: composer require spatie/laravel-google-calendar
2. Publish the config: php artisan vendor:publish --provider="Spatie\GoogleCalendar\GoogleCalendarServiceProvider"
3. Configure credentials in config/google-calendar.php:
   • For service account auth: place service-account-credentials.json (downloaded from Google Cloud Console) in storage/app/google-calendar/ and set default_auth_profile to 'service_account'
   • For user-based OAuth: use oauth-credentials.json and oauth-token.json (generated via Google’s PHP quickstart) and set GOOGLE_CALENDAR_AUTH_PROFILE=oauth in .env
4. Set your Google Calendar ID (found in Calendar Settings > “Integrate calendar”) in config/google-calendar.php or .env (GOOGLE_CALENDAR_ID)
5. First use case: create an event on-demand in a job or controller:

   use Spatie\GoogleCalendar\Event;
   $event = new Event;
   $event->name = 'Team Sync';
   $event->startDateTime = now()->addDay();
   $event->endDateTime = now()->addDay()->addHour();
   $event->save();
   

Implementation Patterns

• Bulk event creation: Use static Event::create([...]) for simplicity in seeders or batch imports.
• Storing event IDs: Save ->id to your database (e.g., google_calendar_id) for later sync/update/delete:

  $event = Event::create([...]);
  $booking->google_event_id = $event->id;
  $booking->save();
  

• Customizing queries: Filter by date range and apply Google Calendar query params:

  $events = Event::get(
      startDateTime: now()->startOfWeek(),
      endDateTime: now()->endOfWeek(),
      queryParameters: ['singleEvents' => true, 'orderBy' => 'startTime']
  );
  

• Attendees & integration: Use addAttendee() to invite users, and addMeetLink() to auto-generate a Google Meet link for virtual meetings.
• Full-day events: Use startDate/endDate (not *DateTime) for multi-day or recurring date boundaries (e.g., conferences, holidays).
• Dynamic calendar selection: Override default calendar_id per call: Event::get(calendarId: 'xyz@group.calendar.google.com')

Gotchas and Tips

• Recurring events are read-only: This package cannot create or modify recurrences reliably. Use Event::find($id) and ignore change attempts to recurring event series—Google’s API treats them differently.
• Timezone matters: startDateTime/endDateTime must be Carbon instances with timezone; set app default via config/app.php#timezone or pass explicit tz: Carbon::now('UTC')->addHour().
• OAuth token refresh: OAuth tokens expire. Use php artisan google-calendar:refresh-token (if using spatie/laravel-google-calendar v3.6+) or manually refresh. Service accounts skip this step.
• Service account permissions: Remember to add the service account email (e.g., myapp@project.iam.gserviceaccount.com) as a sharing editor on the target calendar in Google Calendar UI.
• Debugging API errors: Enable exceptions and inspect them—Google’s API returns JSON error details. Wrap save()/get() in try/catch and log getErrors() or getMessage().
• Hidden properties: source, colorId, location, and visibility are supported but not obvious—check Event::$availableProperties or source code for full list.
• ** Laravel 13 compatibility**: As of v3.8.5, the package supports Laravel 13, but ensure no custom Carbon version constraints break the dependency.
• Type safety on PHP 8.4: The package now handles null typing in v3.8.4—update to avoid deprecation notices.