j0k3r/php-imgur-api-client

Imgur API v3 client

Fund package maintenance!
j0k3r

4.0.1 2023-10-06 07:35 UTC

This package is auto-updated.

Last update: 2024-11-05 09:33:49 UTC


README

CI Coverage Status Total Downloads License

Object Oriented PHP wrapper for the Imgur API.

Uses Imgur API v3.

Information

  • Branch 1.x use Guzzle 3 (but is not maintained)
  • Branch 2.x use Guzzle 5 (but is not maintained)
  • Branch 3.x use Guzzle 6 and PHP >= 5.6
  • Branch master use Guzzle 7 and PHP >= 7.4

Composer

Download Composer

$ curl -s http://getcomposer.org/installer | php

Add the library details to your composer.json

composer require j0k3r/php-imgur-api-client@^4.0

Install the dependency with

$ php composer.phar install

Basic usage

// This file is generated by Composer
require_once 'vendor/autoload.php';

$client = new \Imgur\Client();
$client->setOption('client_id', '[your app client id]');
$client->setOption('client_secret', '[your app client secret]');

if (isset($_SESSION['token'])) {
    $client->setAccessToken($_SESSION['token']);

    if ($client->checkAccessTokenExpired()) {
        $client->refreshToken();
    }
} elseif (isset($_GET['code'])) {
    $client->requestAccessToken($_GET['code']);
    $_SESSION['token'] = $client->getAccessToken();
} else {
    echo '<a href="'.$client->getAuthenticationUrl().'">Click to authorize</a>';
}

The API calls can be accessed via the $client object

$memes = $client->api('memegen')->defaultMemes();

Documentation

Basic information

This client follow the same tree as the Imgur API.

Here is the list of available endpoints: account, album, comment, custom gallery, gallery, image, conversation, notification, memegen & topic.

You can access each endpoint using the api() method:

$client->api('album');
$client->api('comment');
$client->api('customGallery');
// etc ...

All available methods for each endpoints are in the folder Api. They mostly follow the description name in the Imgur doc. Here are few examples:

// for "Account Base" in account
$client->api('account')->base();
// for "Account Gallery Profile" in account
$client->api('account')->accountGalleryProfile();

// for "Filtered Out Gallery" in Custom Gallery
$client->api('customGallery')->filtered();

// for "Random Gallery Images" in gallery
$client->api('gallery')->randomGalleryImages();

// etc ...

Uploading an image

If you want to upload an image you can use one of these solutions:

$pathToFile = '../path/to/file.jpg';
$imageData = [
    'image' => $pathToFile,
    'type'  => 'file',
];

$client->api('image')->upload($imageData);

or

$urlToFile = 'http://0.0.0.0/path/to/file.jpg';
$imageData = [
    'image' => $urlToFile,
    'type'  => 'url',
];

$client->api('image')->upload($imageData);

or

$pathToFile = '../path/to/file.jpg';
$imageData = [
    'image' => base64_encode(file_get_contents($pathToFile)),
    'type'  => 'base64',
];

$client->api('image')->upload($imageData);

Pagination

For any API call that supports pagination and is not explicitly available via the method parameters, it can be achieved by using the BasicPager object and passing it as the second parameter in the api() call.

$pager = new \Imgur\Pager\BasicPager(1, 10);
$images = $client->api('account', $pager)->images();

Here is a real life example if you want to retrieve all your available images of an account:

$page = 1;
$pager = new \Imgur\Pager\BasicPager();
$res = $client->api('account', $pager)->images();

while (!empty($res)) {
    // var_dump(count($res));

    $pager->setPage($page++);

    $res = $client->api('account', $pager)->images();
}

This pager is really basic:

  • You won't have information about how many pages are available
  • If you request a non-existant page, you'll get an empty array

NOTE: /gallery endpoints do not support the perPage query string, and /album/{id}/images is not paged.

Please, read the Imgur doc about it.

Image id or Album id ?

When you got an Imgur link it's almost impossible to be 100% sure if it's an image or an album. That's why we have an endpoint which might fix that by first checking an id as an image and if it's fail, test it as an album:

$data = $client->api('albumOrImage')->find($id);

License

php-imgur-api-client is licensed under the MIT License - see the LICENSE file for details