DEV Community: Gurinder Chauhan

Laravel 13.20 Image Processing: A Production Guide

Gurinder Chauhan — Wed, 15 Jul 2026 22:26:19 +0000

Originally published on letmesend.email. I work on letmesend.email, and this is an adapted edition of that guide.

This article was prepared with AI-assisted editorial support. Its technical claims and examples were tested against Laravel Framework v13.20.0 in an isolated application.

Image handling rarely stays small. An avatar upload becomes a thumbnail, a WebP copy, a storage policy, a validation rule, and eventually a queue job.

Laravel 13.20, released on July 14, 2026, gives this work a first-party home through the new Illuminate\Image component and Image facade. It connects image processing to requests, filesystem disks, configuration, and Laravel's container while keeping transformation pipelines immutable.

This guide focuses on what actually shipped and the production boundaries that still belong in your application.

What first-party image processing means

Laravel applications have used Intervention Image, custom wrappers, and external image services for years. Laravel 13.20 does not make Intervention Image disappear. The built-in GD and Imagick drivers use intervention/image:^4.0 underneath.

The first-party part is the Laravel-facing API:

use Illuminate\Support\Facades\Image;
use RuntimeException;

$thumbnail = Image::fromPath(storage_path('app/source/photo.jpg'))
    ->orient()
    ->cover(640, 360)
    ->toWebp()
    ->quality(80);

$storedPath = $thumbnail->store('thumbnails', 'public');

if ($storedPath === false) {
    throw new RuntimeException('The thumbnail could not be stored.');
}

That chain describes four concerns:

Load the source lazily.
Record transformations in order.
Select an output format and quality.
Process and store the result through Laravel's filesystem.

The built-in drivers support GD and Imagick. GD is the default. The default processing quality is 70 unless the pipeline selects another value.

Install and configure a driver

Laravel 13.20 and the image component require PHP 8.3 or newer. Install the suggested processing dependency:

composer require intervention/image:^4.0

Your runtime also needs the extension for the chosen driver:

GD requires ext-gd.
Imagick requires ext-imagick and the ImageMagick system library.

The image configuration uses GD by default:

<?php

return [
    'default' => env('IMAGE_DRIVER', 'gd'),
];

To use Imagick as the application default:

IMAGE_DRIVER=imagick

An individual pipeline can choose a different driver without changing global configuration:

use Illuminate\Support\Facades\Image;

$source = Image::fromPath(storage_path('app/source/photo.jpg'));

$gdVariant = $source->usingGd()->cover(400, 400);
$imagickVariant = $source->usingImagick()->cover(400, 400);

Test both drivers with the same representative files in the container you deploy. Output size, memory use, and processing time depend on the source material and extension build.

Create images from supported sources

The component accepts request uploads, local paths, URLs, raw bytes, Base64 strings, and Laravel storage paths.

Request uploads

Validate an upload before asking the image driver to decode it:

use Illuminate\Http\Request;

public function store(Request $request)
{
    $request->validate([
        'avatar' => [
            'required',
            'image',
            'mimes:jpeg,png,webp',
            'max:5120',
            'dimensions:min_width=200,min_height=200,max_width=6000,max_height=6000',
        ],
    ]);

    $image = $request->image('avatar');

    abort_if($image === null, 422, 'A valid avatar image is required.');

    // Build the output pipeline from $image.
}

$request->image('avatar') returns an Illuminate\Image\Image when the input contains one uploaded file. It returns null when it does not.

Other entry points

use Illuminate\Support\Facades\Image;
use Illuminate\Support\Facades\Storage;
use RuntimeException;

$binaryContents = file_get_contents(storage_path('app/source/photo.jpg'));

if ($binaryContents === false) {
    throw new RuntimeException('The source image could not be read.');
}

$base64Contents = base64_encode($binaryContents);

$fromPath = Image::fromPath(storage_path('app/source/photo.jpg'));
$fromUrl = Image::fromUrl('https://assets.example.test/photo.jpg');
$fromBytes = Image::fromBytes($binaryContents);
$fromBase64 = Image::fromBase64($base64Contents);
$fromStorage = Image::fromStorage('originals/photo.jpg', 's3');
$fromDisk = Storage::disk('s3')->image('originals/photo.jpg');

Most sources are lazy. Laravel reads or downloads the actual contents when output or metadata is requested.

Do not pass an untrusted user URL directly to fromUrl(). A controlled downloader should limit redirects and response size, reject private network destinations, set a short timeout, and confirm the media type first.

