Interrogare Google Calendar con PHP

Nel precedente articolo abbiamo introdotto l'utilizzo della libreria Zend GData per l'accesso alle API GData di Google, fornite come servizi che permettono di accedere alle fonti di dati pubbliche e private utilizzate da Google per immagazzinare le informazioni inserite all'interno di alcune delle sue applicazioni web. Abbiamo introdotto il sistema di autenticazione che fornisce un certo grado di libertà sia per chi necessita solamente l'accesso in lettura ai dati pubblici che per chi invece desidera aggiornare i dati o accedere ad informazioni protette.

In questo articolo, che divideremo in due parti distinte, scenderemo in dettaglio illustrando come utilizzare praticamente la libreria Zend GData dopo aver svolto l'autenticazione necessaria; utilizzeremo le classi illustrate nello scorso articolo in modo da interrogare le fonti di dati, modificare i valori ottenuti ed eliminarli in caso fosse necessario. Ci interfacceremo a Google Calendar, servizio di Google che permette di mantenere un calendario online completo di avvisi, appuntamenti e condivisione pubblica o privata.

Per chi lo desiderasse, le informazioni più dettagliate sulle API di Google Calendar possono essere recuperate sulla pagina messa a disposizione dal motore di ricerca.

Prime operazioni con le Google Calendar API

Come per gli altri servizi di Google, Calendar si basa sul protocollo Atom APP (descritto brevemente nell'articolo precedente). La classe fornita dalle Zend API per istanziare ed interrogare il servizio è Zend_Gdata_Calendar e può essere utilizzata sia con che senza autenticazione. Nel secondo caso sarà ovviamente possibile accedere solamente ai calendari pubblici.

Come prima operazione potremmo occuparci di recuperare una lista di calendari per un determinato utente. Questa operazione è possibile solamente se ci si è precedentemente autenticati e, diversamente da quello che accade quando si accede all'interfaccia grafica di Google Calendar, saranno restituiti anche i calendari marcati come hidden (nascosti).

<?php

// ... import omessi per brevità

$user = 'username';
$pass = 'password';
$client = Zend_Gdata_ClientLogin::getHttpClient(
			$user, $pass,
			Zend_Gdata_Calendar::AUTH_SERVICE_NAME);
$calendar_service = new Zend_Gdata_Calendar($client);

try
{
	$listFeed = $calendar_service->getCalendarListFeed();
	echo "<h3>Feeds restituiti</h3>";
	echo "<ul>";
	foreach($listFeed as $calendar_entry)
	{
		echo "<li>". $calendar_entry->title ."</li>";
	}
	echo "</ul>";
} catch (Zend_Gdata_App_Exception $e) 
{
	echo "Error: " . $e->getResponse();
}

?>

Utilizzando il metodo getCalendarListFeed otteniamo un'istanza della classe Zend_Gdata_Calendar_ListFeed che contiene per l'appunto il feed che rappresenta la lista di calendari disponibili per l'utente con cui ci si è autenticati. Se iterata questa classe restituisce istanze della classe Zend_Gdata_Calendar_ListEntry che rappresenta una singola Entry del feed in cui sono contenute le informazioni su un determinato calendario.

Dopo aver recuperato i calendari che possiamo analizzare, si può procedere con l'interrogazione di uno di questi per ottenere la lista di eventi presenti.

L'interrogazione avviene utilizzando URL specifici che contengono parametri per filtrare i risultati; per comodità è stata implementata la classe Zend_Gdata_Calendar_EventQuery che permette di generare questi URL in modo semplice come se si stesse effettuando un'interrogazione basata su criteri ad un database ad oggetti. Vediamo ad esempio una classica interrogazione presa dal manuale che permette di ottenere una lista di eventi privati ordinati in base alla data di inizio:

<?php

// ... import omessi per brevità

$user = 'username';
$pass = 'password';
$client = Zend_Gdata_ClientLogin::getHttpClient(
			$user, $pass,
			Zend_Gdata_Calendar::AUTH_SERVICE_NAME);
$calendar_service = new Zend_Gdata_Calendar($client);

$query = $calendar_service->newEventQuery();
$query->setUser('default');
/* Nel caso si utilizzasse come sistema di autenticazione MagicCookie, è necessario
*  impostare la visibility come private-magicCookieValue
*/
$query->setVisibility('private');
$query->setProjection('full');
$query->setOrderby('starttime');
$query->setFutureEvents('true');

try
{
    $eventFeed = $calendar_service->getCalendarEventFeed($query);
	echo "<ul>";
	foreach ($eventFeed as $event_entry)
	{
	    echo "<li>". $event_entry->title ."</li>";
	}
	echo "</ul>";
} catch (Zend_Gdata_App_Exception $e)
{
    echo "Error: " . $e->getResponse();
}

?>

L'interrogazione viene effettuata sempre passando per la classe che rappresenta il servizio a cui si è acceduto e restituisce sempre un feed Atom (in questo caso un'istanza della classe Zend_Gdata_Calendar_EventFeed) che può essere iterato ottenendo ogni singola Entry sotto forma di istanza della classe Zend_Gdata_Calendar_EventEntry. La classe che rappresenta la query di interrogazione accetta alcuni parametri che servono a limitare i risultati ottenuti:

