The simple PHP Class for accessing Instagram's API
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
CHANGELOG.md
.DS_Store
CONTRIBUTING.md
LICENSE
README.md
composer.json

README.md

Class PHP to use Instagram API v2 (2016)

Note: On the 17 Nov 2015 Instagram made changes to their API . Apps created before Nov 17, 2015 wont be affected until Jun 2016. Apps created on or after Nov 17 2015 will require to use their updated API. Please note that this library doesn't yet support their new updates.

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

Total Downloads Latest Stable Version License

Composer package available.
Supports Instagram Video and Signed Header.

Requirements

  • PHP 5.3 or higher
  • cURL
  • Registered Instagram App with new scope 2016

Get started

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 guidelines before registering a redirect URI. You will receive your client_id and client_secret.

Installation

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

$ composer require romaricp/instagram

Initialize the class

use RomaricP\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>";

Authenticate user (OAuth2)

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

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

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

Available methods

Setup Instagram

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');

Get login URL

getLoginUrl(<array>)

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

Optional scope parameters:

Scope Legend Methods
basic to use all user related methods [default] getUser(), getUserFeed(), getUserFollower() etc.
relationships to follow and unfollow users modifyRelationship()
likes to like and unlike items getMediaLikes(), likeMedia(), deleteLikedMedia()
comments to create or delete comments getMediaComments(), addMediaComment(), deleteMediaComment()

Get OAuth token

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

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

Set / Get access token

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

User methods

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.

Relationship methods

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.

Media methods

Public methods

  • getMedia($id)
    • authenticated users receive the info, whether the queried media is liked
  • 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.

Comment methods

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.

Tag methods

Public methods

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

Sample responses of the Tag Endpoints.

Likes methods

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 videos

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.


Signed Header

In order to prevent that your access tokens gets stolen, Instagram recommends to sign your requests with a hash of your API secret, the called endpoint and parameters.

  1. Activate "Enforce Signed Header" in your Instagram client settings.
  2. Enable the signed-header in your Instagram class:
$instagram->setSignedHeader(true);
  1. You are good to go! Now, all your requests will be secured with a signed header.

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

Pagination

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.

Samples for redirect URLs

Registered Redirect URI Redirect URI sent to /authorize Valid?
http://yourcallback.com/ http://yourcallback.com/ yes
http://yourcallback.com/ http://yourcallback.com/?this=that yes
http://yourcallback.com/?this=that http://yourcallback.com/ no
http://yourcallback.com/?this=that http://yourcallback.com/?this=that&another=true yes
http://yourcallback.com/?this=that http://yourcallback.com/?another=true&this=that no
http://yourcallback.com/callback http://yourcallback.com/ no
http://yourcallback.com/callback http://yourcallback.com/callback/?type=mobile yes

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

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

Changelog

Please see the changelog file for more information.

Credits

Copyright (c) 2011-2015 - Programmed by Christian Metz Released under the BSD License.