Immutability changes how variants are built

Every transformation and output option clones the image. The source pipeline does not change.

use Illuminate\Support\Facades\Image;

$source = Image::fromPath(storage_path('app/source/product.jpg'))
    ->orient();

$thumbnail = $source
    ->cover(400, 400)
    ->toWebp()
    ->quality(78);

$detail = $source
    ->scale(width: 1600)
    ->toWebp()
    ->quality(84);

$openGraph = $source
    ->cover(1200, 630)
    ->toJpg()
    ->quality(85);

This makes branching predictable. Adding cover() to $thumbnail cannot accidentally resize $detail.

There is one related boundary: an Image object cannot be serialized. Do not put one on a queued job. Store the original first, then dispatch the storage path or your own asset identifier.

Choose the transformation that matches the layout

Laravel 13.20 exposes these transformations:

Method	Use it when
`cover()`	The output must fill exact dimensions and cropping is acceptable.
`contain()`	The complete image must fit inside a box without cropping.
`crop()`	You need a specific rectangular region.
`resize()`	You intentionally want exact dimensions, even if the aspect ratio changes.
`scale()`	You want proportional resizing from one target dimension.
`rotate()`	The application needs an explicit rotation.
`orient()`	Uploaded photos should respect orientation metadata.
`blur()`	You need a blur effect or low-resolution placeholder.
`sharpen()`	A resized output needs measured sharpening.
`grayscale()`	The output should be converted to grayscale.
`flipVertically()` or `flip()`	The image should be flipped vertically.
`flipHorizontally()` or `flop()`	The image should be flipped horizontally.

Prefer cover() for fixed cards and avatars, contain() when the whole product or logo must remain visible, and scale() for responsive width variants.

Convert and inspect output

Laravel 13.20 provides explicit WebP and JPEG output methods:

use Illuminate\Support\Facades\Image;

$source = Image::fromPath(storage_path('app/source/product.jpg'));

$webp = $source
    ->scale(width: 1200)
    ->toWebp()
    ->quality(82)
    ->optimize();

$jpeg = $source
    ->cover(1200, 630)
    ->toJpg()
    ->quality(85);

toJpeg() is also available as an alias for toJpg().

Using the $webp pipeline created above, you can inspect or export processed output with methods such as:

$width = $webp->width();
$height = $webp->height();
$dimensions = $webp->dimensions();
$mimeType = $webp->mimeType();
$extension = $webp->extension();
$bytes = $webp->toBytes();
$base64 = $webp->toBase64();
$dataUri = $webp->toDataUri();

Store paths and image metadata in the database, not the Image instance or a large Base64 value.

A production avatar workflow

A safe workflow preserves the previous asset until both the new file and database update succeed. The following shortened example shows the important boundary:

use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;
use RuntimeException;
use Throwable;

public function updateAvatar(Request $request)
{
    $request->validate([
        'avatar' => [
            'required',
            'image',
            'mimes:jpeg,png,webp',
            'max:5120',
            'dimensions:min_width=200,min_height=200,max_width=6000,max_height=6000',
        ],
    ]);

    $source = $request->image('avatar');

    abort_if($source === null, 422, 'A valid avatar image is required.');

    $user = $request->user();

    abort_if($user === null, 401);

    $path = "avatars/{$user->getKey()}/".Str::uuid().'.webp';

    $stored = $source
        ->orient()
        ->cover(512, 512)
        ->toWebp()
        ->quality(82)
        ->storeAs($path, disk: 'public');

    if ($stored === false) {
        throw new RuntimeException('The avatar could not be stored.');
    }

    try {
        DB::transaction(function () use ($user, $path): void {
            $user->forceFill(['avatar_path' => $path])->save();
        });
    } catch (Throwable $exception) {
        Storage::disk('public')->delete($path);

        throw $exception;
    }

    return back()->with('status', 'Avatar updated.');
}

In a full replacement workflow, keep the old path before the transaction and delete it only after the new path is active. Versioned filenames prevent a failed write from destroying the last known good asset.

Move expensive work to a queue

Small avatars may be reasonable to process during a request. Large originals, many variants, and batch imports usually belong on a queue.

A reliable sequence is:

Validate and store the original upload.
Create an asset record with a pending state.
Dispatch a job with the asset identifier or storage path.
Load the source from storage in the job.
Generate every required variant.
Mark the asset ready only after all required writes succeed.
Record failures and allow controlled retries.

Keep retry operations idempotent. A job should produce the same variant paths or replace them through an explicit versioning policy.

