メインコンテンツまでスキップ
バージョン: 13.x

Image Manipulation

Introduction​

Laravelは、フレームワーク全体で採用されている表現力豊かな規約に沿って、画像のリサイズ、クロップ、エンコード、保存を行える、流れるような画像操作APIを提供します。Laravelの画像機能は Intervention Image を基盤としており、GDおよびImagickのPHP拡張機能をサポートしています。

画像 API は、アップロードされたファイル、Laravel の filesystem disks に保存されたファイル、ローカルファイル、リモート URL、または生の画像バイト列を扱う場合に便利です。

use Illuminate\Support\Facades\Image;

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

画像処理は CPU とメモリを大量に消費する可能性があります。大規模な画像処理は、アップロードを受け取る HTTP リクエスト中に実行するのではなく、queued job で処理することを検討してください。

Installation​

Laravelの画像操作機能を使用する前に、Composerを使ってIntervention Imageパッケージをインストールしてください。

composer require intervention/image:^4.0

アプリケーションで使用するドライバに応じて、PHP に GD または Imagick 拡張機能のいずれかがインストールされていることも確認してください。

Configuration​

Laravel の画像設定ファイルは config/images.php にあります。アプリケーションに images 設定ファイルがない場合は、config:publish Artisan コマンドを使用して公開できます。

php artisan config:publish images

画像設定ファイルでは、アプリケーションのデフォルト画像ドライバを指定できます。IMAGE_DRIVER 環境変数を使ってデフォルトドライバを指定することもできます。対応しているドライバは gd と imagick です。

IMAGE_DRIVER=imagick

Reading Images​

Image ファサードには、一般的なソースから画像を読み込むためのメソッドがいくつか用意されています。画像の内容は遅延読み込みされるため、通常、画像を処理するかバイト列を要求するまでソースは読み込まれません。

Uploaded Files​

受信したリクエストから、アップロードされた画像を image メソッドで取得できます。このメソッドは、アップロードされたファイルの Illuminate\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');

    // ...
});

または、fromUpload メソッドを使用して、Illuminate\Http\UploadedFile インスタンスから画像インスタンスを作成することもできます。

use Illuminate\Support\Facades\Image;

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

画像をアップロードされたファイルから作成した場合は、file メソッドを使って元のアップロードファイルを取得できます。

$file = $image->file();

Storage Files​

アプリケーションの filesystem disks に保存されているファイルから、fromStorage メソッドを使って画像インスタンスを作成できます。第1引数にはファイルのパスを、第2引数にはディスク名を指定します。

use Illuminate\Support\Facades\Image;

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

ファイルシステムディスクのインスタンスから image メソッドを使って直接イメージのインスタンスを作成することもできます。

use Illuminate\Support\Facades\Storage;

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

Other Sources​

Image ファサードには、バイト列、ローカルファイルパス、リモート 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');

Manipulating Images​

画像インスタンスは不変です。各操作メソッドは、変換を処理パイプラインに追加した新しい画像インスタンスを返すため、メソッドを流れるようにチェーンできます。

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

変換は画像パイプラインに追加された順序で処理され、画像は最後に一度だけエンコードされます。

Resizing Images​

resize メソッドは、指定したサイズに画像をリサイズします。幅と高さの両方を指定することも、名前付き引数を使って一方のサイズだけを指定することもできます。

$image = $image->resize(800, 600);
$image = $image->resize(width: 800);
$image = $image->resize(height: 600);

scale メソッドは、画像が指定された寸法内に収まるよう、縦横比を維持したまま縮小します。このメソッドで画像が拡大されることはありません。

$image = $image->scale(800, 600);
$image = $image->scale(width: 800);
$image = $image->scale(height: 600);

cover メソッドは、指定されたサイズ全体を覆うように画像のサイズを変更し、トリミングします。

$image = $image->cover(400, 400);

contain メソッドは、画像全体を維持したまま、指定されたサイズ内に収まるよう画像のサイズを変更します。必要に応じて、空いた領域をオプションの背景色で塗りつぶします。

$image = $image->contain(400, 400);
$image = $image->contain(400, 400, '#ffffff');
$image = $image->contain(400, 400, 'dominant');

画像の主要な色を使って空白を塗りつぶす背景色として、dominant を指定できます。

crop メソッドを使用して画像をトリミングできます。最初の2つの引数には必要な幅と高さを指定し、3番目と4番目のオプション引数にはトリミング範囲の x 座標と y 座標を指定します。

$image = $image->crop(300, 200);
$image = $image->crop(300, 200, x: 50, y: 25);

Other Transformations​

Laravel には、画像を変換する追加のメソッドもさまざまに用意されています。

