Instagram PHP API V2
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. For more information, please see #182.
A PHP wrapper for the Instagram API. Feedback or bug reports are appreciated.
Composer package available.
Supports Instagram Video and Signed Header.
Requirements
- PHP 5.3 or higher
- cURL
- Registered Instagram App
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
.
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.
Installation
I strongly advice using Composer to keep updates as smooth as possible.
$ composer require cosenary/instagram
Initialize the class
use MetzWeb\Instagram\Instagram;
$instagram = new Instagram(array(
'apiKey' => 'YOUR_APP_KEY',
'apiSecret' => 'YOUR_APP_SECRET',
'apiCallback' => 'YOUR_APP_CALLBACK'
));
echo "Login with Instagram";
Authenticate user (OAuth2)
// grab OAuth callback code
$code = $_GET['code'];
$data = $instagram->getOAuthToken($code);
echo 'Your username is: ' . $data->user->username;
Get user likes
// set user access token
$instagram->setAccessToken($data);
// get all user likes
$likes = $instagram->getUserLikes();
// take a look at the API response
echo '';
print_r($likes);
echo '';
All methods return the API data json_decode()
- so you can directly access the data.
Available methods
Setup Instagram
new Instagram(
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');
Get login URL
getLoginUrl(
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
: 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
- if an
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.
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)
Comment methods
Public methods
getMediaComments($id)
Authenticated methods
addMediaComment($id, $text)
- restricted access: please email
apidevelopers[at]instagram.com
for access
- restricted access: please email
deleteMediaComment($id, $commentID)
- the comment must be authored by the authenticated user
Please note that the authenticated methods require the comments
scope.
Tag methods
Public methods
getTag($name)
getTagMedia($name)
searchTags($name)
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.
- Activate "Enforce Signed Header" in your Instagram client settings.
- Enable the signed-header in your Instagram class:
$instagram->setSignedHeader(true);
- 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
If you need further information about an endpoint, take a look at the Instagram API docs.
Example App
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 Ricardo de Zoete Pro.
More examples and tutorials:
- 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.
Changelog
Please see the changelog file for more information.
Credits
Copyright (c) 2011-2015 - Programmed by Christian Metz
Released under the BSD License.