Production checks worth keeping

The convenient facade does not remove the operational work around image processing:

Validate MIME type, compressed size, and pixel dimensions before decoding.
Decide whether animated input is allowed.
Set web server, PHP, worker memory, and worker timeout limits.
Cap the number of generated variants.
Re-encode accepted input instead of keeping an uploaded file as the public derivative.
Check every storage return value because storage methods return string|false.
Monitor processing time, failures, and worker memory.
Clean abandoned originals and partial variants.
Store final width, height, MIME type, and path with each asset variant.

A small compressed file can expand into a large in-memory bitmap. Test the limits with real source dimensions and formats in your production container.

Should an existing application migrate?

The new API does not require an immediate rewrite. Start with one contained workflow, such as avatars or product thumbnails, then compare the old and new output:

Crop and scale behavior
EXIF orientation
Output dimensions
MIME type and extension
File size at the selected quality
Transparency and background behavior
Animated input behavior, if supported by the product

If the application depends on Intervention operations that Laravel's smaller API does not expose, keep direct Intervention usage for that workflow. If an external image CDN handles dynamic delivery and caching, Laravel's local component does not automatically replace it.

Laravel 13.20 makes the common path more consistent. It does not eliminate the need for input policy, storage design, queues, observability, or realistic performance testing.

The complete Laravel 13.20 Image facade guide includes every released source, transformation, storage method, a multi-variant avatar controller, responsive image markup, migration guidance, tests, and the exact implementation details verified against the v13.20.0 tag.

Sources

🚀 How to Add Dynamic Blog Content to Your AI Email Builder (Laravel + React)

Gurinder Chauhan — Fri, 24 Oct 2025 23:27:03 +0000

Tired of static email templates? In this tutorial, we’ll show you how to integrate dynamic content — like blog posts, podcasts, or live updates — into your AI Email Builder. By the end, you’ll have a fully dynamic email template that automatically populates content without writing any frontend logic.

We’ll use Laravel and React in this example, but the same principles apply to Inertia Vue.js, Livewire, and FilamentPHP setups. You can explore the official builder at https://emailbuilder.dev.

Prerequisites

Before you start, make sure you have:

A Laravel project with AI Email Builder installed.
Any supported frontend: Inertia React, Inertia Vue.js, Livewire, or FilamentPHP.
Some blog posts already stored in your database.

If you haven’t installed the Email Builder yet, follow the guides at https://emailbuilder.dev.

Step 1: Scaffold a Custom Blog Element

Open your terminal and run the command to scaffold a custom element:

php artisan email-builder:custom-element-scaffold

The command will prompt you for a Custom Element ID. Enter: blog

Next, it will ask if the element is loopable. Choose yes since newsletters often contain multiple blog posts.

This will create a Blog.php file inside App\EmailBuilder\CustomElements.

Step 2: Define Blog Placeholders in `Blog.php`

Open Blog.php. The first step is to define placeholders that map to the blog post fields returned by the API. These placeholders will automatically populate the email content.

protected array $placeholders = [
    'loopId'          => '__LOOP_ITEM_ID__',
    'loopTitle'       => '__LOOP_ITEM_TITLE__',
    'loopDescription' => '__LOOP_ITEM_DESCRIPTION__',
    'loopPublishAt'   => '__LOOP_ITEM_PUBLISH_AT__',
    'loopAuthor'      => '__LOOP_ITEM_AUTHOR__',
    'loopCategory'    => '__LOOP_ITEM_CATEGORY__',
    'loopImage'       => '__LOOP_ITEM_IMAGE__',
    'loopLink'        => '__LOOP_ITEM_LINK__',
];

Step 3: Add the API Source URL

Next, point the custom element to the API route where blog posts will be fetched.

public function sourceUrl(): string
{
    return route('api.email-builder.dynamic-data.blog-posts.index');
}

Step 4: Build the Blog Schema

The build method defines the structure, styling, and behavior of your blog element. It contains:

Custom element info (ID, name, icon)
Structural schema (how emails render selected posts)
Source information (API instructions and pagination)
Result map (maps API fields to placeholders)
Display schema (how posts appear in the selection window)

Here’s the main structure:

