Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
Sag === Version 0.5.0-UNRELEASED http://www.saggingcouch.com Sag is a simple PHP library for working with CouchDB. It is designed to not force any particular programming method on its users - you just pass PHP objects, and get StdClass objects and Exceptions back. This makes it trivial to incorporate Sag into your application, build different functionality on top of it, and expand Sag to incorporate new CouchDB functionality. Compatability ------------- Each Sag release is tested against CouchDB 0.11.x and 1.0.x. The majority of Sag is most likely still compatible with 0.10.x, but it's no longer tested. Contents -------- CHANGELOG A detailed list of all changes between releases. LICENSE A copy of the license that Sag is released under. README This file. src/ This is the code that you will want to include in your application. src/Sag.php This is the core file that you will include() or require() in your code. src/SagException.php The SagException class. You don't need to include it. src/SagCouchException.php The SagCouchException class. You don't need to include it. src/SagCache.php The interface that all caching mechanisms extend. src/SagFileCache.php Caching mechanism that uses the local file system. src/SagMemoryCache.php Caching mechanism that uses PHP objects in memory. Reported cache sizes are only semi-accurate, but are less important than file caching. tests/ The unit tests for Sag. You can ignore these files, though SagTests.php may be interesting for examples. Error Handling -------------- Sag's paradigm of simplicity is carried into its error handling by allowing you to send data to CouchDB that will result in errors (ex., malformed JSON). This is because CouchDB knows when there's an error better than Sag, and it would be disingenuous for Sag to try and detect errors for CouchDB. Therefore, Sag will only look for interface problems and issues that are native to PHP (ex., passing an int instead of a StdClass). All errors are floated back to your application with exceptions. Sag does not catch any errors itself, allowing your application to care about them or not. There are two types of exceptions: SagException For errors that happen within Sag, such as an invalid type being passed to a function or being unable to open a socket to the server. SagCouchException For errors generated by CouchDB (ex., if you pass it invalid JSON). The CouchDB error message will be put into the exception's message (ie., $e->getMessage()) and the HTTP status code will be the exception's code (ie., $e->getCode()). You can catch these two types of exceptions explicitly, allowing you to split your error handling depending on where the error occurred, or implicitly by simply catching the Exception class. Networking ---------- Sag uses sockets, so there is no dependency on other libraries such as cURL. If you want to monitor your application's activity on the server side (ex., if you are proxying requests to CouchDB through a web server), then examine the HTTP User-Agent header. HTTPS is currently not supported. Results ------- When you've told Sag to decode CouchDB's responses, they are stored in an object, breaking out the HTTP header lines and data. For example, running `print_r($sag->get('/1'));` (where '/1' is the location of a document) would give you something like: `` stdClass Object ( [headers] => stdClass Object ( [_HTTP] => stdClass Object ( [raw] => HTTP/1.0 200 OK [version] => 1.0 [status] => 200 ) [Server] => CouchDB/0.10.0 (Erlang OTP/R13B) [Etag] => "1-4c6114c65e295552ab1019e2b046b10e" [Date] => Mon, 12 Apr 2010 23:01:39 GMT [Content-Type] => text/plain;charset=utf-8 [Content-Length] => 68 [Cache-Control] => must-revalidate ) [body] => stdClass Object ( [_id] => 1 [_rev] => 1-4c6114c65e295552ab1019e2b046b10e [foo] => bar ) ) '' HTTP protocol information is stored in $result->headers, its headers broken out as entries in the headers array - the "_HTTP" array element holds the basic HTTP information in raw form ($result->headers->_HTTP->raw), and then broken out into HTTP version number ($result->headers->_HTTP->version) and status code ($result->headers->_HTTP->status). The $result->body property holds the raw data from CouchDB, which you can have Sag automatically decode into PHP objects with json_decode(). If you've told Sag to not decode CouchDB's responses, then it'll only return the resulting JSON from CouchDB as a string (what would have been in the body property if you had set decode to true). None of the HTTP info is included. If CouchDB specifies Set-Cookies, then they will be stored in $result->cookies as a StdClass. Functions --------- Detailed documentation of the functions and API are available at http://www.saggingcouch.com/documentation.php. License ------- Sag is released under the Apache License, version 2.0. See the file named LICENSE for more information. More? ----- See http://www.saggingcouch.com for more detailed information, bug reporting, planned features, etc.