라우팅

TubePress는 정적 Router 클래스를 중심으로 구축된 작고 빠른 라우터를 사용합니다. 컨트롤러는 ::routes() 메서드에 라우트를 등록하며, public/index.php가 요청을 디스패치하기 전에 해당 메서드를 호출합니다. 이 페이지에서는 플러그인에서 라우트를 추가하거나 요청이 어떻게 매칭되는지 이해하는 데 필요한 모든 내용을 다룹니다.

라우트 등록

라우트는 Router::get() 또는 Router::post()로 등록합니다. 핸들러는 클로저나 [Class, 'method'] 쌍과 같이 callable이면 무엇이든 가능합니다.

// Closure handler
Router::get('/promo', function () {
    ThemeRenderer::render('promo', ['deal' => 'Summer']);
});

// Controller handler
Router::post('/promo/claim', [PromoController::class, 'claim']);

관례적으로 각 컨트롤러는 모든 라우트를 등록하는 정적 routes() 메서드를 공개하며, 해당 메서드는 부팅 시 한 번 호출됩니다:

class PromoController
{
    public static function routes(): void
    {
        Router::get('/promo', [self::class, 'show']);
        Router::post('/promo/claim', [self::class, 'claim']);
    }
}

라우트 매개변수

경로에 {name} 플레이스홀더를 사용하며, 각각은 단일 URL 세그먼트(/를 제외한 모든 것)와 매칭됩니다. 값은 Router::param()으로 읽습니다.

Router::get('/promo/{code}', function () {
    $code = Router::param('code');          // required
    $ref  = Router::param('ref', 'direct'); // with a default
    // …
});

내부적으로 /promo/{code}와 같은 패턴은 정규식 (?P<code>[^/]+)으로 컴파일되므로, 매개변수는 슬래시를 넘어 매칭되지 않습니다. 정확한 라우트가 먼저 매칭되고, 그다음 등록 순서에 따라 매개변수화된 라우트가 매칭됩니다.

응답 전송

라우트 순서 및 캐치올

정적 페이지는 /{slug} 캐치올로 제공되므로, 페이지 컨트롤러는 모든 프론트엔드, 관리자 및 API 라우트 이후에 public/index.php에서 마지막으로 등록됩니다. 부팅 중 플러그인에서 라우트를 등록하면 캐치올 이전에 추가되어 먼저 매칭됩니다.

CSRF 보호

상태를 변경하는 모든 POST 요청은 CSRF 보호를 받아야 합니다. 라우터는 다음 헬퍼를 제공합니다:

// In your form template
<?= Router::csrfField() ?>          // hidden input

// In your POST handler
if (!Router::verifyCsrf()) {
    Router::json(['error' => 'Invalid token'], 403);
}

verifyCsrf()는 csrf_token POST 필드 또는 X-CSRF-Token 헤더의 토큰을 수락하고, hash_equals()로 비교합니다.

현지화 및 타입별 URL

다국어 사이트의 경우 라우터는 언어 접두사(예: /fr/…)를 투명하게 처리하고 알려진 라우트 슬러그를 번역하므로, /categorie/brunette는 category 라우트로 해석됩니다. 관리자 및 설치 라우트는 면제됩니다 — 사용자 정의 경로를 접두사 처리에서 제외하려면 Router::addNoPrefixPath()로 경로를 등록하세요. 전체 동작은 언어 및 번역을 참조하세요. 헬퍼 Router::langPrefix(), Router::typePrefix() 및 Router::url()을 사용하면 모든 로케일에서 올바른 링크를 생성할 수 있습니다.

다음 단계