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')->starring()->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')->starring()->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')->starring()->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')->starring()->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')->starring()->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\Starring;
 
 /**
  * @link   http://developer.github.com/v3/users/
  * @author Joseph Bielawski <stloyd@gmail.com>
+ * @revised Felipe Valtl de Mello <eu@felipe.im>
  */
 class CurrentUser extends AbstractApi
 {
@@ -111,16 +113,27 @@ public function watchers()
     {
         return new Watchers($this->client);
     }
-
+
+    /**
+     * @Deprecated Use watchers() instead
+     */
     public function watched($page = 1)
     {
         return $this->get('user/watched', array(
             'page' => $page
         ));
     }
+
+     /**
+     * @return Starring
+     */
+    public function starring()
+    {
+         return new Starring($this->client);
+    }
 
-    /**
-     *  @link http://developer.github.com/changes/2012-9-5-watcher-api/
+   /**
+     * @Deprecated Use starring() instead
      */
     public function starred($page = 1)
     {

lib/Github/Api/CurrentUser/Starring.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 <eu@felipe.im>
+ */
+class Starring 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 <stloyd@gmail.com>
+ * @revised Felipe Valtl de Mello <eu@felipe.im>
  */
 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/StarringTest.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Github\Tests\Api;
+
+use Github\Tests\Api\TestCase;
+
+class StarringTest 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\Starring';
+    }
+}