Laravel 패키지 개발

패키지란

Laravel에서 패키지란 애플리케이션에 기능을 추가하는 Composer 패키지입니다. 패키지에는 크게 두 종류가 있습니다.

독립형 패키지 — Laravel에 의존하지 않는 범용 PHP 라이브러리(예: Carbon, Pest)
Laravel 패키지 — 라우트, 컨트롤러, 뷰, 설정 등 Laravel과 통합된 기능을 가진 패키지

이 가이드에서는 후자, 즉 Laravel 전용 패키지 개발을 다룹니다. 패키지 개발에는 서비스 프로바이더, 파사드, 설정 파일의 배포 등 Laravel의 내부 구조에 대한 깊은 이해가 필요합니다.

패키지 테스트를 작성할 때는 Orchestra Testbench를 사용합니다. 일반 Laravel 애플리케이션과 같은 방식으로 패키지 테스트를 작성할 수 있습니다.

패키지 자동 감지

Laravel은 패키지를 설치할 때 composer.json의 extra.laravel 섹션을 읽어 서비스 프로바이더와 파사드를 자동으로 등록합니다.

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

이 설정을 추가하면, 사용자가 bootstrap/providers.php를 수동으로 편집하지 않아도 패키지가 자동으로 로드됩니다.

이 자동 감지가 어떻게 구현되고 언제 캐시가 재구성되는지는 패키지 자동 감지의 내부 구조에서 자세히 설명합니다.

자동 감지 비활성화

사용자 측에서 특정 패키지의 자동 감지를 비활성화하고 싶다면 애플리케이션의 composer.json에 설정합니다.

"extra": {
    "laravel": {
        "dont-discover": [
            "acme/courier"
        ]
    }
}

서비스 프로바이더의 역할

서비스 프로바이더는 패키지의 진입점입니다. 뷰, 설정, 마이그레이션, 라우트 등의 리소스를 Laravel에 등록하는 처리를 여기에 집중시킵니다. 서비스 프로바이더는 Illuminate\Support\ServiceProvider를 상속하며, register와 boot라는 두 개의 메서드를 갖습니다.

<?php

namespace Acme\Courier;

use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider
{
    /**
     * 패키지의 서비스를 등록한다
     */
    public function register(): void
    {
        // 서비스 컨테이너 바인딩은 여기에서 수행
        $this->mergeConfigFrom(
            __DIR__.'/../config/courier.php', 'courier'
        );

        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * 패키지의 서비스를 부트스트랩한다
     */
    public function boot(): void
    {
        // 리소스 등록은 여기에서 수행
        $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
        $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

        $this->publishesMigrations([
            __DIR__.'/../database/migrations' => database_path('migrations'),
        ]);

        $this->publishes([
            __DIR__.'/../config/courier.php' => config_path('courier.php'),
        ], 'courier-config');

        $this->publishes([
            __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
        ], 'courier-views');
    }
}

register 메서드 내에서 이벤트 리스너, 라우트, 뷰 등을 등록하지 마세요. 아직 로드되지 않은 다른 서비스 프로바이더의 서비스를 실수로 사용하게 될 수 있습니다. 바인딩 이외의 처리는 반드시 boot 메서드에서 수행합니다.

서비스가 사용될 때까지 생성하지 않고 확장하면서 이미 해석된 경우에도 설정을 반영하는 방법은 패키지의 서비스 해석 후 훅을 참고하세요. callAfterResolving()의 실행 시점과 중복 적용에 견디는 설계를 해설합니다. Octane이나 큐 워커에서도 상태를 이월하지 않는 등록 방법은 패키지 서비스의 라이프사이클 설계를 참고하세요. scoped()의 내부 구현과 singleton이 보유하는 의존성의 주의점을 해설합니다.

설정 파일 배포

publishes() — 파일 공개하기

boot 메서드에서 publishes()를 호출하면, 사용자가 vendor:publish 명령으로 설정 파일을 자신의 애플리케이션에 복사할 수 있게 됩니다.

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ]);
}

배포 후 설정값은 일반적인 config 접근과 동일한 방식으로 가져올 수 있습니다.

$value = config('courier.option');

mergeConfigFrom() — 기본값과 병합