$image = $image->orient();
$image = $image->rotate(90);
$image = $image->rotate(90, '#ffffff');
$image = $image->rotate(90, 'dominant');
$image = $image->blur(5);
$image = $image->grayscale();
$image = $image->sharpen(10);
$image = $image->flipVertically();
$image = $image->flipHorizontally();

orient メソッドは、画像の EXIF の向き情報に従って画像を回転させます。rotate メソッドは、指定した角度で画像を時計回りに回転させ、オプションで背景色を指定できます。blur メソッドと sharpen メソッドには、0 から 100 までの値を指定できます。

Conditional Transformations​

画像インスタンスは Laravel の 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());

Encoding Images​

デフォルトでは、処理済みの画像は元の形式でエンコードされます。ただし、取得または保存する前に、画像をサポートされている別の形式へ変換できます。

$image = $image->toWebp();
$image = $image->toJpg();
$image = $image->toJpeg();
$image = $image->toPng();
$image = $image->toGif();
$image = $image->toAvif();
$image = $image->toBmp();

quality メソッドを使用して出力品質を設定できます。品質は 1 から 100 の範囲に収まるよう制限されます。

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

optimize メソッドは、画像を指定した形式に変換し、品質を設定する便利なショートカットです。デフォルトでは、画像は品質 70 の WebP 画像として最適化されます。

$image = $image->optimize();

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

処理済みの画像コンテンツは、バイト列、Base64エンコード文字列、またはデータ URI として取得できます。

$bytes = $image->toBytes();
$base64 = $image->toBase64();
$dataUri = $image->toDataUri();

画像インスタンスを文字列に cast して、データ URI を取得することもできます。

$dataUri = (string) $image;

Storing Images​

store メソッドは、処理済みの画像をアプリケーションのファイルシステムディスクのいずれかに保存します。アップロードされたファイルと同様に、Laravel は一意のファイル名を生成し、保存先のパスを返します。第 2 引数を使用してディスクを指定できます。

$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');

storePublicly および storePubliclyAs メソッドは、画像を public の可視性で保存します。

$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 を返します。

Inspecting Images​

次のメソッドを使用すると、画像の MIME タイプ、拡張子、寸法、幅、高さ、主要な色を取得できます。

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

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

$dominantColor = $image->dominantColor();

これらのメソッドは、処理済みの画像に対して動作します。たとえば、cover(400, 400) の後に width を呼び出すと、400 が返されます。

Image Drivers​

Custom Image Drivers​

Laravel のイメージマネージャは、Laravel の基底クラスである Illuminate\Support\Manager を継承しています。これにより、イメージマネージャと Image ファサードで利用できる extend メソッドを使って、カスタムイメージドライバを登録できます。

カスタム画像ドライバは、Illuminate\Contracts\Image\Driver インターフェースを実装する必要があります。process メソッドは元の画像コンテンツと、画像に適用する順序付けられた Illuminate\Image\ImagePipeline を受け取り、処理済みの画像バイト列を返します。

<?php

namespace App\Images;

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

class VipsDriver implements Driver
{
    /**
     * Process the given image contents with the specified pipeline.
     */
    public function process(string $contents, ImagePipeline $pipeline): string
    {
        // Apply the pipeline's transformations and output options...

        return $contents;
    }

    /**
     * Register a transformation handler.
     */
    public function transformUsing(string $transformation, callable $callback): static
    {
        // Store the handler so it may be applied while processing the pipeline...

        return $this;
    }
}

カスタム画像ドライバの実装方法をより深く理解するには、フレームワークに組み込まれている Illuminate\Image\Drivers\InterventionDriver クラスを確認してください。

カスタムドライバを実装したら、Image ファサードの extend メソッドを使って登録できます。通常は、サービスプロバイダの boot メソッドで登録します。

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Image::extend('vips', function (Application $app) {
        return new VipsDriver;
    });
}

ドライバを登録したら、using メソッドを使って特定の画像で使用できます。

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

config/images.php 設定ファイルの default オプションまたは IMAGE_DRIVER 環境変数を使用して、カスタムドライバをアプリケーションのデフォルト画像ドライバとして設定することもできます。

IMAGE_DRIVER=vips

Custom Transformations​

アプリケーションやパッケージでは、Illuminate\Contracts\Image\Transformation コントラクトを実装するクラスを作成して、カスタム変換を定義できます。定義したカスタム変換は、transform メソッドを使って画像パイプラインに追加できます。

<?php

namespace App\Images\Transformations;

use Illuminate\Contracts\Image\Transformation;

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

次に、Image ファサードの transformUsing メソッドを使って、変換とドライバのハンドラを登録します。通常は、サービスプロバイダの 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);
});

変換ハンドラを登録したら、画像に変換を適用できます。

use App\Images\Transformations\Pixelate;

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