幾年前我還在接案子的時候,幫一個特殊車款的車主與愛好者社群做過一個 PHP 入口網站。管理者當初自己學了點網頁技巧、把站搭了起來;隨著頁面越堆越多,問題也浮上來了——那些貼著活動日曆資訊的頁面,內容早就過期,卻還掛在站上。
幾份日曆快照各走各的路,彼此不同步。有些活動早就辦完了,側欄裡卻還留著。就算管理得當、資訊架構也設計得好,在多個網頁裡各自維護一份日曆副本,仍然是又耗時又容易出錯的事。他們後來想通一件事:不是車俱樂部的網站替他們工作,而是他們在替網站工作。
他們要的其實很清楚:一個論壇讓車主聊車、一個集中的新聞頁發布最新活動報導,而且——重點在這裡——不要再多份日曆副本。日曆只在單一入口輸入,站上任何位置都能取用。
線上日曆看起來正是答案。集中管理、集中顯示,社群成員到同一個地方看最新活動,不會被各頁過期資訊搞糊塗。
我用 Drupal 內容管理系統替車俱樂部建站的時候,建議他們把日曆交給 Google Calendar 維護。一開始反饋很好,因為用 Drupal 的後台更新側欄很輕鬆。但俱樂部越做越成功、活動越來越多,編輯側欄就從輕鬆有趣變成一件苦差。
Google Data API 提供了出路。它實作了 Atom 發布協議(Atom Publishing Protocol,APP),是一套用來讀寫各類文件與資訊的 Web 服務 API;此外 .Net、Java、Python、PHP 都有第三方整合套件,把大部分功能包進一組物件導向的類別裡。研究一陣子之後,我把俱樂部的 Drupal 站擴充成一個會自己保持最新的活動側欄,資料直接從 Google Calendar 帳號拉。
Google Data API 會以 Atom 摘要的形式提供各項 Google 服務的文件與資訊,Google Calendar 也不例外。摘要分公開與需驗證兩類:取用驗證過的摘要時,HTTP 客戶端要在 GET 請求裡附上認證資訊;而驗證過的摘要還能接受 POST,讓你可以新增或刪除事件、訂閱或取消訂閱日曆、建立與刪除日曆。
Calendar API 會為使用者能從 GUI 看到的每一本日曆都提供摘要——自己擁有的、別人擁有但你已訂閱的,以及以唯讀方式匯入的。每本日曆各自有公開與私有的驗證事件摘要,逐一列出其中的事件。本文只聚焦在公開事件摘要。
登入 Google Calendar,找到要處理的日曆,點日曆名稱旁的小箭頭,在跳出的選單裡選 Calendar Settings。
圖 1. 所選日曆的 Google Calendar 下拉選單

接著會進入該日曆的設定頁,可以調整時區、名稱等選項。要讓摘要可被公開取用,請點 Change sharing settings:
圖 2. 將日曆的可見性變更為共享或公開

