From 6a3851bae272ae3d1f406095c3f97a4bdbd089eb Mon Sep 17 00:00:00 2001
From: Bharat Mediratta <bharat@menalto.com>
Date: Tue, 26 Jan 2010 00:15:35 -0800
Subject: [PATCH] Refactored the API to deal with relationships and data in
 general more cleanly.  Unfortunately it makes resource data access a lot more
 unwieldy so I don't think we're done yet.

---
 client/Gallery3.php | 159 +++++++++++++-------------------------------
 client/example.php  | 100 ++++++++++++++++------------
 2 files changed, 105 insertions(+), 154 deletions(-)

diff --git a/client/Gallery3.php b/client/Gallery3.php
index 8d173150..7fe63ff0 100644
--- a/client/Gallery3.php
+++ b/client/Gallery3.php
@@ -25,14 +25,9 @@ class Gallery3 {
   var $url;
   var $token;
   var $data;
-  var $changed_data;
   var $file;
-  var $parent;
 
-  public function __construct() {
-    $this->data = new stdClass();
-    $this->changed_data = new stdClass();
-  }
+  protected $original_resource;
 
   /**
    * Connect to a remote Gallery3 instance
@@ -40,84 +35,52 @@ class Gallery3 {
    * @param   string Gallery 3 API url, eg http://example.com/gallery3/index.php/rest
    * @param   string username
    * @param   string password
-   * @return  object Gallery3
+   * @return  string authentication token
    */
-  static function connect($url, $user, $pass) {
+  static function login($url, $user, $pass) {
     $response = Gallery3_Helper::request(
       "post", $url, null, array("user" => $user, "password" => $pass));
-
-    return self::factory($url, $response, null);
+    return $response;
   }
 
   /**
-   * Create a new Gallery3 instance associated with a remote resource
-   * @param string   the url
-   * @param string   security token
-   * @param object   parent object
-   * @return object  Gallery3
+   * Construct a new Gallery3 instance associated with a remote resource
+   * @param   string remote url
+   * @param   string authentication token
+   * @return  object Gallery3
    */
-  static function factory($url, $token, $parent) {
-    $resource = new Gallery3();
-    $resource->url = $url;
-    $resource->token = $token;
-    $resource->parent = $parent;
-    return $resource;
-  }
-
-  /**
-   * Retrieve a remote resource, by url.
-   *
-   * @param string   the path relative to the current resource
-   * @return object  Gallery3
-   */
-  public function get($relative_path, $params=array()) {
-    $query = "";
-    if ($params) {
-      foreach ($params as $key => $value) {
-        $query[] = rawurlencode($key) . "=" . rawurlencode($value);
-      }
-      if ($query) {
-        $query = "?" . join("&", $query);
-      }
+  public function factory($url=null, $token=null) {
+    $obj = new Gallery3();
+    $obj->token = $token;
+    $obj->url = $url;
+    if ($url && $token) {
+      $obj->load();
     }
-
-    return self::factory("$this->url/$relative_path$query", $this->token, $this)->load();
+    return $obj;
   }
 
   /**
-   * Set a value on the remote resource
+   * Constructor.
+   */
+  public function __construct() {
+    $this->data = new stdClass();
+    $this->token = null;
+    $this->url = null;
+  }
+
+  /**
+   * Set a value on the remote resource.  You must call save for it to take effect.
    *
    * @param string   key
    * @param string   value
    * @return object  Gallery3
+   * @chainable
    */
-  public function set_value($key, $value) {
-    $this->changed_data->$key = $value;
+  public function set($key, $value) {
+    $this->data->resource->$key = $value;
     return $this;
   }
 
-  /**
-   * Get a value from the remote resource.
-   *
-   * @param string   $key
-   * @return string  value
-   */
-  public function __get($key) {
-    if (property_exists($this->changed_data, $key)) {
-      return $this->changed_data->$key;
-    }
-    return $this->data->$key;
-  }
-
-  /**
-   * Get the list of members from the remote resource
-   *
-   * @return array  member urls
-   */
-  public function members() {
-    return $this->members;
-  }
-
   /**
    * Attach a file to the remote resource.
    *
@@ -130,30 +93,30 @@ class Gallery3 {
   }
 
   /**
-   * Add a new member to a collection.  You must call save() for it to be created in the
-   * remote Gallery 3.
+   * Save any local changes made to this resource.  If this is an existing resource, we'll return
+   * the resource itself.  If we're creating a new resource, return the newly created resource.
    *
    * @return object  Gallery3
    */
-  public function add() {
-    return Gallery3::factory(null, $this->token, $this);
+  public function create($url, $token) {
+    $response = Gallery3_Helper::request(
+      "post", $url, $token, $this->data->resource, $this->file);
+    $this->url = $response->url;
+    $this->token = $token;
+    return $this->load();
   }
 
   /**
-   * Save any local changes made to this resource.
+   * Save any local changes made to this resource.  If this is an existing resource, we'll return
+   * the resource itself.  If we're creating a new resource, return the newly created resource.
    *
    * @return object  Gallery3
    */
   public function save() {
-    if ($this->url) {
-      $response = Gallery3_Helper::request("put", $this->url, $this->token, $this->changed_data);
-    } else {
-      $response = Gallery3_Helper::request(
-        "post", $this->parent->url, $this->token, $this->changed_data, $this->file);
-      $this->parent->load();
-    }
-
-    return $this->load(!empty($response->url) ? $response->url : null);
+    $response = Gallery3_Helper::request(
+      "put", $this->url, $this->token,
+      array_diff($this->original_resource, (array)$this->data->resource));
+    return $this->load();
   }
 
   /**
@@ -163,47 +126,21 @@ class Gallery3 {
    */
   public function delete() {
     Gallery3_Helper::request("delete", $this->url, $this->token);
-    $this->reset();
-  }
-
-  /**
-   * Remove a member from the remote collection.
-   *
-   * @return object  Gallery3
-   */
-  public function remove($url) {
-    Gallery3_Helper::request("delete", $this->url, $this->token, array("url" => $url));
-    $this->load();
+    $this->data = array();
+    $this->url = null;
+    return $this;
   }
 
   /**
    * Reload the resource from a given url.  This is useful after the remote resource has been
    * modified.
    *
-   * @param  string   optional url, only necessary if the url changes.
    * @return object   Gallery3
    */
-  protected function load($url=null) {
-    if ($url) {
-      $this->url = $url;
-    }
+  public function load() {
     $response = Gallery3_Helper::request("get", $this->url, $this->token);
-
-    $this->data = isset($response->resource) ? $response->resource : new stdClass();
-    $this->members = isset($response->members) ? $response->members : array();
-    $chis->changed_data = new stdClass();
-    return $this;
-  }
-
-  /**
-   * Reset all data for this reference, essentially disconnecting it from the remote resource.
-   *
-   * @return object   Gallery3
-   */
-  protected function reset() {
-    $this->data = array();
-    $this->changed_data = array();
-    $this->url = null;
+    $this->data = $response;
+    $this->original_resource = (array)$response->resource;
     return $this;
   }
 }
diff --git a/client/example.php b/client/example.php
index 2b37a25f..db8c8712 100644
--- a/client/example.php
+++ b/client/example.php
@@ -10,65 +10,79 @@ if (file_exists("local_config.php")) {
 }
 
 alert("Connect to $SITE_URL");
-$gallery3 = Gallery3::connect($SITE_URL, $USER, $PASSWORD);
-$root = $gallery3->get("gallery");
-$tags = $gallery3->get("tags");
+$auth = Gallery3::login($SITE_URL, $USER, $PASSWORD);
+$root = Gallery3::factory("$SITE_URL/item/1", $auth);
+$tags = Gallery3::factory("$SITE_URL/tags", $auth);
 
-alert("Create a tag");
-$tag = $tags->add()
-  ->set_value("name", "My Tag")
+
+$tag = Gallery3::factory()
+  ->set("name", "My Tag")
+  ->create($tags->url, $auth);
+alert("Created tag: <b>{$tag->url}</b>");
+
+
+$album = Gallery3::factory()
+  ->set("type", "album")
+  ->set("name", "Sample Album")
+  ->set("title", "This is my Sample Album")
+  ->create($root->url, $auth);
+alert("Created album: <b>{$album->url} {$album->data->resource->title}</b>");
+
+
+alert("Modify the album");
+$album
+  ->set("title", "This is the new title")
   ->save();
+alert("New title: <b>{$album->data->resource->title}</b>");
 
-alert("Create a new album");
-$album = $root->add()
-  ->set_value("type", "album")
-  ->set_value("name", "Sample Album")
-  ->set_value("title", "This is my Sample Album")
-  ->save();
 
-alert("Upload a photo");
-$photo = $album->add()
-  ->set_value("type", "photo")
-  ->set_value("name", "Sample Photo.jpg")
-  ->set_value("title", "Sample Photo")
+$photo = Gallery3::factory()
+  ->set("type", "photo")
+  ->set("name", "Sample Photo.jpg")
+  ->set("title", "Sample Photo")
   ->set_file("/tmp/foo.jpg")
-  ->save();
-alert("Added: " . $album->members[0] . "");
+  ->create($album->url, $auth);
+alert("Uploaded photo: <b>{$photo->url}</b>");
+alert("Album members: <b>" . join(", ", $album->data->members) . "</b>");
+
 
 alert("Search for the photo");
-$photos = $root->get("", array("name" => "Sample"));
-alert("Found: {$photos->members[0]}");
+$photos = Gallery3::factory($root->url, $auth)
+  ->set("name", "Sample")
+  ->load();
+alert("Found: {$photos->data->members[0]}");
+
 
 alert("Grab a random photo");
-$photos = $root->get("", array("random" => "true"));
-alert("Found: {$photos->members[0]}");
+$photos = Gallery3::factory($root->url, $auth)
+  ->set("random", "true")
+  ->load();
+alert("Found: {$photos->data->members[0]}");
 
-alert("Tag the album");
-$tag->add()
-  ->set_value("url", $album->url)
-  ->save();
 
-alert("Tag the photo");
-$tag->add()
-  ->set_value("url", $photo->url)
-  ->save();
-alert("Tagged items: " . join($tag->members, " "));
+alert("Tag the album (using the album's relationships: {$album->data->relationships->tags->url})");
+$tag_relationship1 = Gallery3::factory()
+  ->set("tag", $tag->url)
+  ->set("item", $root->url)
+  ->create($album->data->relationships->tags->url, $auth);
+alert("Tag: {$tag_relationship1->url}");
+
+
+alert("Tag the photo (using the tag's relationships: {$tag->data->relationships->items->url})");
+$tag_relationship2 = Gallery3::factory()
+  ->set("tag", $tag->url)
+  ->set("item", $photo->url)
+  ->create($tag->data->relationships->items->url, $auth);
+alert("Tag: {$tag_relationship2->url}");
 
 alert("Un-tag the photo");
-$tag->remove($photo->url);
-alert("Tagged items: " . join($tag->members, " "));
+$tag_relationship2->delete();
+$tag->load();
+alert("1 remaining tag: <b>{$tag->data->relationships->items->members[0]}</b>");
 
-alert("Find and modify the album");
-$album = $root->get("Sample-Album")
-  ->set_value("title", "This is my title")
-  ->save();
-alert("New title: $album->title");
 
-// Now delete the album
-alert("Delete the album");
+alert("Delete the album and tag");
 $album->delete();
-
-// Delete the tag
 $tag->delete();
 
 alert("Done!");