Download the PHP package geckods/laravel-routes without Composer

Laravel Routes

Overview

Laravel Routes is a lightweight Laravel package that helps you organize application routes by feature or functionality instead of keeping them all in a single centralized file. This approach promotes better code organization, maintainability, and scalability in larger Laravel projects.

Why Use Laravel Routes?

• Feature-Based Organization: Group related routes by feature or module
• Modular Structure: Each feature can have its own route definitions
• Easy Configuration: Simple configuration to define where routes are located
• Well Tested: Comprehensive test suite with 27 passing tests
• Production Ready: Stable and reliable for production applications

Requirements

• PHP 8.2 or higher
• Laravel 10.0 or higher
• Composer

Installation

Install the package via Composer:

The package will be automatically registered through Laravel's auto-discovery feature. No manual service provider registration is needed.

Configuration

Publish Config File

Publish the configuration file to your application:

This creates config/routes.php with the following options:

Auto-Publishing on Update

To automatically publish the config on each Composer update, add this to your composer.json:

Usage

Basic Setup

In your route files (e.g., routes/api.php or routes/web.php), initialize the route controller:

Creating Route Classes

Create route classes by extending AbstractRouteController:

Another example with different middleware:

How Route Discovery Works

The package uses glob patterns to discover route files. Here's how it works:

1. Uses the path config to find PHP files
2. Converts file paths to class names using prefix_namespace config
3. Requires the file and checks if the class exists
4. Verifies the class extends AbstractRouteController
5. Instantiates the class and calls handle()

Example Mapping

With default config:

• Config path: app_path('Http/**/*.php')
• Config prefix_namespace: App\\

A file at app/Http/Routes/UserRoutes.php containing class App\Http\Routes\UserRoutes will be discovered.

Configuration Options Explained

path

Defines where the package searches for route classes. Supports standard glob patterns.

The glob patterns work as follows:

• * matches any characters except path separators
• ** matches any characters including path separators (recursive)
• ? matches any single character

Examples:

prefix_namespace

The namespace prefix that will be prepended to the discovered class names. This must match your actual class namespaces.

When the package discovers a file, it:

1. Gets the relative path from app directory
2. Replaces slashes with backslashes
3. Removes the .php extension
4. Prepends the prefix_namespace

Examples:

other_routes

Manually register route classes that either:

• Are not located in the path specified above
• Should not be auto-discovered for some reason

Usage:

Project Structure Example

A typical project structure might look like:

Then in routes/api.php:

With config:

The package will discover and execute:

• App\Http\Routes\PostRoutes
• App\Http\Routes\UserRoutes
• App\Http\Routes\CommentRoutes
• App\Features\Notifications\Routes\NotificationRoutes
• App\Features\Payments\Routes\PaymentRoutes

Advanced Usage

Conditional Route Registration

Register routes conditionally based on environment or feature flags:

Nested Route Groups

Organize complex route hierarchies:

Testing

The package includes a comprehensive test suite with 27 tests covering:

• Route discovery and execution
• Configuration validation
• Service provider integration
• Edge cases and error handling

Running Tests

For detailed testing documentation, see TESTING.md.

Documentation

• TESTS.md - Comprehensive test suite documentation
• TESTING.md - Test execution guide with CI/CD examples
• LICENSE - MIT License

Migration from Other Packages

If you are migrating from centralized route files:

1. Create route classes in your desired structure
2. Extend AbstractRouteController with your route definitions
3. Update route files to use RouteController::handle()
4. Test thoroughly to ensure all routes work as expected

Performance Considerations

• Route discovery uses glob patterns and class introspection
• Discovered routes are processed once per request
• For large projects, consider grouping routes logically
• Use other_routes config for routes outside the standard path

Troubleshooting

Routes Not Being Discovered

1. Check that your route class extends AbstractRouteController
2. Verify the path config matches your route class locations
3. Ensure the prefix_namespace config is correct
4. Run php artisan config:clear to clear cached config
5. Verify the class namespace matches what the discovery algorithm produces

Namespace Errors

1. Verify class namespace matches prefix_namespace config
2. Check that files are in the location specified by path config
3. Ensure autoloader is updated: composer dump-autoload

Routes Not Executing

1. Confirm RouteController::handle() is called in your route files
2. Check middleware order and authentication requirements
3. Verify route controller has a valid handle() method

Contributing

Contributions are welcome! Please feel free to submit a Pull Request to the GitHub repository.

Development Setup

Support

For issues, questions, or suggestions, please open an issue on the GitHub repository.

License

This package is open source software licensed under the MIT license.

About

Created and maintained by Gecko Digital Solutions.

Last Updated: November 2025 Version: 1.0.0