register 메서드에서 mergeConfigFrom()을 사용하면, 사용자가 설정 파일을 배포하지 않은 경우에도 패키지의 기본값이 사용됩니다.

public function register(): void
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/courier.php', 'courier'
    );
}

mergeConfigFrom()은 중첩된 배열의 깊은 레벨까지는 병합하지 않습니다. 다차원 배열을 가진 설정에서는 사용자가 일부만 정의한 경우 나머지 옵션이 병합되지 않을 수 있습니다.

Laravel 13의 재귀적 치환 메서드와의 차이, 숫자 키 리스트의 처리, 설정 캐시를 사용하는 경우의 업데이트 절차는 패키지 설정 병합과 캐시에서 해설합니다.

태그로 배포 그룹 분리하기

publishes()의 두 번째 인수에 태그를 지정하면, 사용자가 필요한 리소스만 선택하여 배포할 수 있습니다.

public function boot(): void
{
    $this->publishes([
        __DIR__.'/../config/courier.php' => config_path('courier.php'),
    ], 'courier-config');

    $this->publishesMigrations([
        __DIR__.'/../database/migrations/' => database_path('migrations'),
    ], 'courier-migrations');
}

# 설정 파일만 배포
php artisan vendor:publish --tag=courier-config

# 프로바이더가 제공하는 모든 파일 배포
php artisan vendor:publish --provider="Acme\Courier\CourierServiceProvider"

라우트 등록

loadRoutesFrom()을 사용하여 라우트 파일을 로드합니다. 애플리케이션의 라우트 캐시가 활성화된 경우 자동으로 건너뜁니다.

public function boot(): void
{
    $this->loadRoutesFrom(__DIR__.'/../routes/web.php');
}

라우트 파일에서는 패키지의 컨트롤러를 지정합니다.

// routes/web.php
use Acme\Courier\Http\Controllers\TrackingController;
use Illuminate\Support\Facades\Route;

Route::prefix('courier')->group(function () {
    Route::get('/track/{id}', [TrackingController::class, 'show'])
        ->name('courier.track');
});

미들웨어 명시, URI와 라우트 이름의 충돌 방지, 설정 변경을 캐시에 반영하는 절차는 패키지의 라우트 등록과 캐시에서 설명합니다.

마이그레이션 배포

publishesMigrations()를 사용하면 마이그레이션 파일을 배포 대상으로 등록할 수 있습니다. Laravel 13의 기본 구성에서는 database.migrations.update_date_on_publish가 활성화되어 있으므로, 배포 시 파일 이름의 타임스탬프가 업데이트됩니다. 설정이 비활성화되어 있거나 존재하지 않으면 이 업데이트는 수행되지 않습니다.

public function boot(): void
{
    $this->publishesMigrations([
        __DIR__.'/../database/migrations' => database_path('migrations'),
    ]);
}

배포와 직접 로드의 구분, 타임스탬프 변경 조건, 재배포의 위험, 기존 사용자에 대한 스키마 변경은 패키지 마이그레이션의 배포와 업데이트에서 설명합니다.

뷰 배포

loadViewsFrom() — 뷰 등록하기

loadViewsFrom()으로 뷰 디렉터리를 등록합니다. 두 번째 인수의 네임스페이스를 사용해 package::view 형식으로 뷰를 참조합니다.

public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');
}

등록 후 뷰는 패키지 네임스페이스로 참조합니다.

Route::get('/dashboard', function () {
    return view('courier::dashboard');
});

Laravel은 뷰를 두 곳에서 찾습니다. 먼저 애플리케이션의 resources/views/vendor/courier 디렉터리를 확인하고, 없으면 패키지의 뷰 디렉터리를 사용합니다. 이를 통해 사용자가 뷰를 커스터마이즈할 수 있습니다. 구현상의 검색 순서와 파일 단위 폴백, 배포된 템플릿에 변경을 전달하는 방법, Blade 캐시와의 차이는 패키지 뷰의 덮어쓰기와 업데이트에서 설명합니다.

뷰 배포하기

public function boot(): void
{
    $this->loadViewsFrom(__DIR__.'/../resources/views', 'courier');

    $this->publishes([
        __DIR__.'/../resources/views' => resource_path('views/vendor/courier'),
    ], 'courier-views');
}

Blade 컴포넌트 등록

