Laravel Fractal

spatie/laravel-fractal

제출자 Laravel Korea Discovery Bot

최신 v6.4.0라이센스 MIT배포 2026년 11월 7일

검색

Laravel 애플리케이션에서 쉽게 사용할 수 있는 Fractal 통합 패키지

GitHub

Laravel과 Lumen 애플리케이션을 위한 사용하기 쉬운 Fractal 래퍼

이 패키지는 Fractal을 Laravel 애플리케이션에서 편리하게 사용할 수 있도록 감싸 주는 래퍼입니다. Fractal이 무엇인지 모른다면 공식 소개 문서를 먼저 훑어보세요. 간단히 말해, Fractal은 API로 내보내기 전에 데이터를 변환(transform)할 때 매우 유용한 라이브러리입니다.

Fractal을 직접 사용하면 데이터를 다음과 같이 변환합니다.

use League\Fractal\Manager;
use League\Fractal\Resource\Collection;

$books = [
   ['id' => 1, 'title' => 'Hogfather', 'characters' => [...]],
   ['id' => 2, 'title' => 'Game Of Kill Everyone', 'characters' => [...]]
];

$manager = new Manager();

$resource = new Collection($books, new BookTransformer());

$manager->parseIncludes('characters');

$manager->createData($resource)->toArray();

이 패키지를 사용하면 같은 작업을 훨씬 간단하게 처리할 수 있습니다.

fractal()
   ->collection($books)
   ->transformWith(new BookTransformer())
   ->includeCharacters()
   ->toArray();

파사드를 좋아하는 분들을 위해 파사드도 제공됩니다.

Fractal::collection($books)->transformWith(new BookTransformer())->toArray();

데이터를 빠르게 변환할 수 있는 아주 짧은 문법도 있습니다.

fractal($books, new BookTransformer())->toArray();

Laravel 컬렉션에서 곧바로 변환할 수도 있습니다.

collect($books)->transformWith(new BookTransformer());

Laravel 컬렉션에서 바로 변환하는 방식은 특히 Eloquent 조회 결과를 다룰 때 유용합니다.

Users::all()->transformWith(new UserTransformer())->toArray();

Spatie는 벨기에 앤트워프에 있는 웹 디자인 에이전시입니다. 모든 오픈 소스 프로젝트는 Spatie 웹사이트에서 확인할 수 있습니다.

후원하기

Spatie는 최고 수준의 오픈 소스 패키지를 만드는 데 많은 노력을 기울이고 있습니다. 유료 제품 구매로 이 활동을 후원할 수 있습니다.

또한 사용 중인 패키지를 알려 주며 여러분의 고향에서 보낸 엽서를 보내 주시면 큰 힘이 됩니다. 주소는 연락처 페이지에서 확인할 수 있으며, 받은 엽서는 모두 온라인 엽서 월에 게시됩니다.

설치

이 패키지는 PHP 8.4 이상과 Laravel 13이 필요합니다.

Composer로 패키지를 설치합니다.

composer require spatie/laravel-fractal

패키지는 자동으로 등록됩니다.

기본 시리얼라이저를 변경하거나, 기본 페이지네이터를 바꾸거나, 기본 Fractal 클래스인 Spatie\Fractal\Fractal을 교체하려면 설정 파일을 퍼블리시해야 합니다.

php artisan vendor:publish --provider="Spatie\Fractal\FractalServiceProvider"

Laravel 5.5로 업그레이드하는 경우, 기존 설정 파일의 이름을 laravel-fractal.php 에서 fractal.php 로 변경해야 합니다.

퍼블리시된 설정 파일의 내용은 다음과 같습니다.

return [
    /*
     * The default serializer to be used when performing a transformation. It
     * may be left empty to use Fractal's default one. This can either be a
     * string or a League\Fractal\Serializer\SerializerAbstract subclass.
     */
    'default_serializer' => '',

    /* The default paginator to be used when performing a transformation. It
     * may be left empty to use Fractal's default one. This can either be a
     * string or a League\Fractal\Paginator\PaginatorInterface subclass.
     */
    'default_paginator' => '',

    /*
     * League\Fractal\Serializer\JsonApiSerializer will use this value
     * as a prefix for generated links. Set to `null` to disable this.
     */
    'base_url' => null,

    /*
     * If you wish to override or extend the default Spatie\Fractal\Fractal
     * instance provide the name of the class you want to use.
     */
    'fractal_class' => Spatie\Fractal\Fractal::class,

    'auto_includes' => [

        /*
         * If enabled Fractal will automatically add the includes who's
         * names are present in the `include` request parameter.
         */
        'enabled' => true,

        /*
         * The name of key in the request to where we should look for the includes to include.
         */
        'request_key' => 'include',
    ],

    'auto_excludes' => [

        /*
         * If enabled Fractal will automatically add the excludes who's
         * names are present in the `exclude` request parameter.
         */
        'enabled' => true,

        /*
         * The name of key in the request to where we should look for the excludes to exclude.
         */
        'request_key' => 'exclude',
    ],

    'auto_fieldsets' => [

        /*
         * If enabled Fractal will automatically add the fieldsets who's
         * names are present in the `fields` request parameter.
         */
        'enabled' => true,

        /*
         * The name of key in the request, where we should look for the fieldsets to parse.
         */
        'request_key' => 'fields',
    ],
];

