WebDAV – implementace v PHP

18. června 2003

•

V závěrečném díle seriálu věnovaného WebDAVu si ukážeme jak v PHP naprogramovat třídu pro komunikaci s WebDAV serverem. Předem bych rád uživatele PHP upozornil, že v rámci projektu PEAR byla mimo jiné vytvořena třída pro komunikaci s WebDAV serverem. Pokud vám tedy nebude vyhovovat třída popisovaná v dnešním článku, můžete si její alternativu z projektu PEAR stáhnout na níže uvedené adrese.

WebDAV je ve svém RFC dokumentu definován jako nadstavba protokolu HTTP. Proto i my budeme postupovat obdobným způsobem a nejdříve vytvoříme třídu pro podporu protokolu HTTP, kterou následně použijeme jako předka třídy WebDAV.

Požadované vlastnosti

Klient komunikující s WebDAV serverem musí umět tři základní věci: komunikovat s HTTP serverem, vytvořit a číst dotaz odpovídající specifikaci WebDAVu a vytvořit a analyzovat XML dokument. Jelikož by vytvoření parserů pro jednotlivé typy XML dokumentů, které WebDAV používá, podstatně prodloužilo tento článek, zaměříme naši pozornost na komunikaci se serverem a vytváření a analýzu dotazů.

Třída HTTP_Server

Třída HTTP_Server (předek třídy WebDAV) bude, jak název napovídá, sloužit k zajištění komunikace s HTTP serverem. Konkrétně otevře spojení, odešle dotaz, přijme odpověď a uzavře spojení. Za upozornění stojí fakt, že třída podporuje jak verzi 1.0, tak verzi 1.1 protokolu HTTP.

Jelikož nás bude zajímat hlavně třída WebDAV, omezíme se při popisu třídy HTTP_Server jen na výčet metod a jejich krátký popis.

Metoda	Popis
konstruktor	specifikace serveru, portu a použité verze protokolu HTTP
connect	připojení k serveru prostřednictvím funkce fsockopen
close	uzavření spojení
request	odeslání dotazu klienta
response	načtení odpovědi serveru
getStatus	vrátí hodnotu stavového kódu
setHeader	nastavení hlavičky před odesláním dotazu
headerValue	vrátí hodnotu zvolené hlavičky z odpovědi serveru
getServerBody	vrátí obsah odpovědi
getServerResponse	vrátí celý obsah odpovědi (včetně hlaviček)
setClientBody	vytvoření těla dotazu (pokud je potřeba – např.: XML dokument)

Ostatní metody jsou soukromé a slouží k analýze odpovědi a jejímu rozdělení do jednotlivých částí. Detailnější popis všech metod naleznete v dokumentaci. Na závěr si ukážeme příklad použití této třídy.

Třída WebDAV

Třídu WebDAV budeme definovat jako potomka třídy HTTP_Server, přičemž názvy metod budou odpovídat názvům příkazů WebDAVu (např.: pro příkaz PROPFIND použijeme metodu propfind). Všechny metody pracují na stejném principu:

vytvoří dotaz
prostřednictvím zděděné metody connect se připojí k serveru
pomocí metody request odešlou dotaz
přijmou odpověď serveru
uzavřou spojení se serverem

Posledním krokem každé metody je reakce na hodnotu stavového kódu. Pokud vše proběhlo v pořádku, pak metody většinou vrací true. V opačném případě vrátí false a do proměnné $error uloží zprávu o chybě (většinou se jedná o text stavového hlášení).

Připojené příklady by měly dostatečně ukázat použití jednotlivých metod. Detailní popis metod můžete najít v dokumentaci třídy WebDAV.

Metody

konstruktor – parametrem konstruktoru je adresa serveru, s kterým bude třída komunikovat. Třída WebDAV používá ke komunikaci se serverem implicitně protokol HTTP ve verzi 1.1.

setDepth (příklad) – tato metoda je výjimkou mezi ostatními. Její jedinou funkcí je nastavit hodnotu proměnné $depth. Hodnotou může být jedna z konstant definovaných v souboru webdav.php: DAV_0, DAV_1 nebo DAV_INFINITY.

copy (příklad) – metoda copy slouží ke kopírování zdroje. Kromě umístění zdroje je nutné stanovit i cílové umístění (odešle se v hlavičce Destination). Třetí volitelný parametr určuje, zda se má odeslat hlavička Overwrite: F nebo ne. V případě kopírování kolekce je možné použít metodu setDepth (více WebDAV – soubory a kolekce). Pokud se vyskytla chyba při kopírování kolekce, bude do proměnné $error uložen XML dokument.

delete (příklad) – pomocí této metody smažeme specifikovaný zdroj. Za připomenutí stojí fakt, že pokud chceme smazat kolekci, může server v případě chyby (stavový kód odpovědi je 207) odeslat XML dokument, který bude opět uložen do proměnné $error.

mkcol (příklad) – metoda mkcol slouží k vytvoření prázdné kolekce.

move (příklad) – metoda move je volána se stejnými parametry jako metoda copy. Stejně jako metoda delete může i metoda move, v případě chyby při přesouvání kolekce, uložit do proměnné $error XML dokument.

propfind (příklad) – metoda propfind je první, ve které je nutné před odesláním dotazu vytvořit XML dokument. Tuto metodu lze použít třemi různými způsoby. První (pouze s jedním argumentem) vrátí XML dokument obsahující hodnoty všech vlastností. Pokud nastavíme druhý parametr na true, pak bude vrácen XML dokument obsahující pouze názvy vlastností. Zbývající dva parametry (pole názvů vlastností a asociativní pole jmenných prostorů) použijeme v případě, kdy budeme chtít zjistit hodnoty jen některých vlastností. Asociativní pole jmenných prostorů předáme metodě pouze, pokud chceme zjistit hodnotu uživatelem definovaných vlastností (více WebDAV – práce s vlastnostmi). Pole může mít například podobu: array( "R" => "http://www.server.cz/dtd/vlastnosti.dtd" ). Metoda vrací XML dokument, který je součástí odpovědi serveru.

proppatch (příklad) – metoda proppatch slouží k vytvoření/odstranění vlastností. Jelikož umožňuje obě dvě akce vykonat najednou, je možné parametry set (asociativní pole např.: array( "R:Pocasi" => "krasne pocasi" )) a remove (běžné pole) nastavit současně. Stejně jako předcházející metoda má i tato čtvrtý nepovinný parametr pro určení použitých jmenných prostorů v rámci XML dokumentu. I tato metoda vrací přijatý XML dokument.

lock (příklad) – jak název napovídá slouží tato metoda k uzamknutí souboru nebo kolekce. První dva parametry (zdroj a doba platnosti zámku) jsou povinné. Zbylé parametry (typ zámku a informace o majiteli zámku) jsou nepovinné. Metoda, pokud byl HTTP příkaz úspěšně proveden, vrátí XML dokument, který server odeslal. V opačném případě vrátí false a, jako obvykle, uloží zprávu o chybě do proměnné $error.

unlock (příklad) – odstranění zámku lze provést metodou unlock. Kromě adresy zdroje je jejím parametrem i klíč (Lock-token).

TODO

Současná verze třídy WebDAV má několik nedostatků, které znemožňují její nasazení v praxi. Některé z chybějících funkcí zobrazuje následující tabulka:

Funkce	Popis
autentifikace	chybí jakákoli podpora HTTP autentifikace, která znemožňuje plné použití zámků
XML parsery	pro jednotlivé XML dokumenty, které mohou být obsahem odpovědi serveru prozatím nejsou vytvořeny parsery
zjištění klíče	chybí metoda pro zjištění klíče (Lock-Token) k uzamknutému zdroji
informace o majiteli zámku	metoda lock by měla umožňovat uložit i jiné informace o majiteli zámku než jen url

Download

Obě třídy si můžete stáhnout. Třída WebDAV i HTTP_Server jsou dále vyvíjeny a aktualizovány. Poslední verzi spolu s aktuální dokumentací najdete na http://software.formiginal.com/webdav/index.php?page=download.

Na závěr bych rád předešel rozhořčeným příspěvkům a omluvil se za anglické komentáře v jednotlivých souborech. Doufám, že vám tento seriál umožnil nahlédnout pod pokličku WebDAVu a usnadní vám jeho využití v některých Vašich budoucích projektech.