컴포넌트를 패키지에 포함하는 경우, boot 메서드에서 등록합니다.

use Illuminate\Support\Facades\Blade;
use Acme\Courier\View\Components\AlertComponent;

public function boot(): void
{
    Blade::component('courier-alert', AlertComponent::class);
}

컴포넌트 네임스페이스를 사용하여 일괄 등록할 수도 있습니다.

use Illuminate\Support\Facades\Blade;

public function boot(): void
{
    Blade::componentNamespace('Acme\\Courier\\View\\Components', 'courier');
}

{{-- 개별 등록의 경우 --}}
<x-courier-alert />

{{-- 네임스페이스 등록의 경우 --}}
<x-courier::alert />

공개 에셋 배포

패키지의 JavaScript·CSS·이미지를 배포하려면 publishes()로 public_path('vendor/courier') 등으로의 복사를 등록합니다. 패키지를 업데이트해도 이미 공개된 파일은 자동으로 바뀌지 않습니다. 태그와 프로바이더에 의한 대상 범위 지정, --force와 --existing의 차이, 삭제된 파일의 처리, laravel-assets를 통한 업데이트는 패키지의 공개 에셋과 업데이트에서 해설합니다.

번역 파일 배포

loadTranslationsFrom()으로 번역 파일을 등록합니다. 번역은 package::file.key 형식으로 참조합니다.

public function boot(): void
{
    $this->loadTranslationsFrom(__DIR__.'/../lang', 'courier');

    $this->publishes([
        __DIR__.'/../lang' => $this->app->langPath('vendor/courier'),
    ]);
}

// 번역 사용
echo trans('courier::messages.welcome');

JSON 번역 파일을 사용하는 경우 loadJsonTranslationsFrom()을 사용합니다.

public function boot(): void
{
    $this->loadJsonTranslationsFrom(__DIR__.'/../lang');
}

PHP 번역의 부분 덮어쓰기, JSON 번역의 로드 순서와 덮어쓰기 위치, 번역 키의 호환성과 공개된 파일의 업데이트는 패키지 번역의 덮어쓰기와 업데이트에서 해설합니다.

명령어 등록

패키지의 Artisan 명령어는 commands() 메서드로 등록합니다. 콘솔 환경에서만 등록하는 것이 일반적입니다.

use Acme\Courier\Console\Commands\InstallCommand;
use Acme\Courier\Console\Commands\SyncCommand;

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->commands([
            InstallCommand::class,
            SyncCommand::class,
        ]);
    }
}

optimize 명령어와 통합

패키지가 자체 캐시를 갖는 경우, optimizes() 메서드로 php artisan optimize와 php artisan optimize:clear에 통합할 수 있습니다.

public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->optimizes(
            optimize: 'courier:cache',
            clear: 'courier:clear-cache',
        );
    }
}

명령어 클래스 등록과 최적화 태스크 등록은 별개의 처리입니다. 등록 키 충돌, --except를 통한 제외, 표준 태스크와의 실행 순서, 실패 시 종료 코드는 패키지 캐시와 optimize 통합에서 해설합니다.

`about` 명령어에 정보 추가

php artisan about의 출력에 패키지 정보를 추가하려면 AboutCommand::add()를 사용합니다.

use Illuminate\Foundation\Console\AboutCommand;

public function boot(): void
{
    AboutCommand::add('Courier Package', fn () => ['Version' => '1.0.0']);
}

데이터를 평가하는 시점, --only와 JSON 출력, 비밀 정보를 포함하지 않는 설계, 테스트에서의 등록 상태는 패키지 진단 정보를 about에 추가하기에서 설명합니다.

파사드 생성

파사드를 사용하면 서비스 컨테이너의 바인딩을 정적 메서드처럼 호출할 수 있습니다.

서비스 클래스 만들기

<?php

namespace Acme\Courier;

class CourierManager
{
    public function __construct(
        protected array $config,
    ) {}

    public function send(string $to, string $message): bool
    {
        // 메시지 전송 처리
        return true;
    }

    public function track(string $id): array
    {
        // 추적 정보 조회 처리
        return ['status' => 'delivered'];
    }
}

파사드 클래스 만들기

