Using the Google Calendar API from your web site with PHP

This post is mainly to remind myself how to do this when I inevitably forget in a year or two and want to integrate data from a Google Calendar into a project. There are quite a few steps, but it’s pretty straightforward once you know what to do. As with most programming, there are many other ways of acheiving the same thing, but I won’t be exploring any of them, other than the one that worked for me. All the information here is already out there, but it’s broken into pieces – I couldn’t find any posts showing how to do the whole process from start to finish. So I wrote this.

This presumes you have a Google account and a calendar set up on Google Calendar with events on it which you want to read from a PHP application on a web site. You also need to have a shell account on your server¹.

You will see how to set up a project containing a service account, how to set up authorisation for the service account to retrieve the Calendar data for your web page, and how to set up your web site using PHP to access your calendar using the service account.

Setting up the service account

The service account is like a robot user that accesses Google services on behalf of your web site. It has an email address and an ID, and can log in to Google services using a public/private key pair. Your service account has to belong to a project, and each project can contain multiple service accounts. You can have up to 12 free projects, so it’s probably best to create a new one for your calendar data slurper.

Go to https://console.cloud.google.com and log in if necessary. Click on the 3-dot logo / pull down menu at the top to open the “Select a project” box. Click on “Add new project” or, if you already have one you are going to use, select it here and go to step 3.
Give your project a name and see if the “Project ID” is to your liking. I called mine “Testy test”. Click “Create”.
From here on I’m calling the project “Testy test”. You might want to call yours something a bit less stupid.
If the page doesn’t say “Welcome. You are working in Testy test.”, select the project, either from the notifications drop down, or by clicking the 3-dot logo.
Click on the “IAM & Admin” quick access button or select it from the navigation menu on the left. The page will show you as being the principle for the project “Testy test” but not much else. Click on “Service Accounts” on the left navigation pane to bring up an empty list of service accounts belonging to the project.
Click “+ CREATE SERVICE ACCOUNT” to go to the next page, which has 3 steps to creating it. First, give your service account a name and description:
Make a note of the email address. You will need it later when you share the calendar with your service account. Click “CREATE AND CONTINUE”.
Skip the next two optional steps.
You will now be back at the service account list, with your newly created account showing:
You now want to set up authorisation for your service account by creating keys so it can access APIs. Click on the “Actions” dots and choose “Manage keys”. You will go to a page with an empty list of keys for that service.
Click on “ADD KEY” and choose “Create new key”.
Make sure that “JSON” is selected and choose “CREATE”. Your browser will automatically download a file containing your private key. Upload this file to somewhere safe on your server. This is your private key and has to be accessible to your PHP script but must not be kept anywhere accessible by your web server. On a Linux system, keep it somewhere off your home directory, not your web root (usually public_html) directory. This is really important, so much so that the word “not” is not only bold, but red as well. You have to keep this key private.
You now need to enable the Calendar API for your project. Click on “APIs & Services” in the quick links box of the “Welcome” page or the left menu. Click on “+ ENABLE APIS AND SERVICES”.
Do a search for “Calendar” and click on the result that says “Google Calendar API”.
Click on the “Enable” button and you will be taken to the entry for the Calendar API off the “Enabled APIs and Services” page, showing stats for that API.

Your service account is now ready to go.

Setting up your web server with the PHP for using the API

You now need to download the PHP scripts to for use with the Google API. Well, you don’t NEED to, you could write it all yourself, and there is information out there on how to do it. But anyone sane would just use the scripts that Google provide for free.

The easiest way to install the scripts you need for PHP is to use Composer. This is an installer which works in a similar way to Apt. Follow the instructions on this page to install it.
Install the Google API PHP files by using this command in your web site’s root directory:
composer require google/apiclient:^2.15.0

Now you are ready to start using the calendar API.

Allowing the service account to access your calendar

Before you can access the calendar from your PHP pages, you need to share it with your service account.