在 Share this calendar 頁籤上選擇「Share all information on this calendar with everyone」。系統會跳出確認對話框,詢問你是否真的要公開日曆,回答 Yes,然後別忘了點頁籤底部的 Save 儲存設定。之後按 Back to Calendar 就能繼續往裡頭加活動。
摘要裡每個事件條目都帶著描述該事件的元素:標題、說明、時間與地點。Google Calendar 還維護一份受邀者名單,事件一有更新就透過郵件發送細節;如果這些地址屬於 Google Calendar 使用者,他們可以直接回覆邀請,出席狀態也會被記錄下來。出席細節不在本文範圍內,我們只看基本的事件資訊。
清單 1. 事件條目:識別碼與時間戳
<entry>
<id>
https://www.google.com/calendar/feeds/foss.sanjuan%40gmail.com/public/full/
s19o15ve3nn209gv5qf6c43ao4
</id>
<published>2007-08-12T15:45:40.000Z</published>
<updated>2007-08-12T15:53:37.000Z</updated>
...
...
id 提供該事件在 Google Calendar 系統內唯一的 URI,除了識別碼本身,也標示了它是從哪一份摘要取回的。published 與 updated 使用 RFC 3339 時間戳格式,updated 代表最後編輯時間,對新事件而言就是建立時間。
清單 2. 事件條目:標題、作者與狀態
...
<title type="text">Linux Install Fest</title>
...
<author>
<name>Open Source San Juan</name>
<email>foss.sanjuan@gmail.com</email>
</author>
...
<gd:eventStatus value="https://schemas.google.com/g/2005#event.confirmed"/>
...
title 是一個單純的字串,用來標示事件,不必唯一。author 裡有 name 與 email,也就是把這筆事件輸入日曆的人——在適當設定驗證摘要與寫入權限之後,除了日曆擁有者,其他使用者也能在你的日曆裡建立事件。gd:eventStatus 則有三種可能值:
表 1. gd:eventStatus 的可能值
| 值 | 描述 |
|---|---|
| https://schemas.google.com/g/2005#event.cancelled | 事件已取消。 |
| https://schemas.google.com/g/2005#event.confirmed | 事件已確認。 |
| https://schemas.google.com/g/2005#event.tentative | 事件暫定。 |
清單 3. 事件條目:時間與地點
...
<gd:when startTime="2007-08-03T16:00:00.000-04:00"
endTime="2007-08-03T19:00:00.000-04:00"/>
<gd:where
valueString="Guaynabo Public High School Auditorium, Guaynabo, PR"/>
</entry>
when 元素帶 startTime 與 endTime 兩個屬性,都是 RFC 3339 時間戳;where 的 valueString 就是地點字串,可以從 Calendar 應用程式或 API 完整取得。
順帶一提,Google Calendar 與 Google Data API 不支援針對單一元素做精確查詢,而是對字串元素(title、author、description,以及 where 的 valueString)進行全文比對。唯一的例外,是可以利用開始日期範圍來限制結果。
Google Data API 在 HTTP GET 請求上支援查詢參數,讓客戶端精確指定要什麼:
<gd:recurrence> 元素。iCal 的格式與解析方式不在本文範圍內。清單 4. 帶查詢參數的摘要 URL
https://www.google.com/calendar/feeds/foss.sanjuan%40gmail.com/public/full? max-results=25& singleevents=true& orderby=starttime& start-min=2007-05-22T09%3A58%3A47-04%3A00& start-max=2007-11-06T09%3A58%3A47-04%3A00
DOM 是最標準也最常見的選擇。它的長處是快與可讀——整份文件載入記憶體後,取元素全在記憶體裡完成;程式碼幾乎像英文句子一樣直白:「取出標籤名稱為 entry 的元素」。
清單 5. 以 DOM 解析 Google Calendar 事件摘要
<?PHP
$confirmed = 'https://schemas.google.com/g/2005#event.confirmed';
$three_months_in_seconds = 60 * 60 * 24 * 28 * 3;
$three_months_ago = date("Y-m-dTh:i:sP", time() - $three_months_in_seconds);
$three_months_from_today = date("Y-m-dTh:i:sP", time() + $three_months_in_seconds);
$feed = "https://www.google.com/calendar/feeds/foss.sanjuan%40gmail.com/"
. "public/full?orderby=starttime&singleevents=true&"
. "start-min=" . $three_months_ago . "&"
. "start-max=" . $three_months_from_today;
$doc = new DOMDocument();
$doc->load($feed);
$entries = $doc->getElementsByTagName("entry");
foreach ($entries as $entry) {
$status = $entry->getElementsByTagName("eventStatus");
$eventStatus = $status->item(0)->getAttributeNode("value")->value;
if ($eventStatus == $confirmed) {
$titles = $entry->getElementsByTagName("title");
$title = $titles->item(0)->nodeValue;
$times = $entry->getElementsByTagName("when");
$startTime = $times->item(0)->getAttributeNode("startTime")->value;
$when = date("l JS of F Y - h:i A", strtotime($startTime));
$places = $entry->getElementsByTagName("where");
$where = $places->item(0)->getAttributeNode("valueString")->value;
print $title . "<br>";
print $when . " AST<br>";
print $where . "<br><br>";
}
}
?>
要留意的是 gd: 前綴必須拿掉。PHP 的 DOM API 認得命名空間,留著前綴反而找不到元素。缺點則是囉嗦:getElementsByTagName 與 getAttributeNode 一層層疊下來,行數很快就膨脹;而且大型 XML 文件的記憶體開銷相當可觀,實務上只適合 2、3 MB 等級的文件。
SAX 走另一條路:不把整份文件載進記憶體,而是邊讀邊觸發 callback。寫得好的 SAX 程式可以快得多,記憶體用量也能壓在最低、隨需求調整;DOM 的記憶體需求則是從你要處理的最大文件尺寸往上起跳。
清單 6. 以 SAX 解析事件摘要(片段)
function startElement($parser, $tagName, $attr) {
global $g_entries, $g_tagName, $g_confirmed, $g_is_confirmed,
$g_in_entry, $g_in_originalevent;
if ($tagName == 'ENTRY') {
if ($g_is_confirmed || count($g_entries) == 0) {
$g_entries[] = array();
}
$g_is_confirmed = false;
$g_in_entry = true;
} else if ($tagName == 'GD:EVENTSTATUS') {
if ($attr['VALUE'] == $g_confirmed) {
$g_is_confirmed = true;
}
} else if ($tagName == 'GD:WHEN' && $g_is_confirmed &&
$g_in_originalevent == false) {
$startTime = date("l JS of F Y - h:i A", strtotime($attr['STARTTIME']));
$g_entries[count($g_entries) - 1]['when'] = $startTime;
} else if ($tagName == 'GD:WHERE' && $g_is_confirmed) {
$g_entries[count($g_entries) - 1]['where'] = $attr['VALUESTRING'];
} else if ($tagName == 'GD:ORIGINALEVENT') {
$g_in_originalevent = true;
}
$g_tagName = $tagName;
}
function endElement($parser, $tagName) {
global $g_tagName, $g_in_entry, $g_in_originalevent;
if ($tagName == 'ENTRY') {
$g_in_entry = false;
} else if ($tagName == 'GD:ORIGINALEVENT') {
$g_in_originalevent = false;
}
$g_tagName = null;
}
function textData($parser, $text) {
global $g_entries, $g_tagName, $g_in_entry;
if ($g_tagName == 'TITLE' && $g_in_entry) {
$g_entries[count($g_entries) - 1]['title'] = $text;
}
}
這段程式裡的複雜度不是憑空來的。SAX 的元素是從上到下依序流過的,你往往得先讀到後面的元素,才能決定前面累積的東西要不要留——gd:eventStatus 就出現在 title 之前,所以必須先設旗標記錄「這筆確認了嗎」。摘要本身有 title,每個條目也有 title,得靠旗標分辨;重複事件的 gd:originalEvent 裡還嵌著一個 gd:when,那不是你要的那個。少了這些狀態檢查,單純比對元素名稱就會吐出錯誤結果。
Zend Technologies 與 Google 合作擴充了 Zend Framework,用一組物件導向類別把 Atom 摘要與 HTTP 細節(GET、PUT、POST)都藏起來,連使用者認證也一併封裝,因此很適合需要寫入資料的情境。代價是建構子多半不帶參數,選項得在產生物件後逐一設定,程式碼於是變長。
清單 7. 以 Zend 類別取用並處理事件摘要
<?PHP
require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata');
Zend_Loader::loadClass('Zend_Gdata_Calendar');
$three_months_in_seconds = 60 * 60 * 24 * 28 * 3;
$three_months_ago = date("Y-m-dTh:i:sP", time() - $three_months_in_seconds);
$three_months_from_today = date("Y-m-dTh:i:sP", time() + $three_months_in_seconds);
// 不帶認證建立服務實例,唯讀取用公開摘要
$service = new Zend_Gdata_Calendar();
$query = $service->newEventQuery();
$query->setUser('foss.sanjuan%40gmail.com');
$query->setVisibility('public');
$query->setProjection('full');
$query->setOrderby('starttime');
$query->setStartMin($three_months_ago);
$query->setStartMax($three_months_from_today);
try {
$eventFeed = $service->getCalendarEventFeed($query);
} catch (Zend_Gdata_App_Exception $e) {
echo "Error: " . $e->getResponse();
}
print "<ul>";
foreach ($eventFeed as $event) {
print "<li>" . $event->title . "</li>";
$startTime = $event->when->startTime;
print "<li>" . date("l JS of F Y - h:i A", strtotime($startTime));
// Google Calendar API 對時區的處理有 bug
print " AST</li>";
print "<li>" . $event->where->valueString . "</li>";
}
print "</ul>";
它的優點在於取得 eventFeed 之後,元素與屬性都能沿著階層一路走下來,讀起來貼近 XML 本身的形狀,不像 DOM 那樣得靠 getAttributeNode("attributeName")->value 才拿得到屬性。
我個人是 SimpleXML 的支持者,理由很簡單:它支援 XPath,而且把文件包成一組可逐層遍歷的物件屬性,寫起來直覺。差別只在屬性要靠 attributes() 取出,會回傳一個裝著屬性的物件。
清單 8. 以 XPath 與 SimpleXML 解析事件摘要
$s = simplexml_load_file($feed);
foreach ($s->entry as $item) {
$gd = $item->children('https://schemas.google.com/g/2005');
if ($gd->eventStatus->attributes()->value == $confirmed) {
?>
<font size=+1><b>
<?PHP print $item->title; ?>
</b></font><br>
<?PHP
$startTime = '';
if ($gd->when) {
$startTime = $gd->when->attributes()->startTime;
} elseif ($gd->recurrence) {
$startTime = $gd->recurrence->when->attributes()->startTime;
}
print date("l JS of F Y - h:i A", strtotime($startTime));
// Google Calendar API 對時區的處理有 bug
print " AST<br>";
?>
<?PHP print $gd->where->attributes()->valueString; ?>
<br><br>
<?PHP
}
} ?>
它也有兩個明確的弱點。一是速度,最多可能比 DOM 或 SAX 慢上四倍,原因是元素與屬性節點靠 PHP 的動態特性即時生成,不像 Zend 類別那樣在類別節點裡預先定義,所以逐層遍歷時 Zend 反而更快。二是命名空間支援較弱,取特定命名空間的元素得先呼叫 children(),而 DOM 與 Zend 類別都能把各命名空間的元素直接呈現為可遍歷的節點。
本文的範例程式有一個共同的問題:使用者每開一次頁面,它就重新下載並解析一次摘要。如果這段程式放在側欄,訪客每跳一個頁面就重跑一次——考慮到日曆可能好幾天都不會變,這非常浪費。
而且這不只是效能問題。Google Data API 的服務條款明文不允許這類高頻請求;一旦違反,Google 可以攔截你伺服器的 IP,最壞的情況是停掉帳號。熱門論壇一天上千次瀏覽其實不難達到,20 到 30 個活躍使用者就夠了。顯然該用更聰明的做法。
可行的策略都圍繞同一個想法:把輸出快取起來,只在內容真的變了時才重新處理整份摘要。其中一種是善用 HTTP 標頭。Google Data 服務會依回應中 <atom:updated> 的值設定 Last-Modified 標頭;腳本首次執行時,可以把渲染好的 HTML 存成檔案,同時把該時間戳記進資料庫。之後每次請求,就把時間戳放進 If-Modified-Since 標頭送回去。
若內容沒變,Google 會回 304(Not Modified),腳本直接把先前那份 HTML 包進來即可;若變了,會回 200(OK),腳本重新產生 HTML、更新資料庫裡的時間戳,再輸出新的檔案。
只為一個時間戳開資料庫記錄顯然太重,但 PHP 不像 ASP、ASP.Net、Java servlet 或 JSP 那樣原生支援應用程式層級變數。共享記憶體是另一條路,不過並非所有 PHP 安裝都開啟,因為它有安全風險。若你的 PHP 跑在伺服器叢集上,memcached 會是更合適的選擇——這套叢集記憶體快取服務最早出自 LiveJournal 團隊,後來由 Facebook 的工程師大幅改良。
Google Calendar 提供了一個集中的前台,讓組織與管理者能自由維護並發布成員與公眾的活動日曆;Google Data API 則以 Atom 摘要與 Atom 發布協議,把讀取、查詢、更新、建立的能力開放出來,幾乎涵蓋所有 Google 應用程式。
有了 XPath,你只要查詢事件摘要、解析其中的條目,就能讓網站上的最新活動自動跟日曆同步。XPath 不是 PHP 工具箱裡最快的 XML API,但當手上是一份結構清楚、文件完整的 XML 時,它是最省力的那一個——而速度上的差距,交給快取去補就行。