Illuminate\Support\Facades\Facade를 상속하고, getFacadeAccessor()에서 서비스 컨테이너의 바인딩 키를 반환합니다.

<?php

namespace Acme\Courier\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @method static bool send(string $to, string $message)
 * @method static array track(string $id)
 *
 * @see \Acme\Courier\CourierManager
 */
class Courier extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return \Acme\Courier\CourierManager::class;
    }
}

서비스 프로바이더에서 바인딩하기

public function register(): void
{
    $this->app->singleton(\Acme\Courier\CourierManager::class, function ($app) {
        return new \Acme\Courier\CourierManager($app['config']['courier']);
    });
}

composer.json에 등록하기

"extra": {
    "laravel": {
        "providers": [
            "Acme\\Courier\\CourierServiceProvider"
        ],
        "aliases": {
            "Courier": "Acme\\Courier\\Facades\\Courier"
        }
    }
}

파사드 메서드에 PHPDoc의 @method 애노테이션을 붙이면 IDE 자동완성이 활성화됩니다.

// 파사드를 통해 서비스 호출
use Acme\Courier\Facades\Courier;

Courier::send('[email protected]', '패키지가 도착했습니다');
$status = Courier::track('ABC-123');

DeferrableProvider — 지연 로딩 구현

서비스 컨테이너에 바인딩만 수행하는 프로바이더는 DeferrableProvider 인터페이스를 구현함으로써 지연 로딩을 실현할 수 있습니다. 서비스가 실제로 필요해질 때까지 프로바이더가 로드되지 않기 때문에 애플리케이션 성능이 향상됩니다.

<?php

namespace Acme\Courier;

use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class CourierServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->app->singleton(CourierManager::class, function ($app) {
            return new CourierManager($app['config']['courier']);
        });
    }

    /**
     * 이 프로바이더가 제공하는 서비스 목록을 반환한다
     *
     * @return array<int, string>
     */
    public function provides(): array
    {
        return [CourierManager::class];
    }
}

Laravel은 지연 프로바이더가 제공하는 서비스 목록을 컴파일하여 저장합니다. provides()에 나열된 서비스가 해결될 때만 프로바이더가 로드됩니다.

리소스 등록(뷰, 라우트, 이벤트 리스너 등)이 필요한 프로바이더에는 DeferrableProvider를 사용하지 마세요. 지연 로딩되면 해당 리소스가 등록되지 않은 채로 남게 됩니다.

패키지 테스트

패키지를 단독으로 테스트할 때는 Orchestra Testbench를 사용합니다. 일반 Laravel 애플리케이션 안에 있는 것처럼 패키지 테스트를 작성할 수 있습니다.

composer require --dev orchestra/testbench

테스트 케이스에서 getPackageProviders()를 오버라이드하여 패키지의 서비스 프로바이더를 등록합니다.

<?php

namespace Acme\Courier\Tests;

use Acme\Courier\CourierServiceProvider;
use Orchestra\Testbench\TestCase as BaseTestCase;

class TestCase extends BaseTestCase
{
    /**
     * 패키지의 서비스 프로바이더를 등록한다
     */
    protected function getPackageProviders($app): array
    {
        return [
            CourierServiceProvider::class,
        ];
    }

    /**
     * 패키지의 파사드 별칭을 등록한다
     */
    protected function getPackageAliases($app): array
    {
        return [
            'Courier' => \Acme\Courier\Facades\Courier::class,
        ];
    }

    /**
     * 테스트용 환경 설정
     */
    protected function defineEnvironment($app): void
    {
        $app['config']->set('courier.api_key', 'test-key');
    }
}

<?php

namespace Acme\Courier\Tests\Feature;

use Acme\Courier\Facades\Courier;
use Acme\Courier\Tests\TestCase;

class CourierTest extends TestCase
{
    public function test_can_send_message(): void
    {
        $result = Courier::send('[email protected]', '테스트 메시지');

        $this->assertTrue($result);
    }
}

Composer에 배포

패키지를 Packagist에 배포하기 위한 모범 사례입니다. composer.json의 기본 설정

