이미지 조작

업데이트됨

번역일: 2026년 8월 13일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 8월 13일
번역 갱신: 2026년 8월 13일

이미지 조작

소개
설치
- 설정
이미지 읽기
이미지 조작하기
- 이미지 크기 조정
- 기타 변환
이미지 인코딩
이미지 저장
이미지 정보 확인
이미지 드라이버
- 커스텀 이미지 드라이버
- 커스텀 변환

소개

Laravel은 이미지 크기 조정, 크롭, 인코딩, 저장 등을 유창하게(fluent) 처리할 수 있는 이미지 조작 API를 제공합니다. 이 기능은 Intervention Image 패키지를 기반으로 하며, GD와 Imagick PHP 확장을 모두 지원합니다.

업로드된 파일, 파일시스템 디스크에 저장된 파일, 로컬 경로, 원격 URL, 또는 원시 이미지 바이트 등 다양한 소스에서 이미지를 읽어 처리할 수 있습니다.

use Illuminate\Support\Facades\Image;

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

WARNING

이미지 처리는 CPU와 메모리를 많이 소비할 수 있습니다. 대량의 이미지 처리 작업은 HTTP 요청 도중 직접 처리하기보다 큐 Job으로 분리하는 것을 권장합니다.

설치

이미지 조작 기능을 사용하려면 먼저 Composer로 Intervention Image 패키지를 설치합니다.

composer require intervention/image:^4.0

또한 사용할 드라이버에 따라 PHP에 GD 또는 Imagick 확장이 설치되어 있는지 확인해야 합니다.

설정

이미지 설정 파일은 config/images.php에 위치합니다. 해당 파일이 없다면 다음 Artisan 명령어로 게시할 수 있습니다.

php artisan config:publish images

설정 파일에서 기본 이미지 드라이버를 지정할 수 있으며, IMAGE_DRIVER 환경 변수로도 설정 가능합니다. 지원하는 드라이버는 gd와 imagick입니다.

IMAGE_DRIVER=imagick

이미지 읽기

Image 파사드는 다양한 소스에서 이미지를 읽어오는 메서드를 제공합니다. 이미지 내용은 지연 로딩(lazy loading) 방식으로 읽히므로, 실제로 이미지를 처리하거나 바이트를 요청하는 시점에 소스가 읽힙니다.

업로드된 파일

요청으로 업로드된 이미지를 가져오려면 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');

    // ...
});

Illuminate\Http\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');

파일시스템 디스크 인스턴스에서 직접 image 메서드를 호출하는 방법도 있습니다.

use Illuminate\Support\Facades\Storage;

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

기타 소스

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

이미지 조작하기

이미지 인스턴스는 불변(immutable) 객체입니다. 각 조작 메서드는 변환이 파이프라인에 추가된 새로운 이미지 인스턴스를 반환하므로, 메서드 체이닝을 자연스럽게 사용할 수 있습니다.

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

변환은 파이프라인에 추가된 순서대로 처리되며, 이미지는 마지막에 한 번만 인코딩됩니다.

이미지 크기 조정

resize 메서드는 이미지를 지정한 너비와 높이로 조정합니다. 너비와 높이를 모두 지정하거나, 이름 있는 인자(named argument)를 사용해 하나만 지정할 수도 있습니다.

$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 메서드는 이미지 전체가 보이도록 지정한 크기 안에 맞추며, 남는 공간은 배경색으로 채웁니다. dominant를 지정하면 이미지의 주요 색상으로 빈 공간을 채웁니다.

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

crop 메서드로 이미지를 원하는 크기로 잘라낼 수 있습니다. 처음 두 인자는 너비와 높이이며, 선택적으로 크롭 시작점의 x, y 좌표를 지정할 수 있습니다.

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

기타 변환

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 사이의 값을 인자로 받습니다.

조건부 변환

이미지 인스턴스는 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());

이미지 인코딩

기본적으로 처리된 이미지는 원본 형식 그대로 인코딩됩니다. 이미지를 저장하거나 가져오기 전에 다른 형식으로 변환하려면 아래 메서드를 사용합니다.

$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 메서드는 형식 변환과 품질 설정을 한 번에 처리하는 편의 메서드입니다. 기본값은 WebP 형식, 품질 70입니다.

$image = $image->optimize();

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

처리된 이미지 내용을 바이트 문자열, Base64 인코딩 문자열, 또는 데이터 URI로 가져올 수 있습니다.

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

이미지 인스턴스를 문자열로 캐스팅하면 데이터 URI가 반환됩니다.

$dataUri = (string) $image;

이미지 저장

store 메서드는 처리된 이미지를 애플리케이션의 파일시스템 디스크에 저장합니다. 업로드 파일과 마찬가지로 고유한 파일명이 자동으로 생성되며, 저장된 경로가 반환됩니다. 두 번째 인자로 디스크를 지정할 수 있습니다.

$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를 반환합니다.

이미지 정보 확인

다음 메서드들로 이미지의 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이 반환됩니다.

이미지 드라이버

커스텀 이미지 드라이버

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
{
    /**
     * 지정된 파이프라인으로 이미지 내용을 처리합니다.
     */
    public function process(string $contents, ImagePipeline $pipeline): string
    {
        // 파이프라인의 변환 및 출력 옵션을 적용합니다...

        return $contents;
    }

    /**
     * 변환 핸들러를 등록합니다.
     */
    public function transformUsing(string $transformation, callable $callback): static
    {
        // 파이프라인 처리 시 적용할 수 있도록 핸들러를 저장합니다...

        return $this;
    }
}

NOTE

커스텀 이미지 드라이버 구현 방법을 이해하려면 프레임워크에 내장된 Illuminate\Image\Drivers\InterventionDriver 클래스를 참고하세요.

커스텀 드라이버를 구현한 후에는 Image 파사드의 extend 메서드로 등록합니다. 일반적으로 서비스 프로바이더의 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);

config/images.php 설정 파일의 default 옵션이나 IMAGE_DRIVER 환경 변수를 사용해 커스텀 드라이버를 기본 드라이버로 설정할 수도 있습니다.

IMAGE_DRIVER=vips

커스텀 변환

애플리케이션이나 패키지에서 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);
});

핸들러를 등록한 후에는 transform 메서드로 이미지에 커스텀 변환을 적용할 수 있습니다.

use App\Images\Transformations\Pixelate;

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