PHPackages                             jooservices/flickr - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. jooservices/flickr

ActiveLibrary[Authentication & Authorization](/categories/authentication)

jooservices/flickr
==================

A framework-agnostic PHP 8.5+ SDK for Flickr API, OAuth 1.0a, upload, and replace workflows.

v1.0.0(1mo ago)035↑2642.9%1MITPHPPHP >=8.5CI passing

Since May 8Pushed 1mo agoCompare

[ Source](https://github.com/jooservices/flickr)[ Packagist](https://packagist.org/packages/jooservices/flickr)[ RSS](/packages/jooservices-flickr/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (14)Versions (4)Used By (1)

JOOservices Flickr SDK
======================

[](#jooservices-flickr-sdk)

[![CI](https://github.com/jooservices/flickr/actions/workflows/ci.yml/badge.svg)](https://github.com/jooservices/flickr/actions/workflows/ci.yml)[![PHP](https://camo.githubusercontent.com/16598136c62714d221757c7770d5cbb35ed8bd80c947bb71953bf1457b599683/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e352d373737626234)](https://camo.githubusercontent.com/16598136c62714d221757c7770d5cbb35ed8bd80c947bb71953bf1457b599683/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e352d373737626234)

`jooservices/flickr` is a pure PHP, framework-agnostic Flickr SDK for PHP 8.5+. It is not a Laravel package and intentionally does not ship service providers, facades, routes, migrations, config publishing, or Artisan commands.

The SDK uses `jooservices/dto` for public data objects and `jooservices/client` for HTTP transport. Official Flickr documentation remains the source of truth for API method behavior:

Current coverage:

- all 224 official REST API methods from the Flickr API index have method-registry entries;
- all 224 official REST API methods have service wrapper methods;
- core workflows also have friendlier DTO-first wrappers where useful;
- raw fallback remains available for custom parameters and future methods.

Install
-------

[](#install)

```
composer require jooservices/flickr
```

Configure
---------

[](#configure)

```
use JOOservices\Flickr\Config\FlickrConfig;
use JOOservices\Flickr\FlickrFactory;

$flickr = FlickrFactory::make(FlickrConfig::from([
    'apiKey' => $_ENV['FLICKR_API_KEY'],
    'apiSecret' => $_ENV['FLICKR_API_SECRET'],
    'callbackUrl' => $_ENV['FLICKR_CALLBACK_URL'] ?? null,
]));
```

First Public Search
-------------------

[](#first-public-search)

```
use JOOservices\Flickr\DTO\Photos\SearchPhotosData;

$response = $flickr->photos()->search(SearchPhotosData::from([
    'text' => 'sunset',
    'tags' => ['landscape'],
    'perPage' => 20,
]));
```

`flickr.photos.search` can run unauthenticated for public photos. Private and semi-private results require OAuth read permission.

For lazy public search pagination, use `searchPages()`:

```
use JOOservices\Flickr\DTO\Common\PaginationOptionsData;

foreach ($flickr->photos()->searchPages(
    SearchPhotosData::from(['text' => 'sunset']),
    new PaginationOptionsData(maxPages: 3, perPage: 50),
) as $page) {
    // $page is ApiResponseData
}
```

Raw API Fallback
----------------

[](#raw-api-fallback)

```
$response = $flickr->raw()->call('flickr.photos.search', [
    'text' => 'cats',
    'per_page' => 10,
]);
```

Unknown methods are still allowed so the package can call future Flickr methods before this package is updated.

Full API Method Wrappers
------------------------

[](#full-api-method-wrappers)

Every method in the official Flickr method index is available through a service wrapper. Wrappers that do not yet have a specialized DTO accept an associative parameter array and return `ApiResponseData`.

Examples:

```
$hotTags = $flickr->tags()->getHotList(['count' => 20]);

$recent = $flickr->photos()->getRecent([
    'per_page' => 20,
    'extras' => ['url_m', 'owner_name'],
]);

$favorite = $flickr->favorites()->add([
    'photo_id' => '123456',
]);

$location = $flickr->photosGeo()->getLocation([
    'photo_id' => '123456',
]);
```

The method registry stores docs URL, auth requirement, OAuth permission, cacheability, and GET/POST metadata scraped from the official method docs.

OAuth 1.0a
----------

[](#oauth-10a)

```
use JOOservices\Flickr\Enums\AuthPermission;

$requestToken = $flickr->auth()->requestToken(AuthPermission::Write);
$authorizationUrl = $flickr->auth()->authorizationUrl($requestToken, AuthPermission::Write);

// After Flickr redirects back with oauth_token and oauth_verifier:
$accessToken = $flickr->auth()->accessToken($oauthToken, $oauthVerifier);
$flickr->tokens()->put($accessToken);
```

Flickr supports HMAC-SHA1 for OAuth request signing.

Upload, Replace, And Async Tickets
----------------------------------

[](#upload-replace-and-async-tickets)

Upload and replace are separate from normal REST calls because Flickr sends binary files to `up.flickr.com`.

```
use JOOservices\Flickr\DTO\Upload\UploadPhotoData;
use JOOservices\Flickr\Enums\Privacy;

$result = $flickr->uploads()->upload(UploadPhotoData::from([
    'path' => '/tmp/photo.jpg',
    'title' => 'My photo',
    'tags' => ['php', 'flickr'],
    'privacy' => Privacy::Private,
    'async' => true,
]));

$ticketResponse = $flickr->uploads()->checkTickets([$result->ticketId]);
```

Replace:

```
use JOOservices\Flickr\DTO\Upload\ReplacePhotoData;

$result = $flickr->uploads()->replace(ReplacePhotoData::from([
    'path' => '/tmp/new-photo.jpg',
    'photoId' => '123456',
    'async' => true,
]));
```

Upload and replace require OAuth write permission. Delete requires delete permission. The SDK builds multipart requests with a readable file stream and closes that handle after the transport request completes.

Error Handling
--------------

[](#error-handling)

Normal API responses are mapped to `ApiResponseData`. Flickr `stat=fail` responses return `ok=false` with `ApiErrorData` unless request options set `throwOnApiError`. Malformed, empty, or structurally invalid responses throw `InvalidResponseException`. Transport failures throw `TransportException`.

Cache
-----

[](#cache)

V1 includes `NullCache`, `Psr16Cache`, and `CacheKeyResolver`. Runtime caching is disabled by default because `FlickrFactory` uses `NullCache` unless a cache adapter is passed.

When a cache adapter is passed, only public cacheable GET REST calls can be cached. Mutation, auth, OAuth, upload, replace, upload ticket polling, authenticated options, auth-required methods, POST methods, and Flickr `stat=fail` responses are never cached by default.

```
use JOOservices\Flickr\Cache\Psr16Cache;

$flickr = FlickrFactory::make(
    config: $config,
    cache: new Psr16Cache($psr16Cache),
);
```

XML Support
-----------

[](#xml-support)

JSON is the primary supported REST response format. XML parsing exists for Flickr upload/replace responses and has limited REST response parsing for compatibility, but REST XML should be treated as experimental unless a workflow has explicit tests.

Testing
-------

[](#testing)

Normal tests do not call Flickr:

```
composer test
composer lint:all
composer check
```

Use the public fake transport to test application code without network calls:

```
use JOOservices\Flickr\Client\FakeFlickrTransport;

$transport = FakeFlickrTransport::new()->pushJson([
    'stat' => 'ok',
    'photos' => ['page' => 1, 'pages' => 1, 'perpage' => 1, 'total' => 0, 'photo' => []],
]);

$flickr = FlickrFactory::make(
    config: new FlickrConfig('test-key', 'test-secret'),
    transport: $transport,
);
```

Real API tests are opt-in:

```
FLICKR_REAL_TESTS=true \
FLICKR_API_KEY=... \
FLICKR_API_SECRET=... \
FLICKR_ACCESS_TOKEN=... \
FLICKR_ACCESS_TOKEN_SECRET=... \
composer test -- --filter RealFlickrTest
```

Docs
----

[](#docs)

See [docs/README.md](docs/README.md) for architecture, getting started, user guide, examples, testing, release readiness, and V2 gaps.

###  Health Score

43

—

FairBetter than 90% of packages

Maintenance92

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

40d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/142772948?v=4)[JOOservices Ltd](/maintainers/jooservices)[@jooservices](https://github.com/jooservices)

---

Top Contributors

[![soulevilx](https://avatars.githubusercontent.com/u/2688707?v=4)](https://github.com/soulevilx "soulevilx (17 commits)")

---

Tags

api-clientcachedtoflickrflickr-apiframework-agnosticjooservicesoauthoauth1phpphp85sdkuploadapisdkoauthuploadflickr

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/jooservices-flickr/health.svg)

```
[![Health](https://phpackages.com/badges/jooservices-flickr/health.svg)](https://phpackages.com/packages/jooservices-flickr)
```

###  Alternatives

[happyr/linkedin-api-client

LinkedIn API client. Handles OAuth, CSRF protection. Easy to implement and extend. This is a standalone library for any composer project.

1991.6M12](/packages/happyr-linkedin-api-client)[bocharsky-bw/vkontakte-php-sdk

Vkontakte PHP SDK

3259.5k1](/packages/bocharsky-bw-vkontakte-php-sdk)[acuityscheduling/acuityscheduling

Acuity Scheduling PHP SDK. Examples and a standard library for Acuity Scheduling integration.

11302.2k](/packages/acuityscheduling-acuityscheduling)[surfoo/geocaching-php-sdk

Geocaching PHP SDK

143.5k1](/packages/surfoo-geocaching-php-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)