Caution: this is the development branch for the upcoming version 3

A PHP wrapper for the Instagram API. Feedback or bug reports are appreciated.

Composer package available.
Supports Instagram Video and Signed Header.

• PHP 5.3 or higher
• cURL
• Registered Instagram App

To use the Instagram API you have to register yourself as a developer at the Instagram Developer Platform and create an application. Take a look at the uri guidlines before registering a redirect URI. You will receive your client_id and client_secret.

Please note that Instagram mainly refers to »Clients« instead of »Apps«. So »Client ID« and »Client Secret« are the same as »App Key« and »App Secret«.

A good place to get started is the example project.

I strongly advice using Composer to keep updates as smooth as possible.

$ composer require cosenary/instagram

use MetzWeb\Instagram\Instagram;

$instagram = new Instagram(array(
	'apiKey'      => 'YOUR_APP_KEY',
	'apiSecret'   => 'YOUR_APP_SECRET',
	'apiCallback' => 'YOUR_APP_CALLBACK'
));

echo "<a href='{$instagram->getLoginUrl()}'>Login with Instagram</a>";

// grab OAuth callback code
$code = $_GET['code'];
$data = $instagram->getOAuthToken($code);

echo 'Your username is: ' . $data->user->username;

// set user access token
$instagram->setAccessToken($data);

// get all user likes
$likes = $instagram->getUserLikes();

// take a look at the API response
echo '<pre>';
print_r($likes);
echo '<pre>';

All methods return the API data json_decode() - so you can directly access the data.

new Instagram(<array>/<string>);

array if you want to authenticate a user and access its data:

new Instagram(array(
	'apiKey'      => 'YOUR_APP_KEY',
	'apiSecret'   => 'YOUR_APP_SECRET',
	'apiCallback' => 'YOUR_APP_CALLBACK'
));

string if you only want to access public data:

new Instagram('YOUR_APP_KEY');

getLoginUrl(<array>)

getLoginUrl(array(
	'basic',
	'likes'
));

Optional scope parameters:

getOAuthToken($code, <true>/<false>)

true : Returns only the OAuth token
false [default] : Returns OAuth token and profile data of the authenticated user

• Set the access token, for further method calls: setAccessToken($token)
• Get the access token, if you want to store it for later usage: getAccessToken()

Public methods

• getUser($id)
• searchUser($name, <$limit>)
• getUserMedia($id, <$limit>)

Authenticated methods

• getUser()
• getUserLikes(<$limit>)
• getUserFeed(<$limit>)
• getUserMedia(<$id>, <$limit>)
  • if an $id isn't defined or equals 'self', it returns the media of the logged in user

Sample responses of the User Endpoints.

Authenticated methods

• getUserFollows($id, <$limit>)
• getUserFollower($id, <$limit>)
• getUserRelationship($id)
• modifyRelationship($action, $user)
  • $action : Action command (follow / unfollow / block / unblock / approve / deny)
  • $user : Target user id

// Follow the user with the ID 1574083
$instagram->modifyRelationship('follow', 1574083);

Please note that the modifyRelationship() method requires the relationships scope.

Sample responses of the Relationship Endpoints.

Public methods

• getMedia($id)
  • authenticated users receive the info, whether the queried media is liked
• getMediaShortcode($shortcode)
• getPopularMedia()
• searchMedia($lat, $lng, <$distance>, <$minTimestamp>, <$maxTimestamp>)
  • $lat and $lng are coordinates and have to be floats like: 48.145441892290336,11.568603515625
  • $distance : Radial distance in meter (default is 1km = 1000, max. is 5km = 5000)
  • $minTimestamp : All media returned will be taken later than this timestamp (default: 5 days ago)
  • $maxTimestamp : All media returned will be taken earlier than this timestamp (default: now)

Sample responses of the Media Endpoints.

Public methods

• getMediaComments($id)

Authenticated methods

• addMediaComment($id, $text)
  • restricted access: please email apidevelopers[at]instagram.com for access
• deleteMediaComment($id, $commentID)
  • the comment must be authored by the authenticated user

Please note that the authenticated methods require the comments scope.

Sample responses of the Comment Endpoints.

Public methods

• getTag($name)
• getTagMedia($name)
• searchTags($name)

Sample responses of the Tag Endpoints.

Authenticated methods

• getMediaLikes($id)
• likeMedia($id)
• deleteLikedMedia($id)

How to like a Media: Example usage Sample responses of the Likes Endpoints.

All <...> parameters are optional. If the limit is undefined, all available results will be returned.

Instagram entries are marked with a type attribute (image or video), that allows you to identify videos.

An example of how to embed Instagram videos by using Video.js, can be found in the /example folder.

Please note: Instagram currently doesn't allow to filter videos.

In order to prevent that your access tokens gets stolen, Instagram recommends to sign your requests with a hash of your API secret and IP address.

1. Activate "Enforce Signed Header" in your Instagram client settings.
2. Enable the signed-header in your Instagram class:

$instagram->setSignedHeader(true);

3. You are good to go! Now, all your POST and DELETE requests will be secured with a signed header.

Go into more detail about how it works in the Instagram API Docs.

Each endpoint has a maximum range of results, so increasing the limit parameter above the limit won't help (e.g. getUserMedia() has a limit of 90).

That's the point where the "pagination" feature comes into play. Simply pass an object into the pagination() method and receive your next dataset:

$photos = $instagram->getTagMedia('kitten');

$result = $instagram->pagination($photos);

Iteration with do-while loop.

If you need further information about an endpoint, take a look at the Instagram API docs.

This example project, located in the example/ folder, helps you to get started. The code is well documented and takes you through all required steps of the OAuth2 process. Credit for the awesome Instagram icons goes to mauroxanish.

• User likes
• Follow user
• User follower
• Load more button
• User most recent media
• Instagram login
• Instagram signup (9lessons tutorial)
• Laravel Wrapper

Let me know if you have to share a code example, too.

Please see the changelog file for more information.

Copyright (c) 2011-2015 - Programmed by Christian Metz

Released under the BSD License.