Instagram PHP API v3.3.0
A PHP wrapper for the Instagram API.
Feedback or bug reports are appreciated.
Now supports Instagram video responses.
Requirements
- Registered Instagram App
- PHP 5.3 or higher
- cURL
Get started
To use the Instagram API with OAuth you have to register yourself as developer at the Instagram Developer Platform and set up an App. Take a look at the uri guidlines before registering a redirect URI.
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 App.
Initialize the class
Pure PHP
<?php
require '../vendor/autoload.php';
$instagram = new BunkerDB\Instagram\Client(array(
'apiKey' => 'YOUR_APP_KEY',
'apiSecret' => 'YOUR_APP_SECRET',
'apiCallback' => 'YOUR_APP_CALLBACK',
'scope' => array('basic'),
));
echo "<a href='{$instagram->getLoginUrl()}'>Login with Instagram</a>";
?>
Laravel
This package offers Laravel support out of the box. These steps are required to setup the package.
Configure application
// publish configration file
php artisan config:publish bunkerdb/instagram --path vendor/bunkerdb/instagram/src/Support/Laravel/config
// Edit app/config/packages/bunkerdb/instagram/config/config.php
array (
'clientId' => 'APPLICATION_ID',
'clientSecret' => 'APPLICATION_SECRET',
'redirectUri' => 'AUTH_REDIRECT',
'scope' => array('basic'),
)
Add Service provider and register Facade
'providers' => array(
'BunkerDB\Instagram\Support\Laravel\ServiceProvider\Instagram',
),
'aliases' => array(
'Instagram' => 'BunkerDB\Instagram\Support\Laravel\Facade\Instagram',
),
echo "<a href='" . Instagram::getLoginUrl() . "'>Login with Instagram</a>";
Authenticate user (OAuth2)
<?php
// Grab OAuth callback code
$code = $_GET['code'];
$data = $instagram->getOAuthToken($code);
echo 'Your username is: ' . $data->user->username;
?>
Get user likes
<?php
// 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.
Available methods
Setup Instagram
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');
Get login URL
getLoginUrl(<array>,<string>)
getLoginUrl(array(
'basic',
'likes'
), 'uMFYKG5u6v');
Optional scope parameters: To find out more about Scopes, please visit https://www.instagram.com/developer/authorization/
Get OAuth token
getOAuthToken($code, <true>/<false>)
true
: Return only the OAuth token
false
[default] : Returns OAuth token and profile data of the authenticated user
Set / Get access token
Set access token, for further method calls:
setAccessToken($token)
Return 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 toself
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
-
<?php
// 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)
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.
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:
<?php
$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)
Let me know if you have to share a code example, too.
History
Instagram 3.2.0 - 09/07/2014
-
feature
Add option to set permission scope application-wide thru Client constructor.
-
feature
You may provide an optional state parameter togetLoginUrl
method to protect against CSRF. -
feature
Throw specific Exception instead of generic Exception (usefull for handling multiple error cases).
Instagram 3.1.0 - 09/07/2014
-
feature
Laravel support out of the box (but still framework agnostic).
Instagram 3.0.0 - 08/07/2014
-
feature
PSR-4 autoloading, publish Composer package
Instagram 2.1 - 30/01/2014
-
update
added min and max_timestamp tosearchMedia()
-
update
public authentication forgetUserMedia()
method -
fix
support for inconsistent pagination return type (relationship endpoint)
Instagram 2.0 - 24/12/2013
-
release
version 2.0
Instagram 2.0 beta - 20/11/2013
-
feature
Added Locations endpoint -
update
Updated example project to display Instagram videos
Instagram 2.0 alpha 4 - 01/11/2013
-
feature
Comment endpoint implemented -
feature
New example with a fancy GUI -
update
Improved documentation
Instagram 2.0 alpha 3 - 04/09/2013
-
merge
Merged master branch updates-
update
Updated documentation -
bug
/change
cURL CURLOPT_SSL_VERIFYPEER disabled (fixes #6, #7, #8, #16) -
feature
Added cURL error message -
feature
Addedlimit
togetTagMedia()
method
-
Instagram 2.0 alpha 2 - 14/06/2013
-
feature
Improved Pagination functionality -
change
Addeddistance
parameter tosearchMedia()
method (thanks @jonathanwkelly)
Instagram 2.0 alpha 1 - 28/05/2012
-
feature
Added Pagination method -
feature
Added User Relationship endpoints -
feature
Added scope parameter table for thegetLoginUrl()
method
Instagram 1.5 - 31/01/2012
-
release
Second master version -
feature
Added Tag endpoints -
change
Edited the "Get started" example -
change
Now you can pass thegetOAuthToken()
object directly intosetAccessToken()
Instagram 1.0 - 20/11/2011
-
release
First public release -
feature
Added sample App with documented code -
update
New detailed documentation
Instagram 0.8 - 16/11/2011
-
release
First inital released version -
feature
Initialize the class with a config array or string (see example)
Instagram 0.5 - 12/11/2011
-
release
Beta version -
update
Small documentation
Credits
Copyright (c) 2014 - Andrej Badin Released under the BSD License.
Instagram-PHP-API contains code taken from Christian Metz's Instagram-PHP-API, also licensed under BSD License.