public function build(): static
{
    $this->schema = [
        'id'          => 'blog',
        'name'        => 'Blog',
        'title'       => 'Display Blog items',
        'description' => 'Add Blog items in the email.',
        'loopable'    => true,
        'dynamic'     => true,
        'icon'        => 'svg:<svg ...></svg>',
        'schema'      => [
            'featured-content' => [
                $this->makeSection(stack: false, config: ['padding' => '10px', 'background-color' => '#ffffff'], content: $this->itemContent(featured: true)),
            ],
            'content' => [
                $this->makeSection(stack: true, config: ['padding' => '10px', 'background-color' => '#ffffff'], content: $this->itemContent()),
            ],
        ],
        'source'      => PaginationSource::make()
            ->sourceUrl($this->options['sourceUrl'])
            ->paginated()
            ->sorts([
                ['label' => 'Latest', 'value' => 'orderBy=latest'],
                ['label' => 'Oldest', 'value' => 'orderBy=oldest'],
            ])
            ->toArray(),
        'resultMap'   => [
            'fields' => [
                'LOOP_ITEM_ID'          => 'id',
                'LOOP_ITEM_TITLE'       => 'title',
                'LOOP_ITEM_DESCRIPTION' => 'description',
                'LOOP_ITEM_PUBLISH_AT'  => 'published_at',
                'LOOP_ITEM_AUTHOR'      => 'author',
                'LOOP_ITEM_CATEGORY'    => 'category',
                'LOOP_ITEM_IMAGE'       => 'image',
                'LOOP_ITEM_LINK'        => 'link',
            ],
        ],
        'display'     => [
            'type'     => 'card',
            'template' => $this->itemDisplaySchema(),
        ],
    ];

    return $this;
}

Step 5: Understand the `itemContent` Method

The itemContent method defines how each blog item is rendered inside the email body.

Featured items occupy 100% width
Regular items occupy 50% width for two-column layout
Includes image, title, description, category, and a Read More button

protected function itemContent(bool $featured = false): array
{
    return [
        $this->makeColumn(
            width: $featured ? '100%' : '50%',
            config: ['padding' => '0px'],
            content: [
                $this->makeImage(
                    src: $this->placeholderLoopImage(),
                    href: $this->placeholderLoopLink(),
                    config: ['padding' => '0'],
                ),
            ],
        ),
        $this->makeColumn(
            width: $featured ? '100%' : '50%',
            config: ['padding' => '10px', 'vertical-align' => 'top'],
            content: [
                $this->makeText(
                    text: $this->placeholderLoopTitle(),
                    config: ['font-size' => $featured ? '16px' : '14px', 'font-weight' => '700', 'color' => '#ef4444', 'padding' => '0 0 10px 0']
                ),
                $this->makeText(
                    text: $this->placeholderLoopDescription(),
                    config: ['font-size' => '12px', 'font-weight' => '500', 'color' => '#475569', 'padding' => '0 0 10px 0']
                ),
                $this->makeText(
                    text: "Category: {$this->placeholderLoopCategory()}",
                    config: ['font-size' => '12px', 'font-weight' => '500', 'color' => '#475569', 'padding' => '0 0 10px 0']
                ),
                $this->makeButton(
                    text: "Read More",
                    config: [
                        'href'    => $this->placeholderLoopLink(),
                        'padding' => '0 0 10px 0',
                        'align'   => 'left',
                    ]
                ),
            ],
        ),
    ];
}

Step 6: Understand the `itemDisplaySchema` Method

The itemDisplaySchema method defines how items appear in the Email Builder selection window:

Each blog item is a card with image, title, description, and metadata
Supports a loopable content layout for multiple items
Inline CSS ensures styling is consistent

protected function itemDisplaySchema(): array
{
    return [
        'config'          => [
            'style' => $this->displayStyleTagContent(),
        ],
        'wrap'            => [
            'className' => 'blog-items-wrap',
        ],
        'loopableContent' => [
            "type"      => "div",
            "className" => "blog-item",
            "loopable"  => true,
            "content"   => [
                [
                    "type"      => "div",
                    "className" => "blog-featured-img-wrap",
                    "style"     => "display: flex;",
                    "content"   => [
                        ["type" => "img", "className" => "blog-featured-img", "src" => "__LOOP_ITEM_IMAGE__", "alt" => "Placeholder"],
                    ],
                ],
                [
                    "type"      => "div",
                    "className" => "blog-detail",
                    "content"   => [
                        ["type" => "h3", "className" => "blog-title", "text" => "__LOOP_ITEM_TITLE__"],
                        ["type" => "p", "className" => "blog-description", "text" => "__LOOP_ITEM_DESCRIPTION__"],
                        ["type" => "div", "className" => "blog-meta", "style" => "display: flex; gap: 16px;", "content" => [
                            ["type" => "p", "className" => "blog-meta-date", "text" => "__LOOP_ITEM_PUBLISH_AT__"],
                            ["type" => "p", "className" => "blog-meta-author", "text" => "__LOOP_ITEM_AUTHOR__"],
                            ["type" => "p", "className" => "blog-meta-category", "text" => "__LOOP_ITEM_CATEGORY__"],
                            ["type" => "a", "className" => "blog-meta-link", "text" => "Link", "href" => "__LOOP_ITEM_LINK__"],
                        ]],
                    ],
                ],
            ],
        ],
    ];
}

