Adr Bundle Laravel Package

Getting Started

The v0.0.2 release adds directory-based route loading for actions, which is the first feature worth evaluating. Start by requiring the package and publishing its config:

composer require <vendor>/<package>
php artisan vendor:publish --tag=<package>-config

Look first at the published config file—specifically the directory/path options and any namespace or middleware defaults. Then create a small Actions directory under app/ with one invokable action class. Register that directory in config and confirm the route appears with php artisan route:list.

A first use case: replace a handful of manual Route::get() calls with action classes that each expose their route definition (attribute, method, or convention). The package scans the directory, instantiates or reflects on each action, and registers routes. This is most useful for CRUD-style or domain-grouped actions where a directory maps cleanly to a route group.

Because this is v0.0.2, treat the API as unstable and pin the exact version in composer.json.

Implementation Patterns

Directory-per-domain grouping. Point the package at app/Actions/Admin, app/Actions/Api, etc., and apply middleware/prefixes per directory in config. This keeps route registration close to the actions themselves.

Convention-based action discovery. Name action classes consistently (e.g., GetUsersAction, StoreUserAction) and let the package infer HTTP verbs and URIs from class names or a route() method. Keep the convention documented in your team’s README so new actions are predictable.

Attribute-driven routes. If the package supports PHP attributes on action classes, prefer them over a central route file. This makes each action self-contained and easy to move between directories without touching a separate route map.

Mixing with manual routes. Load directory routes inside the same route group as existing manual routes, but keep the directory scan last so explicit routes take precedence. Use Route::middleware() around the directory loader if the package exposes a registrar.

Module/package integration. For modular Laravel apps, register each module’s action directory from its service provider. This lets modules own their routes without editing routes/web.php.

Testing workflow. Use php artisan route:list after adding or moving an action. In tests, assert route registration with Route::getRoutes() or feature tests that hit the discovered URI. Clear route cache before running the suite if you cache routes in CI.

Gotchas and Tips

• Route caching. Directory scanning is a runtime filesystem operation. Ensure the package supports route:cache; if not, discovered routes may disappear in production. Always run php artisan route:clear after changing action directories.
• Deterministic ordering. Directory iteration order can vary by filesystem. If two actions resolve to the same URI or name, you may get inconsistent overrides. Namespace route names per directory and avoid duplicate URIs.
• Autoloading requirements. Action classes must be PSR-4 autoloadable and discoverable by Composer. Run composer dump-autoload after adding a new namespace or moving directories.
• Class reflection cost. Scanning many files on every request adds overhead. Prefer route caching in production and keep action directories shallow.
• Middleware inheritance. Confirm whether directory-level middleware merges with or replaces group middleware. Test with route:list -v to see the effective middleware stack.
• Config quirks. Early versions often expect absolute paths or a specific namespace format. If routes do not register, log the resolved directory path and verify it matches the filesystem.
• Extension points. Look for a custom route resolver or attribute reader in the package’s service provider. If none exists, wrap the directory loader in your own registrar rather than forking.
• Version pinning. v0.0.2 is pre-1.0; the directory-loading API may change. Pin the version and review changelogs before upgrading.
• Debugging. Use php artisan route:list, check the package’s config cache, and verify that action classes are not abstract or excluded by filename patterns.