Route Management

Create routes with full scaffolding and view your application's routing configuration. Generate routes with controllers and views in one command, or list all registered routes for debugging.

make:route - Create Route with Controller & View

Generate a complete route setup including Twig template, controller method, and route entry in one command.

php craftsman make:route {uri} [options]

Arguments

Options

Examples

Basic Route Creation

# Create /about route with HomeController
php craftsman make:route /about

# Creates:
# - pages/about.twig (view template)
# - HomeController@about method
# - Route entry in routes/web.php

Custom Controller

# Create route with specific controller
php craftsman make:route /blog/post --controller BlogController

# Creates:
# - pages/blog/post.twig
# - BlogController@blogPost method
# - Route with name: blog.post

Closure-Based Route

# Create route without controller
php craftsman make:route /contact --no-controller

# Creates:
# - pages/contact.twig
# - Closure-based route in routes/web.php

POST Route

# Create POST route
php craftsman make:route /form-submit --method POST

# For handling form submissions

Named Route with Layout

# Create route with custom name and layout
php craftsman make:route /dashboard --name admin.dashboard --layout app

# Custom route name for url() helper
# Extends pages/layouts/app.twig

What Gets Created

1. Twig Template

Creates a view template in pages/ directory (or custom VIEWS_PATH):

{% extends 'layouts/app.twig' %}

{% block title %}About{% endblock %}

{% block content %}
    

        
About
        
Welcome to the about page.
    
{% endblock %}

2. Controller Method

Adds method to existing controller or creates new one:

<?php

namespace App\Controllers;

use ZephyrPHP\Core\Controllers\Controller;

class HomeController extends Controller
{
    public function about(): string
    {
        return $this->render('about');
    }
}

3. Route Entry

Adds route to routes/web.php:

<?php

use App\Controllers\HomeController;

Route::get('/about', [HomeController::class, 'about'])->name('about');

URI Conversion Logic

The command automatically converts URIs to proper naming conventions:

Layout Options

The command auto-discovers available layouts in pages/layouts/:

# Interactive selection
php craftsman make:route /page

Select a layout to extend:
  [0] app     (pages/layouts/app.twig)
  [1] base    (pages/layouts/base.twig)
  [2] none    (Create standalone page)

# Or specify directly
php craftsman make:route /page --layout app
php craftsman make:route /page --layout none

Routing Styles

The command auto-detects your routing style:

Static Style (Route::)

Route::get('/about', [HomeController::class, 'about'])->name('about');

Instance Style ($router->)

$router->get('/about', [HomeController::class, 'about'], 'about');

route:list - List All Routes

Display a table of all registered routes in your application.

php craftsman route:list

Example Output

$ php craftsman route:list

┌────────┬─────────────────────┬──────────────────────────┐
│ Method │ URI                 │ Action                   │
├────────┼─────────────────────┼──────────────────────────┤
│ GET    │ /                   │ HomeController@index     │
│ GET    │ /about              │ HomeController@about     │
│ GET    │ /posts              │ PostController@index     │
│ POST   │ /posts              │ PostController@store     │
│ GET    │ /posts/{id}         │ PostController@show      │
│ PUT    │ /posts/{id}         │ PostController@update    │
│ DELETE │ /posts/{id}         │ PostController@destroy   │
│ GET    │ /contact            │ Closure                  │
└────────┴─────────────────────┴──────────────────────────┘

Output Columns

How It Works

• Parses routes/web.php file
• Supports both static (Route::) and instance ($router->) routing styles
• Extracts route information using regex pattern matching
• Displays routes in a clean table format

Common Use Cases

Quick Route Scaffolding

# Rapidly build out pages
php craftsman make:route /about
php craftsman make:route /services
php craftsman make:route /contact

# Each creates complete MVC structure automatically

Debugging Routes

# Check if your route is registered
php craftsman route:list

# Verify the URI pattern matches
# Check controller name is correct
# Look for typos in route definitions

Creating API Routes

# POST endpoint
php craftsman make:route /api/posts --method POST --controller ApiPostController

# PUT endpoint
php craftsman make:route /api/posts/{id} --method PUT --controller ApiPostController

# DELETE endpoint
php craftsman make:route /api/posts/{id} --method DELETE --controller ApiPostController

Route Documentation

# Generate route list for team documentation
php craftsman route:list > docs/routes.txt

# Share with frontend developers
# Document API endpoints
# Onboard new team members

Troubleshooting

Route Not Working (404)

# 1. Check route is registered
php craftsman route:list

# 2. Verify URI matches exactly (check trailing slashes)
# 3. Check HTTP method matches
# 4. Clear route cache if caching is enabled
php craftsman cache:clear

Controller Not Found

# Verify controller exists
ls app/Controllers/YourController.php

# Check namespace in controller matches app namespace
# Verify autoloader is working
composer dump-autoload

Template Not Rendering

# Check template file exists
ls pages/your-template.twig

# Verify VIEWS_PATH in .env
cat .env | grep VIEWS_PATH

# Check for Twig syntax errors in template

Duplicate Route Definitions

# Run route:list to see all routes
php craftsman route:list

# Look for duplicate URIs
# Remove or consolidate duplicate routes in routes/web.php

Best Practices

Route Organization

• Use make:route for simple pages (about, contact, etc.)
• Use make:crud for resourceful routes (posts, products, etc.)
• Keep related routes grouped together in routes/web.php
• Use route groups for shared middleware and prefixes

Naming Conventions

# Use dot notation for route names
Route::get('/posts', [PostController::class, 'index'])->name('posts.index');
Route::get('/posts/{id}', [PostController::class, 'show'])->name('posts.show');

# Name all routes for easier URL generation
View Post

RESTful Routes

Follow REST conventions for resource routes:

Next Steps

Continue exploring Craftsman CLI features:

• Generate complete CRUD with Code Generation Commands
• Set up database with Database Commands
• Manage application with Module Management
• Return to Craftsman CLI Overview