Hacktoberfest 2026：メンテナが10月に向けて印を付けた、オープンで初心者向けの issue。 Hacktoberfest の issue を見る

Support nested module-relative controller resolution in routes while preserving explicit controller class references

オープン
  • 何か問題がありますか？
#546 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
64/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
静か
技術スタック
php
領域
api, backend

調査の方向性

まず src/Router/RouteBuilder.php と src/Router/RouteDispatcher.php を通じてコントローラー解決を追跡し、次に src/Router/Route.php、リクエストのルートメタデータ、およびルート一覧表示のパスを調査します。dispatch、ルート一覧表示、メタデータにおいて、フラットなコントローラー文字列、ネストされたモジュール相対のコントローラー文字列、明示的に完全修飾されたコントローラー文字列をそれぞれ検証し、各ケースのテストを追加して、既存のフラットな動作が引き続き維持されることを確認します。

索引モデルが issue の本文から書いたものです。

説明

routing

Summary

Enhance Quantum route controller resolution so route definitions can reference controllers in nested subnamespaces/folders within the current module, while preserving existing support for explicit fully qualified controller class references.

This should allow controller route strings such as:

  • PostController
  • V1\PostController
  • Admin\UserController

to resolve relative to the current module’s Controllers namespace, without breaking the ability to use explicit FQCN controller class strings where intentionally supported.

Why

Current route controller resolution in Quantum is too limited for deeper controller organization.

Today, flat shorthand works for controllers that live directly under:

  • {Module}\Controllers\...

However, the current resolution logic uses a simple backslash check to decide whether a handler should be prefixed with the module controller namespace.

That means a nested relative controller path such as:

  • V1\PostController

is currently treated the same way as an explicitly qualified controller class string, even though those are different use cases.

As a result, Quantum lacks a clean way to organize controllers inside nested subnamespaces within the current module.

Goal

Allow nested controller organization inside a module while preserving both:

  • current flat controller shorthand
  • intentional explicit FQCN controller class references

Proposed Direction

Update route controller resolution so it can distinguish between:

Module-relative controller shorthand

Examples:

  • PostController
  • V1\PostController
  • Admin\UserController

These should resolve relative to the current module’s Controllers namespace.

Examples:

  • PostController
    resolves to:

    • {ModuleBaseNamespace}\{CurrentModule}\Controllers\PostController

  • V1\PostController
    resolves to:

    • {ModuleBaseNamespace}\{CurrentModule}\Controllers\V1\PostController

  • Admin\UserController
    resolves to:

    • {ModuleBaseNamespace}\{CurrentModule}\Controllers\Admin\UserController
Explicit FQCN controller references

If the route handler is intentionally written as an explicit fully qualified controller class string, that behavior should remain supported.

Examples:

  • \Modules\Api\Controllers\V1\PostController
  • Modules\Api\Controllers\V1\PostController

The resolution logic should therefore no longer use “contains backslash” as the only distinction between shorthand and explicit controller references.

Instead, it should distinguish properly between:

  • nested module-relative controller paths
  • explicit FQCN controller class references

Why this matters

This is a prerequisite for cleaner future work such as:

  • API major versioning within a single module
  • better controller organization in larger modules
  • route-set mounting with version-specific controller subnamespaces

without forcing:

  • flat controller folders
  • duplicated route definitions
  • awkward controller naming workarounds

Acceptance Criteria

  • flat controller shorthand continues to work
  • nested controller shorthand such as V1\PostController and Admin\UserController resolves correctly within the current module
  • explicit FQCN controller class references remain supported if intentionally provided
  • route listing, dispatch, and request route metadata continue to work with nested resolved controllers
  • controller resolution no longer relies solely on “contains backslash” to decide whether a handler is relative or explicit
  • tests verify flat controller shorthand resolution such as PostController
  • tests verify nested module-relative controller shorthand such as V1\PostController
  • tests verify explicit FQCN controller class references continue to resolve correctly

Notes

Relevant code:

  • src/Router/RouteBuilder.php
  • src/Router/RouteDispatcher.php
  • src/Router/Route.php
  • src/Http/Traits/Request/Route.php
  • src/Console/Commands/RouteListCommand.php

This ticket should be treated as a routing foundation improvement and a prerequisite for cleaner API versioning support inside a single module.

主要言語
PHP
スター
36
フォーク
22
30日以内にマージされた PR はありません

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

quantum-php/framework のほかの issue

quantum-php/framework の issue をすべて見る

似ている issue

PHP の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。