画像加工

はじめに

Laravel は Image ファサードを通じて、流暢な画像加工 API を提供します。リサイズ・クロップ・エンコード・保存などの操作をフレームワーク全体で一貫した表現方法で記述できます。内部的には Intervention Image を利用しており、PHP の GD 拡張と Imagick 拡張の両方をサポートしています。

use Illuminate\Support\Facades\Image;

$path = Image::fromStorage('avatars/photo.jpg', 'public')
    ->cover(400, 400)
    ->toWebp()
    ->quality(80)
    ->storePublicly('avatars', 'public');

画像処理は CPU とメモリを大量に消費する可能性があります。大規模な画像処理は HTTP リクエスト中に行わず、キュージョブとして処理することを検討してください。

この機能は Laravel v13.20.0 以上 で利用できます。古いバージョンを使用している場合は composer update でフレームワークを最新版に更新してください。

インストール

画像加工機能を使用する前に、Composer で Intervention Image パッケージをインストールします。

composer require intervention/image:^4.0

また、使用するドライバーに応じて PHP の GD 拡張または Imagick 拡張がインストールされていることを確認してください。

設定

設定ファイルは config/image.php に配置されます。設定ファイルが存在しない場合は Artisan コマンドで公開します。

php artisan config:publish image

デフォルトのドライバーは設定ファイルまたは環境変数 IMAGE_DRIVER で指定できます。サポートされているドライバーは gd と imagick です。

IMAGE_DRIVER=imagick

画像の読み込み

Image ファサードはさまざまなソースから画像インスタンスを生成するメソッドを提供します。画像の内容は遅延読み込みされるため、処理またはバイト列の要求があるまで実際には読み込まれません。

アップロードファイル

リクエストからアップロードされた画像を取得するには image メソッドを使います。ファイルが存在しない場合は null を返します。

use Illuminate\Http\Request;

Route::post('/avatar', function (Request $request) {
    $request->validate(['avatar' => ['required', 'image']]);

    $path = $request->image('avatar')
        ->cover(400, 400)
        ->toWebp()
        ->storePublicly('avatars', 'public');

    // ...
});

UploadedFile インスタンスから生成する場合は fromUpload メソッドを使います。

use Illuminate\Support\Facades\Image;

$image = Image::fromUpload($request->file('avatar'));

アップロードファイルから生成した画像インスタンスは file メソッドで元のファイルを取得できます。

$file = $image->file();

ストレージファイル

ファイルシステムディスクに保存されているファイルから画像インスタンスを生成するには fromStorage メソッドを使います。第一引数はファイルパス、第二引数はディスク名です。

use Illuminate\Support\Facades\Image;

$image = Image::fromStorage('avatars/photo.jpg', disk: 'public');

Storage ファサードの image メソッドからも生成できます。

use Illuminate\Support\Facades\Storage;

$image = Storage::disk('public')->image('avatars/photo.jpg');

その他のソース

バイト列・ローカルパス・URL・Base64 からも画像インスタンスを生成できます。

use Illuminate\Support\Facades\Image;

$image = Image::fromBytes($contents);
$image = Image::fromBase64($base64);
$image = Image::fromPath(storage_path('app/avatars/photo.jpg'));
$image = Image::fromUrl('https://example.com/photo.jpg');

画像の加工

画像インスタンスはイミュータブルです。各メソッドは変換を処理パイプラインに追加した新しいインスタンスを返すため、メソッドチェーンで記述できます。変換はパイプラインに追加した順に処理され、エンコードは最後に一度だけ行われます。

$image = $request->image('avatar')
    ->orient()
    ->cover(400, 400)
    ->sharpen(10);

リサイズ

メソッド	説明
`resize(800, 600)`	指定サイズにリサイズ。幅または高さのみも指定可
`scale(800, 600)`	比率を保ちながら指定サイズ内に収まるよう縮小。拡大はしない
`cover(400, 400)`	指定サイズを完全に覆うようリサイズ＋クロップ
`contain(400, 400)`	比率を保ちながら指定サイズ内に収まるようリサイズ。余白は背景色で塗りつぶし
`crop(300, 200)`	指定サイズでクロップ。`x`・`y` 座標も指定可

$image = $image->resize(800, 600);
$image = $image->resize(width: 800);       // 幅のみ
$image = $image->scale(800, 600);
$image = $image->cover(400, 400);
$image = $image->contain(400, 400, '#ffffff');
$image = $image->crop(300, 200, x: 50, y: 25);

その他の変換

$image = $image->orient();            // EXIF の向き情報に従って回転
$image = $image->rotate(90);          // 時計回りに 90° 回転
$image = $image->rotate(90, '#ffffff'); // 背景色を指定して回転
$image = $image->blur(5);             // ぼかし（0〜100）
$image = $image->grayscale();         // グレースケール
$image = $image->sharpen(10);         // シャープ化（0〜100）
$image = $image->flipVertically();    // 上下反転
$image = $image->flipHorizontally();  // 左右反転

条件付き変換

画像インスタンスは Conditionable トレイトをサポートしており、when / unless で条件付きの変換が可能です。

$image = $request->image('avatar')
    ->when($request->boolean('crop'), fn ($image) => $image->cover(400, 400))
    ->unless($request->boolean('preserve_format'), fn ($image) => $image->toWebp());