• setUser permette di impostare l'utente (sotto forma del suo indirizzo email) di cui si desidera recuperare gli eventi. Nel caso non venga specificato o si utilizzi la stringa default i risultati ottenuti saranno quelli dell'utente con cui ci si è autenticati;
• setVisibility permette di specificare se si vuole limitare la ricerca ai calendari pubblici (public) o privati (private);
• setProjection permette di specificare la quantità di dati che saranno ottenuti dall'interrogazione. Per i dettagli sul valore di questo argomento rimando alla documentazione ufficiale delle Google Calendar API. In generale utilizzerete comunque il valore full che indica al servizio di restituire un feed Atom contenente estensioni aggiuntive che contengono tutte le informazioni sull'evento;
• setOrderBy permette di specificare l'ordine con cui si vogliono ottenere i risultati. I valori supportati attualmente sono starttime (ordinato per data di inizio dell'evento) e lastmodified (ordinato per la data di ultima modifica);

Altri metodi fondamentali per l'interrogazione sono quelli che permettono di limitare la data di ricerca, di effettuare ricerche fulltext o di cercare un determinato evento:

• setStartMin e setStartMax servono per limitare il range temporale su cui effettuare la ricerca. Accettano come parametro la data in formato YYYY-MM-DD;
• setQuery serve per fornire una chiave di ricerca fulltext che verrà utilizzata per filtrare i dati. Il parametro passato è una stringa che rappresenta la chiave fulltext di ricerca, nello stesso formato accettato da Google per le ricerche sui siti internet (a questo indirizzo trovate maggiori dettagli nel caso foste interessati);
• setEvent accetta come parametro l'ID di un evento specifico (che potete ottenere attraverso il parametro id della classe Zend_Gdata_Calendar_EventEntry) e restituisce quell'evento se presente nel contesto specificato;

Vi lasciamo prendere confidenza con questi comandi. Nella parte successiva dell'articolo vedremo la creazione dei nuovi eventi all'interno di un singolo calendario.

Creazione di nuovi eventi

Dopo aver introdotto, nella prima parte di questo articolo, gli strumenti per interrogare il servizio Google Calendar per ottenere i calendari e gli eventi che ci interessano, possiamo procedere analizzando come avviene la creazione e l'inserimento di un nuovo evento all'interno di un determinato calendario. Per poter effettuare l'operazione di inserimento è necessario aver effettuato l'accesso alle API GData di Google Calendar utilizzando uno qualsiasi dei sistemi di autenticazione supportati.

Un nuovo evento è rappresentato come un'istanza della classe Zend_Gdata_EventEntry, che verrà convertita automaticamente dalle API Zend in XML per essere inviata al server. Affinchè un evento risulti valido è necessario specificare per lo meno il titolo (attraverso la proprietà Title) e la data in cui avverrà (attraverso al proprietà When). Altri parametri sono disponibili ma opzionali, e possono essere specificati per indicare dettagli sull'evento:

