include/HTTP_WebDAV_Server/dav.txt

   1 The HTTP_WebDAV_Server class provides a framwork for the
   2 implementation of customized WebDAV servers that can provide
   3 filesystem like access to almost any kind of hierachically stored
   4 data.
   5
   6 The (abstract) server base class tries to encapsulate as much of
   7 the protocol details as possible. It takes care of the needed WebDAV
   8 header and XML payload parsing and generation (and knows about some
   9 of the problems with common clients and tries hard to work around
  10 them).
  11
  12 WebDAV itself is an extension to the HTTP protocol. The HTTP
  13 specific parts of it are already taken care of by the web server. Any
  14 data needed by the server class is provided by the PHP SAPI interface
  15 of the server used.
  16
  17 To create a working server from the base class you have to extend and
  18 add methods for the actual access, modification and access control of
  19 your own data.
  20
  21 You may use the included HTTP_WebDAV_Server_Filesystem class as an
  22 example of how to create a working server. This sample implementation
  23 is used for testing the implementation of this package against the
  24 litmus WebDAV compliance test suite.
  25 (litmus is available on http://www.webdav.org/neon/litmus)
  26
  27 The methods you can add in your extended class are mostly named after
  28 the WebDAV specific request methods (using upper case names). Methods
  29 you may implement are:
  30
  31 * GET()                           get a resource from the server
  32 * HEAD()                                get resource headers only from the server
  33 * PUT()         create or modify a resource on the server
  34 * COPY()        copy a resource on the server
  35 * MOVE()        move a resource on the server
  36 * DELETE()      delete a resource on the server
  37 * MKCOL()       create a new collection
  38 * PROPFIND()    get property data for a resource
  39 * PROPPATCH()   modify property data for a resource
  40 * LOCK()        lock a resource
  41 * UNLOCK()      unlock a locked resource
  42 * checklock()   check whether a resource is locked
  43 * check_auth()  check authentication
  44
  45 You can think of WebDAV resources as files, collections as directories
  46 and properties as filesystem meta data (like size, creation date, ...).
  47
  48 The base class is able identify which of the methods you have
  49 implemented and will create appropriate answers to OPTIONS requests
  50 that ask for the WebDAV standards compliance level and the allowed
  51 HTTP methods for you.
  52
  53 For a minimal working test server you need to implement GET(), PUT()
  54 and PROPFIND() only.
  55
  56 For a minimal (level 1) standards compliant server you also need to
  57 implement MKCOL(), DELETE(), and PROPPATCH(). The COPY(), MOVE() and
  58 HEAD() methods are emulated using GET(), PUT() and DELETE() if not
  59 implemented, but for performance reasons you should better implement
  60 them yourself.
  61
  62 For a complete (level 2) RFC2518 compliand server you also have to
  63 provide locking support by implementing LOCK(), UNLOCK() and
  64 checklock().
  65
  66 Authentication is not really part of the WebDAV specification and
  67 should be handled on the HTTP level. You can do so by means of, for
  68 example, .htaccess files or similar services provided by your web
  69 server. But you can also make use of the authentication features
  70 offered by PHP by implementing the check_auth() method.
  71 Using the check_auth() method you can create a dynamic interface
  72 to any authentication system protecting the data you want to serve.
  73
  74
  75 <WARNING>
  76   the following reference information may be outdated and/or
  77   incomplete ...
  78 </WARNING>
  79
  80 bool PROPINFO($options, &$files)
  81
  82   options[path]  - Resource-Path
  83   options[depth] - Depth of search requested: "0", "1", or "infinity"
  84   options[props] - "all", "names", or an arry of requested properties
  85                    each property array element is either a string
  86                    (which implies the default "DAV:" namespace) or
  87                    an array with the two elements "name" and "xmlns"
  88                    for the properties name and XML namespace
  89
  90   &$files - storage array for property results with the following elements:
  91
  92           "files" -> array of found properties forresources. elements are:
  93
  94                "path" -> path of the resource
  95                "props" -> properties array
  96                                                                     each property array element is either a string
  97                                                                                                   (which implies the default "DAV:" namespace) or
  98                           an array with the two elements "name" and "xmlns"
  99                           for the properties name and XML namespace
 100
 101                           you should at least support the following
 102                           list of properties from the "DAV:" namespave:
 103
 104                           - resourcetype:     "collection" oder ""
 105                           - creationdate:     unix-timestamp
 106                           - getcontentlength: integer
 107                           - getlastmodified:  unix-timestamp
 108
 109                                                                                                         You may want to add support for these "DAV:"
 110                                                                                                         properties, too:
 111
 112                           - getcontenttype:   mime-type
 113                           - displayname:      string
 114
 115                           for a compliant server you also have to be
 116                           able to return any property from other
 117                           namespaces that has been stored using
 118                           PROPPATCH
 119
 120
 121   return-value: true / false
 122
 123
 124
 125
 126 string MKCOL($option)
 127
 128   options[path] - path of the new collection to be created
 129
 130   return-value: string
 131                 HTTP status and status message, possible values are
 132                 * 201 Success
 133                 * 403 Forbidden
 134                 * 405 Method not allowed
 135                 * 409 Conflict
 136                 * 415 Unsupported media type
 137                 * 507 Insufficient Storage
 138                 (see also RFC2518 8.3.2)
 139
 140
 141
 142
 143 string GET(&$options)
 144
 145   $options['path']   - path to the requested resource
 146   $options['ranges'] - optional array of range specifications for
 147                        partial access. range specs are arrays that
 148                        consist of either a 'start' and 'end' element
 149                        (where 'end' can be empty to indicate a request
 150                        up to the actual end of the resource) or a
 151                        'last' element to access the last n bytes of
 152                                                                                          a resource without knowing its actual size in
 153                        advance
 154
 155   Return-value: true bei Erfolg, false wenn not found
 156
 157   (TODO: andere stati berücksichtigen)
 158
 159   Content-Type, Content-Length header müssen von der Methode selbst
 160   erzeugt werden  (TODO: outdated)
 161
 162
 163
 164
 165 string PUT($options)
 166
 167   options[path] - path to the requested resource
 168   options[content_length] - size of request data in bytes
 169   options[stream] - a PHP stream providing the input data
 170
 171   return-value: string
 172                 HTTP status, possible values are:
 173                                                                 * 201 Created    -> the resource did not exist before
 174                                     and has been successfully created
 175                 * 204 No Content -> a previously existing resource has
 176                                     successfully been modified
 177                 * 409 Conflict
 178                 ...
 179
 180
 181
 182
 183 string COPY($options)
 184
 185   options[path]      - path to the resource to be copied
 186   options[depth]     - "0" or "infinity" (applies only to directories)
 187   options[overwrite] - true / false
 188   options[dest]      - path to the destination resource if local
 189   options[dest_url]  - non-local destination path
 190
 191   return-value: string
 192                 HTTP status, see RFC2518 8.8.5
 193
 194
 195
 196
 197
 198 string MOVE($options)
 199
 200   options[path]      - path to the resource to be moved
 201   options[overwrite] - true / false
 202   options[dest]      - path to the destination resource if local
 203   options[dest_url]  - non-local destination path
 204
 205   return-value: string
 206                 HTTP status, see RFC2518 8.9.4
 207
 208
 209
 210
 211 string DELETE($options)
 212
 213   options[path] - path to the resource to be removed
 214
 215   return-value: string
 216                 HTTP status, see RFC2518 8.6.2
 217
 218
 219
 220
 221
 222 bool check_auth($type, $user, $passwd)
 223
 224   $type: HTTP-Auth type, i.A. "Basic"
 225   $user: HTTP Username
 226   $passwd: HTTP Passwort
 227
 228   return-value: true bei success, sonst false
 229   (ToDo: array mit Auth-Type und Realm String zulassen bei fehler)