エンコード

デフォルトでは元のフォーマットでエンコードされます。フォーマットを変換するには以下のメソッドを使います。

$image = $image->toWebp();
$image = $image->toJpg();
$image = $image->toJpeg();

quality メソッドで出力品質（1〜100）を設定できます。

$image = $image->toWebp()->quality(80);

optimize メソッドはフォーマット変換と品質設定のショートカットです。デフォルトは WebP・品質 70 です。

$image = $image->optimize();
$image = $image->optimize(format: 'jpg', quality: 85);

バイト列・Base64・Data URI として取得することもできます。

$bytes   = $image->toBytes();
$base64  = $image->toBase64();
$dataUri = $image->toDataUri();
$bytes   = (string) $image; // 文字列キャスト

保存

store メソッドで画像をファイルシステムディスクに保存します。Laravel は一意なファイル名を自動生成し、保存パスを返します。

$path = $request->image('avatar')
    ->cover(400, 400)
    ->store(path: 'avatars');

$path = $request->image('avatar')
    ->cover(400, 400)
    ->store(path: 'avatars', disk: 's3');

ファイル名を指定する場合は storeAs を使います。

$path = $request->image('avatar')
    ->cover(400, 400)
    ->storeAs(path: 'avatars', name: 'avatar.jpg', disk: 'public');

public 可視性で保存する場合は storePublicly / storePubliclyAs を使います。

$path = $request->image('avatar')
    ->cover(400, 400)
    ->storePublicly(path: 'avatars', disk: 'public');

$path = $request->image('avatar')
    ->cover(400, 400)
    ->storePubliclyAs(path: 'avatars', name: 'avatar.webp', disk: 'public');

保存に失敗した場合は false を返します。

画像情報の取得

mimeType・extension・dimensions・width・height メソッドで画像の情報を取得できます。これらのメソッドは処理後の画像を対象とします（例：cover(400, 400) 後に width() を呼ぶと 400 を返します）。

$mimeType = $image->mimeType();
$extension = $image->extension();

[$width, $height] = $image->dimensions();
$width  = $image->width();
$height = $image->height();

カスタムドライバー

Laravel の画像マネージャーは Illuminate\Support\Manager を継承しており、extend メソッドでカスタムドライバーを登録できます。カスタムドライバーは Illuminate\Contracts\Image\Driver インターフェースを実装し、process メソッドで元の画像バイト列とパイプラインを受け取り、処理済み画像バイト列を返します。

<?php

namespace App\Images;

use Illuminate\Contracts\Image\Driver;
use Illuminate\Image\ImagePipeline;

class VipsDriver implements Driver
{
    public function process(string $contents, ImagePipeline $pipeline): string
    {
        // パイプラインの変換と出力オプションを適用...
        return $contents;
    }

    public function transformUsing(string $transformation, callable $callback): static
    {
        // ハンドラーを保存して処理中に適用できるようにする...
        return $this;
    }
}

登録はサービスプロバイダーの boot メソッドで行います。

use App\Images\VipsDriver;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\Image;

public function boot(): void
{
    Image::extend('vips', function (Application $app) {
        return new VipsDriver;
    });
}

特定の画像に対してドライバーを指定するには using メソッドを使います。

$image = $request->image('avatar')
    ->using('vips')
    ->cover(400, 400);

カスタム変換

Illuminate\Contracts\Image\Transformation インターフェースを実装したクラスでカスタム変換を定義できます。

<?php

namespace App\Images\Transformations;

use Illuminate\Contracts\Image\Transformation;

class Pixelate implements Transformation
{
    public function __construct(
        public readonly int $size,
    ) {}
}

ハンドラーの登録はサービスプロバイダーの boot メソッドで行います。

use App\Images\Transformations\Pixelate;
use Illuminate\Support\Facades\Image;
use Intervention\Image\Interfaces\ImageInterface;

Image::transformUsing('gd', Pixelate::class, function (ImageInterface $image, Pixelate $transformation) {
    return $image->pixelate($transformation->size);
});

登録後は transform メソッドで適用します。

use App\Images\Transformations\Pixelate;

$image = $request->image('avatar')
    ->transform(new Pixelate(12))
    ->store('avatars');

アーキテクチャ

データベース

Eloquent

セキュリティ

イベント

メールと通知

決済

非同期処理

リアルタイム通信

スケジューリング

キャッシュと最適化

国際化

ファイルとストレージ

デバッグと監視

コンソールとCLI

パフォーマンス

フロントエンド

AI開発

開発環境

はじめに

インストール

設定

画像の読み込み

アップロードファイル

ストレージファイル

その他のソース

画像の加工

リサイズ

その他の変換

条件付き変換

エンコード

保存

画像情報の取得

カスタムドライバー

カスタム変換

​はじめに

​インストール

​設定

​画像の読み込み

​アップロードファイル

​ストレージファイル

​その他のソース

​画像の加工

​リサイズ

​その他の変換

​条件付き変換

​エンコード

​保存

​画像情報の取得

​カスタムドライバー

​カスタム変換

はじめに

インストール

設定

画像の読み込み

アップロードファイル

ストレージファイル

その他のソース

画像の加工

リサイズ

その他の変換

条件付き変換

エンコード

保存

画像情報の取得

カスタムドライバー

カスタム変換