• Author: fornisce informazioni sull'autore che ha creato l'evento;
• Content: testo contenente informazioni aggiuntive sull'evento;
• EventStatus: specifica lo stato dell'evento (confirmed, tentative oppure canceled);
• Hidden: nasconde l'evento in modo che non sia visibile dall'interfaccia grafica di Google Calendar;
• WebContent: permette di specificare dei link da associare all'evento;
• Where: indica la locazione dell'evento;
• Visibility: permette di nascondere l'evento della lista degli eventi pubblici (specificando private come valore);

Una lista completa dei valori è disponibile nella documentazione ufficiale del protocollo utilizzato da Google Calendar. Vediamo come effettuare praticamente l'inserimento di un evento:

<?php

// ... import ed autenticazione omessi per brevità

$event = $calendar_service->newEventEntry();
$event->title = $calendar_service->newTitle("Titolo dell'evento");
$event->where = array($calendar_service->newWhere("Milano, Italy"));
$event->content = $calendar_service->newContent("Il contenuto dell'evento, magari una descrizione ...");

$startDate = "2008-01-20";
$startTime = "14:00";
$endDate = "2008-01-20";
$endTime = "16:00";
$tzOffset = "-08";

$when = $calendar_service->newWhen();
$when->startTime = "{$startDate}T{$startTime}:00.000{$tzOffset}:00";
$when->endTime = "{$endDate}T{$endTime}:00.000{$tzOffset}:00";
$event->when = array($when);

$newEvent = $calendar_service->insertEvent($event);

?>

Come possiamo notare ogni proprietà dell'evento deve essere generata attraverso metodi specifici del servizio istanziato, che si occuperanno anche della validazione dei dati. Il parametro where contiene un array di locazioni specificate utilizzato i formati validi accettati da Google Maps. Il parametro when invece, che ricordo essere obbligatorio, contiene una lista di istanze di oggetti generati attraverso il metodo newWhen, che vengono popolati con informazioni sull'inizio e la fine della ricorrenza. Il formato utilizzato per specificare la data è specificato nella RFC 3339.

Il parametro when è molto interessante in quanto permette di specificare anche altre informazioni che influiranno sull'evento:

• attraverso la proprietà valueString possiamo definire un messaggio che verrà associato all'evento;
• attraverso la proprietà remider possiamo definire una lista di reminder che verranno utilizzati per la notifica dell'evento. Questi reminder sono generati attraverso il metodo newReminder dell'istanza del servizio e sono istanze della classe Zend_Gdata_Extension_Reminder. Rimando alla documentazione ufficiale per la lista delle proprietà supportate;

Quando si genera un evento è possibile definirlo come ricorrenza; in questo caso è necessario omettere il parametro when e definire invece un parametro recurrence definito utilizzando il formato data specificato nella RFC 2445:

<?php

// ... import ed autenticazione omessi per brevità

$event = $calendar_service->newEventEntry();
$event->title = $calendar_service->newTitle("Titolo dell'evento");
$event->where = array($calendar_service->newWhere("Milano, Italy"));
$event->content = $calendar_service->newContent("Il contenuto dell'evento, magari una descrizione ...");

$recurrence = "DTSTART;VALUE=DATE:20070501rn".
        "DTEND;VALUE=DATE:20070502rn".
        "RRULE:FREQ=WEEKLY;BYDAY=Tu;UNTIL=20070904rn";
$event->recurrence = $calendar_service->newRecurrence($recurrence);

$newEvent = $calendar_service->insertEvent($event);

?>

Il formato utilizzato per definire le ricorrenze è abbastanza complesso, ed alcuni dettagli oltre che nella reference indicata precedentemente possono essere trovati nella documentazione ufficiale di Google.

Conclusione

Nel prossimo articolo ci occuperemo delle operazioni di modifica ed eliminazione degli eventi, fornendo anche una semplicissima applicazione di esempio.