{
    "name": "acme/courier",
    "description": "A Laravel courier package",
    "type": "library",
    "license": "MIT",
    "require": {
        "php": "^8.2",
        "illuminate/support": "^11.0||^12.0||^13.0"
    },
    "require-dev": {
        "orchestra/testbench": "^9.0||^10.0",
        "phpunit/phpunit": "^11.0"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Courier\\": "src/"
        }
    },
    "autoload-dev": {
        "psr-4": {
            "Acme\\Courier\\Tests\\": "tests/"
        }
    },
    "extra": {
        "laravel": {
            "providers": [
                "Acme\\Courier\\CourierServiceProvider"
            ],
            "aliases": {
                "Courier": "Acme\\Courier\\Facades\\Courier"
            }
        }
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

illuminate/support에 의존함으로써, illuminate/framework 전체가 아닌 Laravel의 필요한 컴포넌트만 의존성에 포함할 수 있습니다. 패키지의 의존성 트리를 작게 유지합시다.

디렉터리 구조 예시

acme/courier/
├── config/
│   └── courier.php
├── database/
│   └── migrations/
│       └── 2024_01_01_000000_create_courier_logs_table.php
├── lang/
│   └── ko/
│       └── messages.php
├── resources/
│   └── views/
│       └── dashboard.blade.php
├── routes/
│   └── web.php
├── src/
│   ├── Console/
│   │   └── Commands/
│   │       └── InstallCommand.php
│   ├── Facades/
│   │   └── Courier.php
│   ├── Http/
│   │   └── Controllers/
│   │       └── TrackingController.php
│   ├── CourierManager.php
│   └── CourierServiceProvider.php
├── tests/
│   ├── Feature/
│   └── TestCase.php
├── composer.json
└── README.md

서비스 프로바이더

서비스 프로바이더의 register와 boot 메서드, 지연 프로바이더의 상세 내용을 확인합니다.

버전 호환성 관리

Laravel과 PHP 메이저 버전 업그레이드에 대응하는 전략과 GitHub Actions 테스트 매트릭스 설정을 설명합니다.

AI 개발

디자인 패턴

패키지 개발

애플리케이션 구조

Laravel 13 신기능

Eloquent 심화

유효성 검증 확장

인증 확장

보안

큐

테스트

실시간

패키지란

패키지 자동 감지

자동 감지 비활성화

서비스 프로바이더의 역할

설정 파일 배포

publishes() — 파일 공개하기

mergeConfigFrom() — 기본값과 병합

태그로 배포 그룹 분리하기

라우트 등록

마이그레이션 배포

뷰 배포

loadViewsFrom() — 뷰 등록하기

뷰 배포하기

Blade 컴포넌트 등록

공개 에셋 배포

번역 파일 배포

명령어 등록

optimize 명령어와 통합

`about` 명령어에 정보 추가

파사드 생성

DeferrableProvider — 지연 로딩 구현

패키지 테스트

Composer에 배포

관련 페이지

서비스 프로바이더

버전 호환성 관리

​패키지란

​패키지 자동 감지

​자동 감지 비활성화

​서비스 프로바이더의 역할

​설정 파일 배포

​publishes() — 파일 공개하기

​mergeConfigFrom() — 기본값과 병합

​태그로 배포 그룹 분리하기

​라우트 등록

​마이그레이션 배포

​뷰 배포

​loadViewsFrom() — 뷰 등록하기

​뷰 배포하기

​Blade 컴포넌트 등록

​공개 에셋 배포

​번역 파일 배포

​명령어 등록

​optimize 명령어와 통합

​about 명령어에 정보 추가

​파사드 생성

​DeferrableProvider — 지연 로딩 구현

​패키지 테스트

​Composer에 배포

​관련 페이지

서비스 프로바이더

버전 호환성 관리

패키지란

패키지 자동 감지

자동 감지 비활성화

서비스 프로바이더의 역할

설정 파일 배포

publishes() — 파일 공개하기

mergeConfigFrom() — 기본값과 병합

태그로 배포 그룹 분리하기

라우트 등록

마이그레이션 배포

뷰 배포

loadViewsFrom() — 뷰 등록하기

뷰 배포하기

Blade 컴포넌트 등록

공개 에셋 배포

번역 파일 배포

명령어 등록

optimize 명령어와 통합

`about` 명령어에 정보 추가

파사드 생성

DeferrableProvider — 지연 로딩 구현

패키지 테스트

Composer에 배포

관련 페이지