Add Starred API, revised Watchers API and Improved Docs

doc/activity.md

@@ -0,0 +1,94 @@
+## Activity API (incomplete)
+[Back to the navigation](index.md)
+
+Access to Starring and Watching a Repository for [non] authenticated users.
+Wrap [GitHub Activity API](https://developer.github.com/v3/activity/).
+
+> *** No authentication required. ***
+
+### Get repos that a specific user has starred
+
+```php
+$users = $client->api('user')->starred('ornicar');
+```
+
+Returns an array of starred repos.
+
+### Get repos that a specific user is watching
+
+```php
+$users = $client->api('user')->watched('ornicar');
+```
+
+Returns an array of watched repos.
+
+> *** Requires [authentication](security.md). ***
+
+### Get repos that a authenticated user has starred
+
+```php
+$activity = $client->api('current_user')->starred()->all();
+```
+Returns an array of starred repos.
+
+### Check if authenticated user has starred a specific repo
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->starred()->check($owner, $repo);
+```
+Throws an Exception with code 404 in case that the repo is not starred by the authenticated user or NULL in case that it is starred by the authenticated user.
+
+### Star a specific repo for authenticated user
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->starred()->star($owner, $repo);
+```
+Throws an Exception in case of failure or NULL in case of success.
+
+### Unstar a specific repo for authenticated user
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->starred()->unstar($owner, $repo);
+```
+Throws an Exception in case of failure or NULL in case of success.
+
+
+### Get repos that a authenticated user is watching
+
+```php
+$activity = $client->api('current_user')->watchers()->all();
+```
+Returns an array of watched repos.
+
+### Check if authenticated user is watching a specific repo
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->watchers()->check($owner, $repo);
+```
+Throws an Exception with code 404 in case that the repo is not beeing watched by the authenticated user or NULL in case that it is beeing watched by the authenticated user.
+
+### Watch a specific repo for authenticated user
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->watchers()->watch($owner, $repo);
+```
+Throws an Exception in case of failure or NULL in case of success.
+
+### Stop watching a specific repo for authenticated user
+
+```php
+$owner = "KnpLabs";
+$repo = "php-github-api";
+$activity = $client->api('current_user')->watchers()->unwatch($owner, $repo);
+```
+Throws an Exception in case of failure or NULL in case of success.

doc/index.md

@@ -20,6 +20,7 @@ APIs:
     * [Assets](repo/assets.md)
 * [Users](users.md)
 * [Meta](meta.md)
+* [Activity](activity.md)
 
 Additional features:
 

doc/users.md

@@ -108,12 +108,24 @@ $client->api('current_user')->follow()->unfollow('symfony');
 Returns an array of followed users.
 
 ### Get repos that a specific user is watching
+> See [more](activity.md).
 
 ```php
 $users = $client->api('user')->watched('ornicar');
 ```
 
+For authenticated user use.
+
+> Requires [authentication](security.md).
+
+```php
+$users = $client->api('current_user')->watchers()->all();
+```
+
+Returns an array of watched repos.
+
 ### Get repos that a specific user has starred
+> See [more](activity.md).
 
 ```php
 $users = $client->api('user')->starred('ornicar');
@@ -124,10 +136,10 @@ For authenticated user use.
 > Requires [authentication](security.md).
 
 ```php
-$users = $client->api('current_user')->watched();
+$users = $client->api('current_user')->starred()->all();
 ```
 
-Returns an array of watched repos.
+Returns an array of starred repos.
 
 ### Get the authenticated user emails
 

lib/Github/Api/CurrentUser.php

@@ -7,10 +7,12 @@
 use Github\Api\CurrentUser\Followers;
 use Github\Api\CurrentUser\Notifications;
 use Github\Api\CurrentUser\Watchers;
+use Github\Api\CurrentUser\Starred;
 
 /**
  * @link   http://developer.github.com/v3/users/
  * @author Joseph Bielawski <[email protected]>
+ * @revised Felipe Valtl de Mello <[email protected]>
  */
 class CurrentUser extends AbstractApi
 {
@@ -111,21 +113,22 @@ public function watchers()
     {
         return new Watchers($this->client);
     }
-
+
+    /**
+     * @Deprecated
+     */
     public function watched($page = 1)
     {
         return $this->get('user/watched', array(
             'page' => $page
         ));
     }
 
-    /**
-     *  @link http://developer.github.com/changes/2012-9-5-watcher-api/
+   /**
+     * @return Starred
      */
-    public function starred($page = 1)
+    public function starred()
     {
-        return $this->get('user/starred', array(
-            'page' => $page
-        ));
+         return new Starred($this->client);
     }
 }

lib/Github/Api/CurrentUser/Starred.php

@@ -0,0 +1,65 @@
+<?php
+
+namespace Github\Api\CurrentUser;
+
+use Github\Api\AbstractApi;
+
+/**
+ * @link   https://developer.github.com/v3/activity/starring/
+ * @author Felipe Valtl de Mello <[email protected]>
+ */
+class Starred extends AbstractApi
+{
+    /**
+     * List repositories starred by the authenticated user
+     * @link https://developer.github.com/v3/activity/starring/
+     *
+     * @param  integer $page
+     * @return array
+     */
+    public function all($page = 1)
+    {
+        return $this->get('user/starred', array(
+            'page' => $page
+        ));
+    }
+
+    /**
+     * Check that the authenticated user starres a repository
+     * @link https://developer.github.com/v3/activity/starring/
+     *
+     * @param  string $username   the user who owns the repo
+     * @param  string $repository the name of the repo
+     * @return array
+     */
+    public function check($username, $repository)
+    {
+        return $this->get('user/starred/'.rawurlencode($username).'/'.rawurlencode($repository));
+    }
+
+    /**
+     * Make the authenticated user star a repository
+     * @link https://developer.github.com/v3/activity/starring/
+     *
+     * @param  string $username   the user who owns the repo
+     * @param  string $repository the name of the repo
+     * @return array
+     */
+    public function star($username, $repository)
+    {
+        return $this->put('user/starred/'.rawurlencode($username).'/'.rawurlencode($repository));
+    }
+
+    /**
+     * Make the authenticated user unstar a repository
+     * @link https://developer.github.com/v3/activity/starring
+     *
+     * @param  string $username   the user who owns the repo
+     * @param  string $repository the name of the repo
+     * @return array
+     */
+    public function unstar($username, $repository)
+    {
+        return $this->delete('user/starred/'.rawurlencode($username).'/'.rawurlencode($repository));
+    }
+}

lib/Github/Api/CurrentUser/Watchers.php

@@ -5,61 +5,62 @@
 use Github\Api\AbstractApi;
 
 /**
- * @link   http://developer.github.com/v3/repos/watching/
+ * @link   https://developer.github.com/v3/activity/watching/
  * @author Joseph Bielawski <[email protected]>
+ * @revised Felipe Valtl de Mello <[email protected]>
  */
 class Watchers extends AbstractApi
 {
     /**
      * List repositories watched by the authenticated user
-     * @link http://developer.github.com/v3/repos/watching/
+     * @link https://developer.github.com/v3/activity/watching/
      *
      * @param  integer $page
      * @return array
      */
     public function all($page = 1)
     {
-        return $this->get('user/watched', array(
+        return $this->get('user/subscriptions', array(
             'page' => $page
         ));
     }
 
     /**
      * Check that the authenticated user watches a repository
-     * @link http://developer.github.com/v3/repos/watching/
+     * @link https://developer.github.com/v3/activity/watching/
      *
      * @param  string $username   the user who owns the repo
      * @param  string $repository the name of the repo
      * @return array
      */
     public function check($username, $repository)
     {
-        return $this->get('user/watched/'.rawurlencode($username).'/'.rawurlencode($repository));
+        return $this->get('user/subscriptions/'.rawurlencode($username).'/'.rawurlencode($repository));
     }
 
     /**
      * Make the authenticated user watch a repository
-     * @link http://developer.github.com/v3/repos/watching/
+     * @link https://developer.github.com/v3/activity/watching/
      *
      * @param  string $username   the user who owns the repo
      * @param  string $repository the name of the repo
      * @return array
      */
     public function watch($username, $repository)
     {
-        return $this->put('user/watched/'.rawurlencode($username).'/'.rawurlencode($repository));
+        return $this->put('user/subscriptions/'.rawurlencode($username).'/'.rawurlencode($repository));
     }
 
     /**
      * Make the authenticated user unwatch a repository
-     * @link http://developer.github.com/v3/repos/watching/
+     * @link https://developer.github.com/v3/activity/watching/
      *
      * @param  string $username   the user who owns the repo
      * @param  string $repository the name of the repo
      * @return array
      */
     public function unwatch($username, $repository)
     {
-        return $this->delete('user/watched/'.rawurlencode($username).'/'.rawurlencode($repository));
+        return $this->delete('user/subscriptions/'.rawurlencode($username).'/'.rawurlencode($repository));
     }
 }

test/Github/Tests/Api/CurrentUser/StarredTest.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Github\Tests\Api;
+
+use Github\Tests\Api\TestCase;
+
+class StarredTest extends TestCase
+{
+    /**
+     * @test
+     */
+    public function shouldGetStarred()
+    {
+        $expectedValue = array(
+            array('name' => 'l3l0/test'),
+            array('name' => 'cordoval/test')
+        );
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('user/starred')
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->all());
+    }
+
+    /**
+     * @test
+     */
+    public function shouldCheckStar()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('user/starred/l3l0/test')
+            ->will($this->returnValue(null));
+
+        $this->assertNull($api->check('l3l0', 'test'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldStarUser()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('put')
+            ->with('user/starred/l3l0/test')
+            ->will($this->returnValue(null));
+
+        $this->assertNull($api->star('l3l0', 'test'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldUnstarUser()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('delete')
+            ->with('user/starred/l3l0/test')
+            ->will($this->returnValue(null));
+
+        $this->assertNull($api->unstar('l3l0', 'test'));
+    }
+
+    protected function getApiClass()
+    {
+        return 'Github\Api\CurrentUser\Starred';
+    }
+}