이미지 가공

시작하기

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 개발

개발 환경