PHPackages                             ghijk/cloudflare-super-images - 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. [Image & Media](/categories/media)
4. /
5. ghijk/cloudflare-super-images

ActiveLibrary[Image & Media](/categories/media)

ghijk/cloudflare-super-images
=============================

A Laravel package for Cloudflare Images: build delivery URLs, mint direct creator uploads, and manage assets.

v0.2.0(today)00MITPHPPHP ^8.3

Since Jun 19Pushed todayCompare

[ Source](https://github.com/1stevengrant/cloudflare-super-images)[ Packagist](https://packagist.org/packages/ghijk/cloudflare-super-images)[ Docs](https://github.com/1stevengrant/cloudflare-super-images)[ RSS](/packages/ghijk-cloudflare-super-images/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (8)Versions (3)Used By (0)

Cloudflare Super Images
=======================

[](#cloudflare-super-images)

A Laravel package for [Cloudflare Images](https://developers.cloudflare.com/images/). Build flexible delivery URLs, mint Direct Creator Upload URLs, verify uploads, and clean up assets, all from a clean, fluent API.

What it does
------------

[](#what-it-does)

- **Flexible delivery URLs**. Build `imagedelivery.net` URLs with width, height, fit, quality, and format through a fluent builder.
- **Background removal**. Append `segment=foreground` (Cloudflare's BiRefNet model) with a single chainable call. Transparency-safe format handling is automatic.
- **Smart crops**. Use `gravity=face` with an optional `zoom` to keep portraits framed.
- **Presets and named variants**. Ship with thumbnail, classic, and hero presets, or point at dashboard variants.
- **Direct Creator Upload**. Mint one-time upload URLs so the browser uploads straight to Cloudflare, bypassing your application's request body limits.
- **Upload verification**. Poll with exponential backoff until a draft upload flips to ready.

This package relies on **Flexible Variants** being enabled on your account (Dashboard, Images, Hosted Images, Delivery) so arbitrary transformation parameters such as `w=600,fit=cover` render.

Installation
------------

[](#installation)

```
composer require ghijk/cloudflare-super-images
```

Publish the config file:

```
php artisan vendor:publish --tag="cloudflare-super-images-config"
```

Configuration
-------------

[](#configuration)

Add your Cloudflare credentials to `.env`:

```
CF_ACCOUNT_ID=your-account-id
CF_ACCOUNT_HASH=your-public-delivery-hash
CF_IMAGES_TOKEN=your-images-edit-token
```

VariablePurpose`CF_ACCOUNT_ID`Your Cloudflare account ID.`CF_ACCOUNT_HASH`Public-safe Images delivery hash (Images, Hosted Images, Developer Resources). Safe to expose in markup.`CF_IMAGES_TOKEN`API token with `Account, Cloudflare Images, Edit`, used to mint upload URLs and manage assets.Building delivery URLs
----------------------

[](#building-delivery-urls)

```
use Ghijk\CloudflareSuperImages\Facades\CloudflareImages;
use Ghijk\CloudflareSuperImages\Enums\ImageFit;
use Ghijk\CloudflareSuperImages\Enums\ImageFormat;
use Ghijk\CloudflareSuperImages\Enums\ImageGravity;
use Ghijk\CloudflareSuperImages\Enums\ImagePreset;

// Responsive product card
CloudflareImages::url($imageId)
    ->width(600)
    ->fit(ImageFit::Cover)
    ->format(ImageFormat::Auto)
    ->toString();

// Background removal (format defaults to PNG to preserve transparency)
CloudflareImages::url($imageId)
    ->removeBackground()
    ->width(800)
    ->toString();

// Face-aware crop
CloudflareImages::url($imageId)
    ->preset(ImagePreset::Thumbnail)
    ->gravity(ImageGravity::Face)
    ->zoom(0.5)
    ->toString();

// A named variant configured in the dashboard
CloudflareImages::variant($imageId, 'hero');
```

The builder casts to a string, so you can use it directly in markup or pass it anywhere a string is expected.

Blade component
---------------

[](#blade-component)

```

```

Any extra attributes (`alt`, `class`, `loading`) pass straight through to the rendered `` tag.

Inertia (React and Vue)
-----------------------

[](#inertia-react-and-vue)

The package ships React and Vue components that build delivery URLs on the client from an `imageId`, so one image can render at many sizes without a server prop per variant. They share a small TypeScript port of the URL builder.

Publish the stubs into your app, where your existing Vite and TypeScript pipeline compiles them:

```
php artisan vendor:publish --tag="cloudflare-super-images-js"
```

This copies `buildImageUrl.ts`, `react/CloudflareImage.tsx`, and `vue/CloudflareImage.vue` into `resources/js/vendor/cloudflare-super-images`.

Share your public delivery hash once so the components can read it. In `app/Http/Middleware/HandleInertiaRequests.php`:

```
use Ghijk\CloudflareSuperImages\Facades\CloudflareImages;

public function share(Request $request): array
{
    return [
        ...parent::share($request),
        'cloudflareImages' => [
            'accountHash' => CloudflareImages::accountHash(),
        ],
    ];
}
```

Then use the component. Options map onto the same names as the PHP builder, and extra attributes pass through to the ``:

```
import { CloudflareImage } from '@/vendor/cloudflare-super-images/react/CloudflareImage'

```

```

import CloudflareImage from '@/vendor/cloudflare-super-images/vue/CloudflareImage.vue'

```

If you would rather not share the hash globally, pass it explicitly with an `accountHash` prop. To keep the URL built on the server instead, drop the components and pass `CloudflareImages::url($id)->...->toString()` as a plain string prop.

Direct Creator Upload
---------------------

[](#direct-creator-upload)

Mint a one-time upload URL and hand it to the browser:

```
use Ghijk\CloudflareSuperImages\Facades\CloudflareImages;

$upload = CloudflareImages::requestDirectUpload([
    'product_id' => $product->id,
]);

// $upload->id, $upload->uploadUrl, $upload->accountHash
return response()->json($upload->toArray());
```

The browser then POSTs the file directly to `$upload->uploadUrl`. Once that completes, verify the asset before persisting anything that points at it:

```
// Polls with exponential backoff, throws CouldNotVerifyUpload if it never readies
CloudflareImages::assertUploaded($upload->id);
```

Reading and deleting assets
---------------------------

[](#reading-and-deleting-assets)

```
$details = CloudflareImages::getImageDetails($imageId);

if ($details?->isReady()) {
    // ...
}

// Best-effort cleanup, returns a boolean rather than throwing
CloudflareImages::delete($imageId);
```

How upload works
----------------

[](#how-upload-works)

```
  Browser                    Your app                        Cloudflare
 ─────────                  ──────────                       ────────────
   │                                                            │
   │  1. requestDirectUpload()  ───────►  POST direct_upload    │
   │                                                            │
   │  ◄────  { id, uploadUrl }  ◄────────────────────────────── │
   │                                                            │
   │  2. POST file directly to uploadUrl  ────────────────────► │
   │                                                            │
   │  3. assertUploaded(id)  ───────────►  verify upload        │
   │                                                            │
   │  4.  renders imagedelivery.net URL ─── │

```

Testing
-------

[](#testing)

```
composer test
```

The package ships with `Http::fake()` driven tests for the API client and pure unit tests for the URL builder.

Credits
-------

[](#credits)

Ported from a TanStack Start on Cloudflare Workers demo into a reusable Laravel package.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity39

Early-stage or recently created project

 Bus Factor1

Top contributor holds 66.7% 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

Every ~0 days

Total

2

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/10068142?v=4)[ghijk](/maintainers/ghijk)[@ghijk](https://github.com/ghijk)

---

Top Contributors

[![1stevengrant](https://avatars.githubusercontent.com/u/112473?v=4)](https://github.com/1stevengrant "1stevengrant (2 commits)")[![jillesme](https://avatars.githubusercontent.com/u/2955483?v=4)](https://github.com/jillesme "jillesme (1 commits)")

---

Tags

laravelimagescloudflarecdncloudflare imagesghijk

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ghijk-cloudflare-super-images/health.svg)

```
[![Health](https://phpackages.com/badges/ghijk-cloudflare-super-images/health.svg)](https://phpackages.com/packages/ghijk-cloudflare-super-images)
```

###  Alternatives

[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.3M42](/packages/spatie-laravel-pdf)[spatie/laravel-health

Monitor the health of a Laravel application

87411.3M152](/packages/spatie-laravel-health)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3913.7k](/packages/rawilk-profile-filament-plugin)[ralphjsmit/laravel-glide

Auto-magically generate responsive images from static image files.

4923.6k5](/packages/ralphjsmit-laravel-glide)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

43140.3k](/packages/harris21-laravel-fuse)[vormkracht10/laravel-mails

Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app.

24655.3k](/packages/vormkracht10-laravel-mails)

PHPackages © 2026

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