사용법

이 패키지가 제공하는 모든 메서드는 spatie/fractalistic 문서에서 확인할 수 있습니다.

모든 코드 예제에서 Fractal::create() 대신 fractal() 헬퍼를 사용할 수 있습니다.

변환된 데이터로 응답 보내기

Laravel 앱에서 JSON 데이터를 응답으로 반환하려면 다음과 같이 할 수 있습니다.

$books = fractal($books, new BookTransformer())->toArray();

return response()->json($books);

Fractal 클래스의 respond() 메서드를 사용하면 이 과정을 조금 더 간결하게 작성할 수 있습니다.

return fractal($books, new BookTransformer())->respond();

첫 번째 인자로 응답 코드를, 두 번째 인자로 헤더를 선택적으로 전달할 수 있습니다.

return fractal($books, new BookTransformer())->respond(403, [
    'a-header' => 'a value',
    'another-header' => 'another value',
]);

세 번째 인자로는 JSON 인코딩 옵션을 전달할 수 있습니다.

return fractal($books, new BookTransformer())->respond(200, [], JSON_PRETTY_PRINT);

콜백을 사용해 상태 코드와 헤더를 설정할 수도 있습니다.

use Illuminate\Http\JsonResponse;

return fractal($books, new BookTransformer())->respond(function(JsonResponse $response) {
    $response
        ->setStatusCode(403)
        ->header('a-header', 'a value')
        ->withHeaders([
            'another-header' => 'another value',
            'yet-another-header' => 'yet another value',
        ]);
});

Laravel의 Macroable 트레이트를 이용해 Fractal 클래스에 메서드를 추가할 수 있습니다. 예를 들어 요청의 메타데이터에 통계 정보를 추가하고 싶다면, 코드를 어지럽히지 않고 다음처럼 처리할 수 있습니다.

use Spatie\Fractal\Fractal;

Fractal::macro('stats', function ($stats) {
    // transform the passed stats as necessary here
    return $this->addMeta(['stats' => $stats]);
});

fractal($books, new BookTransformer())->stats(['runtime' => 100])->respond();

트랜스포머 빠르게 만들기

make:transformer 명령을 실행하면 기본 트랜스포머를 빠르게 생성할 수 있습니다. 기본적으로 app\Transformers 디렉터리에 저장됩니다.

업그레이드

v4에서 v5로

설정 파일 이름을 laravel-fractal에서 fractal로 변경하세요.

v2에서 v3으로

v3에서는 league/fractal이 spatie/fractalistic으로 교체되었습니다. Lumen 지원은 중단되었습니다. 일반적으로 코드 변경 없이 Laravel 애플리케이션을 v2에서 v3으로 업그레이드할 수 있습니다.

v1에서 v2로

대부분의 경우 코드를 전혀 또는 거의 수정하지 않고도 v2로 업그레이드할 수 있습니다.

resourceName이 withResourceName으로 이름이 변경되었습니다.

이 패키지의 v2가 태그된 주된 이유는, 내부에서 사용하는 League의 Fractal v0.14에 호환되지 않는 변경 사항이 포함되어 있기 때문입니다. v2에서 League\Fractal\Serializer\JsonApiSerializer를 사용한다면 links 키에 self, first, next, last가 포함됩니다.

변경 내역

최근 변경 사항은 CHANGELOG를 참고하세요.

테스트

$ composer test

기여하기

자세한 내용은 CONTRIBUTING을 참고하세요.

보안

보안과 관련된 버그를 발견했다면 이슈 트래커 대신 security@spatie.be로 메일을 보내 주세요.

크레딧

라이선스

MIT 라이선스(MIT)를 따릅니다. 자세한 내용은 라이선스 파일을 참고하세요.