DIV CSS 佈局教程網

您现在的位置: DIV+CSS佈局教程網 >> 網頁腳本 >  >> XML學習教程 >> XML詳解
用 XPath 把 Google Calendar 事件搬上 PHP 網站
編輯:XML詳解     

一個老問題:日曆副本到處跑

幾年前我還在接案子的時候,幫一個特殊車款的車主與愛好者社群做過一個 PHP 入口網站。管理者當初自己學了點網頁技巧、把站搭了起來;隨著頁面越堆越多,問題也浮上來了——那些貼著活動日曆資訊的頁面,內容早就過期,卻還掛在站上。

幾份日曆快照各走各的路,彼此不同步。有些活動早就辦完了,側欄裡卻還留著。就算管理得當、資訊架構也設計得好,在多個網頁裡各自維護一份日曆副本,仍然是又耗時又容易出錯的事。他們後來想通一件事:不是車俱樂部的網站替他們工作,而是他們在替網站工作。

他們要的其實很清楚:一個論壇讓車主聊車、一個集中的新聞頁發布最新活動報導,而且——重點在這裡——不要再多份日曆副本。日曆只在單一入口輸入,站上任何位置都能取用。

Google Calendar 與 Google Data API

線上日曆看起來正是答案。集中管理、集中顯示,社群成員到同一個地方看最新活動,不會被各頁過期資訊搞糊塗。

我用 Drupal 內容管理系統替車俱樂部建站的時候,建議他們把日曆交給 Google Calendar 維護。一開始反饋很好,因為用 Drupal 的後台更新側欄很輕鬆。但俱樂部越做越成功、活動越來越多,編輯側欄就從輕鬆有趣變成一件苦差。

Google Data API 提供了出路。它實作了 Atom 發布協議(Atom Publishing Protocol,APP),是一套用來讀寫各類文件與資訊的 Web 服務 API;此外 .Net、Java、Python、PHP 都有第三方整合套件,把大部分功能包進一組物件導向的類別裡。研究一陣子之後,我把俱樂部的 Drupal 站擴充成一個會自己保持最新的活動側欄,資料直接從 Google Calendar 帳號拉。

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 請求上支援查詢參數,讓客戶端精確指定要什麼:

  • max-results:最多回傳幾筆
  • orderby:用哪個元素排序
  • start-min / start-max:要納入的事件起始時間範圍,兩者皆為 RFC 3339 格式
  • singleevents=true:把重複事件展開成一個個獨立事件;否則條目裡會帶一個 iCal 格式的 <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

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

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 的 Google Data API 類別

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 才拿得到屬性。

XPath 搭配 SimpleXML

我個人是 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 時,它是最省力的那一個——而速度上的差距,交給快取去補就行。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved