Docblocks

evert · evert · commit 44790917f205 · 2010-02-20T10:13:44.000Z
diff --git a/lib/Sabre/CalDAV/Backend/PDO.php b/lib/Sabre/CalDAV/Backend/PDO.php
@@ -1,23 +1,59 @@
 <?php
 
+/**
+ * PDO CalDAV backend
+ *
+ * This backend is used to store calendar-data in a PDO database, such as 
+ * sqlite or MySQL
+ * 
+ * @package Sabre
+ * @subpackage CalDAV
+ * @version $Id$
+ * @copyright Copyright (C) 2007-2010 Rooftop Solutions. All rights reserved.
+ * @author Evert Pot (http://www.rooftopsolutions.nl/) 
+ * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
+ */
 class Sabre_CalDAV_Backend_PDO extends Sabre_CalDAV_Backend_Abstract {
 
+    /**
+     * pdo 
+     * 
+     * @var PDO
+     */
     private $pdo;
 
+    /**
+     * List of CalDAV properties, and how they map to database fieldnames
+     *
+     * Add your own properties by simply adding on to this array
+     * 
+     * @var array
+     */
     public $propertyMap = array(
         '{DAV:}displayname'                          => 'displayname',
         '{urn:ietf:params:xml:ns:caldav}description' => 'description',
         '{http://apple.com/ns/ical/}calendar-order'  => 'calendarorder',
         '{http://apple.com/ns/ical/}calendar-color'  => 'calendarcolor',
     );
 
-    function __construct(PDO $pdo) {
+    /**
+     * Creates the backend 
+     * 
+     * @param PDO $pdo 
+     */
+    public function __construct(PDO $pdo) {
 
         $this->pdo = $pdo;
 
     }
 
-    function getCalendarsForUser($principalUri) {
+    /**
+     * Returns a list of calendars for a principal
+     *
+     * @param string $userUri 
+     * @return array 
+     */
+    public function getCalendarsForUser($principalUri) {
 
         $fields = array_values($this->propertyMap);
         $fields[] = 'id';
@@ -46,7 +82,18 @@ function getCalendarsForUser($principalUri) {
 
     }
 
-    function createCalendar($principalUri,$calendarUri, array $properties) {
+    /**
+     * Creates a new calendar for a principal.
+     *
+     * If the creation was a success, an id must be returned that can be used to reference
+     * this calendar in other methods, such as updateCalendar
+     *
+     * @param string $principalUri
+     * @param string $calendarUri
+     * @param array $properties
+     * @return mixed
+     */
+    public function createCalendar($principalUri,$calendarUri, array $properties) {
 
         $fieldNames = array(
             'principaluri',
@@ -71,7 +118,29 @@ function createCalendar($principalUri,$calendarUri, array $properties) {
 
     }
 
-    function updateCalendar($calendarId, array $mutations) {
+    /**
+     * Updates a calendar's properties
+     *
+     *
+     * The mutations array has 3 elements for each item. The first indicates if the property
+     * is to be removed or updated (Sabre_DAV_Server::PROP_REMOVE and Sabre_DAV_Server::PROP_SET)
+     * the second is the propertyName in Clark notation, the third is the actual value (ommitted
+     * if the property is to be deleted).
+     *
+     * The result of this method should be another array. Each element has 2 subelements with the 
+     * propertyname and statuscode for the change
+     *
+     * For example:
+     *   array(array('{DAV:}prop1',200), array('{DAV:}prop2',200), array('{DAV:}prop3',403))
+     *
+     * The default implementation does not allow any properties to be updated, and thus
+     * will return 403 for each one.
+     *
+     * @param string $calendarId
+     * @param array $mutations
+     * @return array 
+     */
+    public function updateCalendar($calendarId, array $mutations) {
 
         $values = array();
 
@@ -113,7 +182,13 @@ function updateCalendar($calendarId, array $mutations) {
 
     }
 
-    function deleteCalendar($calendarId) {
+    /**
+     * Delete a calendar and all it's objects 
+     * 
+     * @param string $calendarId 
+     * @return void
+     */
+    public function deleteCalendar($calendarId) {
 
         $stmt = $this->pdo->prepare('DELETE FROM calendarobjects WHERE calendarid = ?');
         $stmt->execute(array($calendarId));
@@ -123,37 +198,73 @@ function deleteCalendar($calendarId) {
 
     }
 
-    function getCalendarObjects($calendarId) {
+    /**
+     * Returns all calendar objects within a calendar object. 
+     * 
+     * @param string $calendarId 
+     * @return array 
+     */
+    public function getCalendarObjects($calendarId) {
 
         $stmt = $this->pdo->prepare('SELECT * FROM calendarobjects WHERE calendarid = ?');
         $stmt->execute(array($calendarId));
         return $stmt->fetchAll();
 
     }
 
-    function getCalendarObject($calendarId,$objectUri) {
+    /**
+     * Returns information from a single calendar object, based on it's object uri. 
+     * 
+     * @param string $calendarId 
+     * @param string $objectUri 
+     * @return array 
+     */
+    public function getCalendarObject($calendarId,$objectUri) {
 
         $stmt = $this->pdo->prepare('SELECT * FROM calendarobjects WHERE calendarid = ? AND uri = ?');
         $stmt->execute(array($calendarId, $objectUri));
         return $stmt->fetch();
 
     }
 
-    function createCalendarObject($calendarId,$objectUri,$calendarData) {
+    /**
+     * Creates a new calendar object. 
+     * 
+     * @param string $calendarId 
+     * @param string $objectUri 
+     * @param string $calendarData 
+     * @return void
+     */
+    public function createCalendarObject($calendarId,$objectUri,$calendarData) {
 
         $stmt = $this->pdo->prepare('INSERT INTO calendarobjects (calendarid, uri, calendardata, lastmodified) VALUES (?,?,?,?)');
         $stmt->execute(array($calendarId,$objectUri,$calendarData,time()));
 
     }
 
-    function updateCalendarObject($calendarId,$objectUri,$calendarData) {
+    /**
+     * Updates an existing calendarobject, based on it's uri. 
+     * 
+     * @param string $calendarId 
+     * @param string $objectUri 
+     * @param string $calendarData 
+     * @return void
+     */
+    public function updateCalendarObject($calendarId,$objectUri,$calendarData) {
 
         $stmt = $this->pdo->prepare('UPDATE calendarobjects SET calendardata = ?, lastmodified = ? WHERE calendarid = ? AND uri = ?');
         $stmt->execute(array($calendarData,time(),$calendarId,$objectUri));
 
     }
 
-    function deleteCalendarObject($calendarId,$objectUri) {
+    /**
+     * Deletes an existing calendar object. 
+     * 
+     * @param string $calendarId 
+     * @param string $objectUri 
+     * @return void
+     */
+    public function deleteCalendarObject($calendarId,$objectUri) {
 
         $stmt = $this->pdo->prepare('DELETE FROM calendarobjects WHERE calendarid = ? AND uri = ?');
         $stmt->execute(array($calendarId,$objectUri));
diff --git a/lib/Sabre/CalDAV/Plugin.php b/lib/Sabre/CalDAV/Plugin.php
@@ -15,15 +15,26 @@
  */
 class Sabre_CalDAV_Plugin extends Sabre_DAV_ServerPlugin {
 
+    /**
+     * This is the official CalDAV namespace
+     */
     const NS_CALDAV = 'urn:ietf:params:xml:ns:caldav';
 
+    /**
+     * The following constants are used to differentiate
+     * the various filters for the calendar-query report
+     */
     const FILTER_COMPFILTER   = 1;
     const FILTER_ISNOTDEFINED = 2;
     const FILTER_TIMERANGE    = 3;
     const FILTER_PROPFILTER   = 4;
     const FILTER_PARAMFILTER  = 5;
     const FILTER_TEXTMATCH    = 6;
 
+    /**
+     * The hardcoded root for calendar objects. It is unfortunate
+     * that we're stuck with it, but it will have to do for now
+     */
     const CALENDAR_ROOT = 'calendars';
 
     /**
@@ -316,6 +327,15 @@ public function calendarQueryReport($dom) {
     }
 
 
+    /**
+     * This function parses the calendar-query report request body
+     *
+     * The body is quite complicated, so we're turning it into a PHP
+     * array.
+     * 
+     * @param DOMNode $domNode 
+     * @return array 
+     */
     protected function parseFilters($domNode) {
 
         $filters = array();
@@ -388,6 +408,16 @@ protected function parseFilters($domNode) {
 
     }
 
+    /**
+     * Verify if a list of filters applies to the calendar data object 
+     *
+     * The calendarData object must be a valid iCalendar blob. The list of 
+     * filters must be formatted as parsed by Sabre_CalDAV_Plugin::parseFilters
+     *
+     * @param string $calendarData 
+     * @param array $filters 
+     * @return bool 
+     */
     protected function validateFilters($calendarData,$filters) {
 
         // We are converting the calendar object to an XML structure
@@ -399,6 +429,16 @@ protected function validateFilters($calendarData,$filters) {
         
     }
 
+    /**
+     * This function is simply used by validateFilters 
+     *
+     * A separete function was needed, because it nees to be a recursive function 
+     *
+     * @param SimpleXMLElement $xNode 
+     * @param array $filters 
+     * @param string $xpath 
+     * @return bool 
+     */
     protected function validateXMLFilters($xNode,$filters,$xpath = '/c:iCalendar') {
 
         foreach($filters as $filter) {
diff --git a/lib/Sabre/CalDAV/Property/SupportedCalendarComponentSet.php b/lib/Sabre/CalDAV/Property/SupportedCalendarComponentSet.php
@@ -1,16 +1,50 @@
 <?php
 
+/**
+ * Sabre_CalDAV_Property_SupportedCalendarComponentSet
+ *
+ * @package Sabre
+ * @version $Id$
+ * @copyright Copyright (C) 2007-2010 Rooftop Solutions. All rights reserved.
+ * @author Evert Pot (http://www.rooftopsolutions.nl/) 
+ * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
+ */
+
+/**
+ * Supported component set property
+ *
+ * This property is a representation of the supported-component-set property
+ * in the CalDAV namespace. It simply requires an array of components, such as
+ * VEVENT, VTODO
+ */
 class Sabre_CalDAV_Property_SupportedCalendarComponentSet extends Sabre_DAV_Property {
 
+    /**
+     * components 
+     * 
+     * @var array 
+     */
     private $components;
 
-    function __construct(array $components) {
+    /**
+     * Creates the property 
+     * 
+     * @param array $components 
+     */
+    public function __construct(array $components) {
 
        $this->components = $components; 
 
     }
     
-    function serialize(Sabre_DAV_Server $server,DOMElement $node) {
+    /**
+     * Serializes the property in a DOMDocument 
+     * 
+     * @param Sabre_DAV_Server $server 
+     * @param DOMElement $node 
+     * @return void
+     */
+    public function serialize(Sabre_DAV_Server $server,DOMElement $node) {
 
        $doc = $node->ownerDocument;
        foreach($this->components as $component) {
diff --git a/lib/Sabre/CalDAV/Property/SupportedCalendarData.php b/lib/Sabre/CalDAV/Property/SupportedCalendarData.php
@@ -1,8 +1,32 @@
 <?php
 
+/**
+ * Sabre_CalDAV_Property_SupportedCalendarData
+ *
+ * @package Sabre
+ * @version $Id$
+ * @copyright Copyright (C) 2007-2010 Rooftop Solutions. All rights reserved.
+ * @author Evert Pot (http://www.rooftopsolutions.nl/) 
+ * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
+ */
+
+/**
+ * supported-calendar-data property
+ *
+ * This property is a representation of the supported-calendar-data property
+ * in the CalDAV namespace. SabreDAV only has support for text/calendar;2.0
+ * so the value is currently hardcoded.
+ */
 class Sabre_CalDAV_Property_SupportedCalendarData extends Sabre_DAV_Property {
 
-    function serialize(Sabre_DAV_Server $server,DOMElement $node) {
+    /**
+     * Serializes the property in a DOMDocument 
+     * 
+     * @param Sabre_DAV_Server $server 
+     * @param DOMElement $node 
+     * @return void
+     */
+    public function serialize(Sabre_DAV_Server $server,DOMElement $node) {
 
         $doc = $node->ownerDocument;
 
@@ -13,7 +37,6 @@ function serialize(Sabre_DAV_Server $server,DOMElement $node) {
         $caldata->setAttribute('version','2.0');
 
         $node->appendChild($caldata); 
-
     }
 
 }
diff --git a/lib/Sabre/CalDAV/Property/SupportedCollationSet.php b/lib/Sabre/CalDAV/Property/SupportedCollationSet.php