Start Calendar in a web browser and click on the burger of the calender you want to use in the “My calendars” section and choose “Settings”:
Scroll down to the “Share with specific people or groups” section and click “Add people and groups”.
Remember part 7 of setting up the service account? Where I said make a note of the email address? Yup. That’s what you put in the “Add email or name” box. Make sure the “See all event details” is chosen and then click “Send”. If you want your PHP script to be able to alter the calendar you need to choose another option that allows it. Only grant permissions that are necessary.
Scroll down to the “Integrate calendar” section and make a note of the Calendar ID. It looks something like “qhhbdvqi5dom44arse60oav68k@group.calendar.google.com”.
It’s at this point that I wish I had read the documentation a bit more closely and seen this:

Note: Sharing a calendar with a user no longer automatically inserts the calendar into their CalendarList. If you want the user to see and interact with the shared calendar, you need to call the CalendarList: insert() method.

Read that again. It’s important. I spent literally hours trying to find out why the API couldn’t see the calendar. Hours wasted because I didn’t read a paragraph of text. Anyway I’m not bitter, as you can tell.

Hitting the PHP

There doesn’t seem to be a way to insert a calendar into the service account’s calendar list from the admin console, so you need to run the following code on your server. Download it here – right click on that link and choose “Save link as…”

<?php
require_once __DIR__.'/vendor/autoload.php';

if ($argc < 2) {
    echo "Supply the calendar name as an argument\n";
    exit;
}

$calendarId = $argv[1];

$client = new Google_Client();
$client->setAuthConfig('/path/to/credentials.json');

$client->setScopes('https://www.googleapis.com/auth/calendar');
$client->setApplicationName("My Calendar");

$service = new Google_Service_Calendar($client); 

$calendarListEntry = new Google_Service_Calendar_CalendarListEntry();
$calendarListEntry->setId($calendarId);

$service->calendarList->insert($calendarListEntry);

$calendarList = $service->calendarList->listCalendarList();

while(true) {
  foreach ($calendarList->getItems() as $calendarListEntry) {
    echo $calendarListEntry->getSummary() . "\n";
  }
  $pageToken = $calendarList->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $calendarList = $service->calendarList->listCalendarList($optParams);
  } else {
    break;
  }
}
?>

Edit the highlighted parts with your path to the keys file (step 11 of setting up the service account) and change the application name if you want to. Then run the script from the command line with:

naich:~$ php add_calendar.php qhhbdvqi5dom44arse60oav68k@group.calendar.google.com

Obviously change the calendar ID to the one you want to use (step 4 of allowing the service access to your calendar). If all goes well you should see the name of the calendar you have added along with the other calendars (if any) that have been added to that service account already. If not you will see lines of error messages. Make sure you have followed all the steps in “Allowing the service to access your calendar”.

Your service account is now ready for your scripts to use.

Getting started

https://developers.google.com/calendar has information about using the calendar API and the examples (e.g. in this tutorial) usually have PHP versions. The examples assume you have already set up a service in your PHP script – something like this:

require_once __DIR__.'/vendor/autoload.php';

$calendarId = "qhhbdvqi5dom44arse60oav68k@group.calendar.google.com";

$client = new Google_Client();
$client->setAuthConfig('/path/to/credentials.json');

$client->setScopes('https://www.googleapis.com/auth/calendar');
$client->setApplicationName("Calendar");

$service = new Google_Service_Calendar($client);

There is a list of Google_Service_Calendar methods which is confusing as hell to me. If you use the links on the left with “_Resource” at the end you get a list of functions for that class. So, for example, the Google_Service_Calendar_Events_Resource page shows how to get a list of events for a calendar. The code would be:

$events = $service->events->listEvents($calendarId);

Follow the link in the “Returns” section to see how to use the $events class. Something like:

  foreach ($events->getItems() as $event) {
    $name = $event->getSummary();
    $startDate = $event->getStart()->getDate();
    $endDate = $event->getEnd()->getDate();

And so on. Basically you need to do a lot of reading of documents, which is where I’ll leave you now.

Good luck!

I think that in theory you could do all this on a hosted account, but it would not be straightforward to keep the private key secure if you can only access space that is readable by the web server. You would also have to install the Google PHP APIs manually. ↩︎

Naich's crappy blog