Step 7: Create the Blog API Endpoint

In your api.php file, add a route to serve blog posts:

Route::middleware(['auth', 'auth:sanctum'])->group(function () {
    Route::get(
        '/email-builder/dynamic-data/blog-posts',
        [PostsController::class, 'emailBuilderList']
    )->name('api.email-builder.dynamic-data.blog-posts.index');
});

Step 8: Implement `emailBuilderList` in `PostsController`

This method returns blog posts in a JSON format for the Email Builder. It supports pagination, search, and ordering.

public function emailBuilderList(Request $request)
{
    $perPage = $request->get('perPage') ?: 20;
    $page    = $request->get('page') ?: 1;

    $result = Post::query()
        ->when(filled($request->get('query')), fn($q) => $q->where('title', 'like', '%' . $request->get('query') . '%'))
        ->when($request->get('orderBy') === 'latest', fn($q) => $q->orderByDesc('published_at'))
        ->when($request->get('orderBy') === 'oldest', fn($q) => $q->orderBy('published_at', 'asc'))
        ->paginate(perPage: $perPage > 100 ? 20 : $perPage, page: $page)
        ->through(fn($model) => [
            'id'           => $model->id,
            'title'        => $model->title,
            'description'  => $model->description,
            'image'        => $model->image,
            'author'       => $model->author,
            'published_at' => Carbon::parse($model->published_at)->format('M d, Y'),
            'category'     => $model->category,
            'link'         => $model->link,
        ]);

    return response()->json([
        'status' => 'success',
        'result' => $result,
    ]);
}

Step 9: Drag and Drop Blog Content in Email Builder

Once your Blog custom element is ready, go to your Email Builder dashboard:

Add your saved header and footer blocks to the canvas.
Open the elements panel and locate the Blog element.
Drag it between the header and footer.
Select the blog posts to display — they’ll auto-populate in the email in the order you select.

Step 10: Preview and Send

The Email Builder will render your blog content dynamically. Featured items occupy full width, while regular items display in two columns. All styling is handled inline, and your selection window shows a neat card layout for each post.

Visit https://emailbuilder.dev to learn more and explore additional features.

Conclusion

With just a few steps, you can now:

Scaffold a custom blog element
Connect it to a secure API endpoint
Map placeholders for dynamic content
Build a flexible schema with featured and regular items
Control the selection window using itemDisplaySchema
Render dynamic email content with itemContent
Drag and drop blog posts into emails for instant dynamic rendering

This approach works for any dynamic content, whether it’s blog posts, podcasts, or live updates — all without touching frontend code.

Explore more about AI Email Builder: https://emailbuilder.dev

References & Docs

🚀 How I Stopped Juggling 4 Terminal Tabs Every Morning

Gurinder Chauhan — Thu, 16 Oct 2025 19:56:12 +0000

When working locally on my Laravel + Bun + Stripe stack for AI Email Builder, I used to open 4 terminal tabs every time:

bun run dev for frontend
php artisan queue:work for jobs
php artisan schedule:work for cron
and Stripe listener for webhooks

It worked… but it was annoying.

So I wrote a tiny Bash script to spin everything up in one command 👇

#!/bin/bash

BASE=$PWD

DEV_CMD="(cd $BASE && bun run dev)"
QUEUE_CMD="(cd $BASE && php artisan queue:work)"
SCHEDULE_CMD="(cd $BASE && php artisan schedule:work)"
STRIPE_CMD="(cd $BASE && zsh listen-stripe.sh)"

npx concurrently \
    -n dev,queue,schedule,stripe \
    -c green,blue,magenta,yellow \
    "$DEV_CMD" \
    "$QUEUE_CMD" \
    "$SCHEDULE_CMD" \
    "$STRIPE_CMD"

Now I just run: ./dev.sh

And everything starts together — clean, color-coded, and fast 🙌

This little script made my daily development workflow for Email Builder so much smoother.

Feel free to tweak it to match your stack too.