Zend_Service_Instagram

{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Zend_Service_Instagram
{zone-data}

{zone-data:proposer-list}
[Mauricio Cuenca|mailto:macuenca@gmail.com]
{zone-data}

{zone-data:liaison}
TBD
{zone-data}

{zone-data:revision}
1.0 - 06 March 2011: Initial Draft.
{zone-data}

{zone-data:overview}
Zend_Service_Instagram is a full implementation of the official Instagram API. It provides an object oriented interface to the API and returns data in JSON format or PHP data objects.
{zone-data}

{zone-data:references}
* [Instagram Developer|http://instagr.am/developer/]
* [Instagram PHP API implementation|https://github.com/macuenca/Instagram-PHP-API]
{zone-data}

{zone-data:requirements}
Most requirements take the form of "foo will do ...." or "foo will not support ...", although different words and sentence structure might be used. Adding functionality to your proposal is requirements creep (bad), unless listed below. Discuss major changes with your team first, and then open a "feature improvement" issue against this component.

* This component *will* fully implement Instagram official API.
* This component should namespace the API methods as they are stated in Instagram's API documentation.
* This component *will not* support real-time photo updates.
{zone-data}

{zone-data:dependencies}
* Zend_Oauth
* Zend_Service_Exception
* Zend_Http_Client
* Zend_Http_Client_Adapter_Curl
* Zend_Http_Client_Exception
{zone-data}

{zone-data:operation}
Zend_Service_Instagram will allow a developer an easy interaction with the Instagram API in a object oriented manner, supporting such actions as getting users' information, browse through popular media, manage users' relationships, comments, likes, tags and locations. All data returned can be represented whether in JSON format or as php data objects. Zend_Service_Instagram creates a php client for the Instagram API.
{zone-data}

{zone-data:milestones}
* Milestone 1: Proposal, Community Review and Acceptance.
* Milestone 2: Unit tests exist, work, and are checked into versioning system.
* Milestone 4: Initial documentation exists.
#If a milestone is already done, begin the description with "\[DONE\]", like this:
#* Milestone #: \[DONE\] Unit tests ...
{zone-data}

{zone-data:class-list}
* Zend_Instagram_Exception
* Zend_Instagram
{zone-data}

{zone-data:use-cases}
||UC-01 Users||



{composition-setup}

{deck:id=Users}
{card:label=Get Info}
Get basic information about a user.
{code:php}
$instagram = new Instagram($config);
$popular = $instagram->getUser(3847232);
{code}
{card}

{card:label=Get Feed}
See the authenticated user's feed.
{code:php}
$instagram = new Instagram($config);
$userFeed = $instagram->getUserFeed(100, 90);
{code}
{card}

{card:label=Get Recent Info}
Get the most recent media published by a user.
{code:php}
$instagram = new Instagram($config);
$recentInfo = $instagram->getUserRecent(3847232);
{code}
{card}

{card:label=Search Username}
Search for a user by name.
{code:php}
$instagram = new Instagram($config);
$searchResults = $instagram->searchUser('Mauricio');
{code}
{card}

{deck}


||UC-02 Relationships||

{deck:id=Relationships}
{card:label=User Follows}
Get the list of users this user follows.
{code:php}
$instagram = new Instagram($config); 
$userFollows = $instagram->getUserFollows(3847232); 
{code}
{card}

{card:label=User Followed By}
Get the list of users this user is followed by.
{code:php}
$instagram = new Instagram($config);
$followedBy = $instagram->getUserFollowedBy(3847232);
{code}
{card}

{card:label=Follow Requests}
List the users who have requested this user's permission to follow.
{code:php}
$instagram = new Instagram($config); 
$followRequests = $instagram->getUserRequestedBy();
{code}
{card}

{card:label=User Relationships}
Get information about the current user's relationship (follow/following/etc) to another user.
{code:php}
$instagram = new Instagram($config); 
$relationships = $instagram->getUserRelationship(3847232);
{code}
{card}

{deck}


||UC-03 Media||

{deck:id=Media}
{card:label=Media Object Info}
Get information about a media object.
{code:php}
$instagram = new Instagram($config); 
$media = $instagram->getMedia(87319873891);
{code}
{card}

{card:label=Search Media By Location}
Search for media in a given area.
{code:php}
$instagram = new Instagram($config); 
$nearbyMedia = $instagram->mediaSearch(3.3727468, -0.21312389);
{code}
{card}

{card:label=Popular Media}
Get a list of what media is most popular at the moment.
{code:php}
$instagram = new Instagram($config); 
$popular = $instagram->getPopularMedia();
{code}
{card}

{deck}


||UC-04 Comments||

{deck:id=Comments}
{card:label=Media Comments}
Get a full list of comments on a media.
{code:php}
$instagram = new Instagram($config); 
$comments = $instagram->getMediaComments(87319873891);
{code}
{card}

{card:label=Create Media Comment}
Create a comment on a media.
{code:php}
$instagram = new Instagram($config); 
$comment = $instagram->postMediaComment(87319873891, 'A beautiful landscape');
{code}

{card:label=Remove Media Comment}
Remove a comment either on the authenticated user's media or authored by the authenticated user.
{code:php}
$instagram = new Instagram($config); 
$popular = $instagram->deleteComment(87319873891, 2);
{code}
{card}

{deck}

||UC-05 Likes||

{deck:id=Likes}
{card:label=Get Likes}
Get a list of users who have liked this media.
{code:php}
$instagram = new Instagram($config); 
$likes = $instagram->getLikes(87319873891);
{code}
{card}

{card:label=Set Like}
Set a like on this media by the currently authenticated user.
{code:php}
$instagram = new Instagram($config);
$like = $instagram->postLike(87319873891);
{code}
{card}

{card:label=Set Like}
Set a like on this media by the currently authenticated user.
{code:php}
$instagram = new Instagram($config);
$like = $instagram->postLike(87319873891);
{code}
{card}

{card:label=Remove Like}
Remove a like on this media by the currently authenticated user.
{code:php}
$instagram = new Instagram($config); 
$like = $instagram->removeLike(87319873891); 
{code}

{zone-data:skeletons}
{code:php}
require_once 'Zend/Http/Client.php';

class Zend_Service_Instagram extends Zend_Service {

/**
* The name of the GET param that holds the authentication code
* @var string
*/
const RESPONSE_CODE_PARAM = 'code';

/**
* Format for endpoint URL requests
* @var string
*/
protected $_endpointUrls = array(
'user' => 'https://api.instagram.com/v1/users/%d/?access_token=%s',
'user_feed' => 'https://api.instagram.com/v1/users/self/feed?access_token=%s&max_id=%d&min_id=%d',
'user_recent' => 'https://api.instagram.com/v1/users/%d/media/recent/?access_token=%s&max_id=%d&min_id=%d&max_timestamp=%d&min_timestamp=%d',
'user_search' => 'https://api.instagram.com/v1/users/search?q=%s&access_token=%s',
'user_follows' => 'https://api.instagram.com/v1/users/%d/follows?access_token=%s',
'user_followed_by' => 'https://api.instagram.com/v1/users/%d/followed-by?access_token=%s',
'user_requested_by' => 'https://api.instagram.com/v1/users/self/requested-by?access_token=%s',
'user_relationship' => 'https://api.instagram.com/v1/users/%d/relationship?access_token=%s',
'modify_user_relationship' => 'https://api.instagram.com/v1/users/%d/relationship?action=%s&access_token=%s',
'media' => 'https://api.instagram.com/v1/media/%d?access_token=%s',
'media_search' => 'https://api.instagram.com/v1/media/search?lat=%s&lng=%s&max_timestamp=%d&min_timestamp=%d&distance=%d&access_token=%s',
'media_popular' => 'https://api.instagram.com/v1/media/popular?access_token=%s',
'media_comments' => 'https://api.instagram.com/v1/media/%d/comments?access_token=%s',
'post_media_comment' => 'https://api.instagram.com/v1/media/%d/comments?access_token=%s',
'delete_media_comment' => 'https://api.instagram.com/v1/media/%d/comments?comment_id=%d&access_token=%s',
'likes' => 'https://api.instagram.com/v1/media/%d/likes?access_token=%s',
'post_like' => 'https://api.instagram.com/v1/media/%d/likes,',
'remove_like' => 'https://api.instagram.com/v1/media/%d/likes?access_token=%s',
'tags' => 'https://api.instagram.com/v1/tags/%s?access_token=%s',
'tags_recent' => 'https://api.instagram.com/v1/tags/%s/media/recent?max_id=%d&min_id=%d&access_token=%s',
'tags_search' => 'https://api.instagram.com/v1/tags/search?q=%s&access_token=%s',
'locations' => 'https://api.instagram.com/v1/locations/%d?access_token=%s',
'locations_recent' => 'https://api.instagram.com/v1/locations/%d/media/recent/?max_id=%d&min_id=%d&max_timestamp=%d&min_timestamp=%d&access_token=%s',
'locations_search' => 'https://api.instagram.com/v1/locations/search?lat=%s&lng=%s&foursquare_id=%d&distance=%d&access_token=%s',
);

/**
* Configuration parameter
*/
protected $_config = array();

/**
* Access token
* @var string
*/
protected $_accessToken = null;

/**
* Holds the HTTP client instance
* @param Zend_Http_Client $httpClient
*/
protected $_httpClient = null;

/**
* Constructor needs to receive the config as an array
* @param mixed $config
*/
public function __construct($config = null) {
$this->_config = $config;
if (empty($config)) {
throw new InstagramException('Configuration params are empty or not an array.');
}
}

/**
* The init method is triggered on every call to retrieve the
* access token in case is not in the current instance.
*/
protected function _init() {}

/**
* Gets the code param received during the authorization step
*/
public function getCode() {
return $_GET[self::RESPONSE_CODE_PARAM];
}

/**
* Retrieves the OAuth token to be used in every request
* @return string
*/
protected function _getOauthToken() {}

/**
* Get basic information about a user.
* @param $id
* @param $oauthToken
*/
public function getUser($id) {}

/**
* See the authenticated user's feed.
* @param integer $maxId. Return media after this maxId.
* @param integer $minId. Return media before this minId.
*/
public function getUserFeed($maxId = null, $minId = null) {}

/**
* Get the most recent media published by a user.
* @param $id. User id
* @param $maxId. Return media after this maxId
* @param $minId. Return media before this minId
* @param $maxTimestamp. Return media before this UNIX timestamp
* @param $minTimestamp. Return media after this UNIX timestamp
*/
public function getUserRecent($id, $maxId = '', $minId = '', $maxTimestamp = '', $minTimestamp = '') {}

/**
* Search for a user by name.
* @param string $name. A query string
*/
public function searchUser($name) {
}

/**
* Get the list of users this user follows.
* @param integer $id. The user id
*/
public function getUserFollows($id) {}

/**
* Get the list of users this user is followed by.
* @param integer $id
*/
public function getUserFollowedBy($id) {}

/**
* List the users who have requested this user's permission to follow
*/
public function getUserRequestedBy() {}

/**
* Get information about the current user's relationship (follow/following/etc) to another user.
* @param integer $id
*/
public function getUserRelationship($id) {}

/**
* Modify the relationship between the current user and the target user
* In order to perform this action the scope must be set to 'relationships'
* @param integer $id
* @param string $action. One of follow/unfollow/block/unblock/approve/deny
*/
public function modifyUserRelationship($id, $action) {}

/**
* Get information about a media object.
* @param integer $mediaId
*/
public function getMedia($id) {}

/**
* Search for media in a given area.
* @param float $lat
* @param float $lng
* @param integer $maxTimestamp
* @param integer $minTimestamp
* @param integer $distance
*/
public function mediaSearch($lat, $lng, $maxTimestamp = '', $minTimestamp = '', $distance = '') {}

/**
* Get a list of what media is most popular at the moment.
*/
public function getPopularMedia() {}

/**
* Get a full list of comments on a media.
* @param integer $id
*/
public function getMediaComments($id) {}

/**
* Create a comment on a media.
* @param integer $id
* @param string $text
*/
public function postMediaComment($id, $text) {}

/**
* Remove a comment either on the authenticated user's media or authored by the authenticated user.
* @param integer $mediaId
* @param integer $commentId
*/
public function deleteComment($mediaId, $commentId) {}

/**
* Get a list of users who have liked this media.
* @param integer $mediaId
*/
public function getLikes($mediaId) {}

/**
* Set a like on this media by the currently authenticated user.
* @param integer $mediaId
*/
public function postLike($mediaId) {}

/**
* Remove a like on this media by the currently authenticated user.
* @param integer $mediaId
*/
public function removeLike($mediaId) {}

/**
* Get information about a tag object.
* @param string $tagName
*/
public function getTags($tagName) {}

/**
* Get a list of recently tagged media.
* @param string $tagName
* @param integer $maxId
* @param integer $minId
*/
public function getRecentTags($tagName, $maxId = '', $minId = '') {}

/**
* Search for tags by name - results are ordered first as an exact match, then by popularity.
* @param string $tagName
*/
public function searchTags($tagName) {}

/**
* Get information about a location.
* @param integer $id
*/
public function getLocation($id) {}

/**
* Get a list of recent media objects from a given location.
* @param integer $locationId
*/
public function getLocationRecentMedia($id, $maxId = '', $minId = '', $maxTimestamp = '', $minTimestamp = '') {}

/**
* Search for a location by name and geographic coordinate.
* @see http://instagr.am/developer/endpoints/locations/#get_locations_search
* @param float $lat
* @param float $lng
* @param integer $foursquareId
* @param integer $distance
*/
public function searchLocation($lat, $lng, $foursquareId = '', $distance = '') {}
}
{code}
{zone-data}

{zone-template-instance}