README

A comprehensive route visualization package for Laravel applications that provides an interactive web interface to explore, analyze, and export your application's routing structure with advanced validation and multiple visualization options.

Features

Interactive Route Explorer: Web-based dashboard with advanced search and filtering
Network Graph Visualization: Interactive network graphs using Vis.js for route relationships
Tree View: Hierarchical visualization of route structure organized by prefixes
Advanced Filtering: Filter by HTTP methods, middleware, middleware groups, controllers, domains, namespaces, and more
Route Validation: Automatic detection of duplicate routes, missing controllers, and missing methods
Export Capabilities: Export filtered route data to HTML, JSON, or SVG formats
Performance Optimized: Built-in caching, pagination, and lazy loading for large route sets
Security Aware: Hide sensitive routes in production environments
Customizable: Configurable visualization options, and multiple templates
Copy to Clipboard: One-click copying of route URIs and controller actions
Laravel Telescope Integration: Direct links to route performance data when Telescope is installed

Requirements

PHP ^8.1
Laravel ^10.0|^11.0|^12.0

Installation

Install the package via Composer:

composer require onamfc/laravel-route-visualizer

The package will automatically register itself via Laravel's auto-discovery feature.

Quick Installation

Use the install command to publish all necessary files:

php artisan route-visualizer:install

This command will publish the configuration file, views, and assets in one step.

Manual Installation

If you prefer to publish files individually:

Publish Configuration

php artisan vendor:publish --tag=route-visualizer-config

Publish Views (Optional)

If you want to customize the views:

php artisan vendor:publish --tag=route-visualizer-views

Publish Assets (Optional)

If you want to serve assets locally:

php artisan vendor:publish --tag=route-visualizer-assets

Configuration

The configuration file config/route-visualizer.php allows you to customize:

return [
    // Enable/disable the visualizer (auto-disabled in production)
    'enabled' => env('ROUTE_VISUALIZER_ENABLED', app()->environment(['local', 'testing'])),
    
    // Route prefix for the visualizer dashboard
    'route_prefix' => 'route-visualizer',
    
    // Middleware to apply to visualizer routes
    'middleware' => ['web'],
    
    // Cache settings for performance
    'cache' => [
        'enabled' => true,
        'ttl' => 3600, // 1 hour
        'key' => 'route_visualizer_data',
    ],
    
    // Visualization library and options
    'visualization' => [
        'layout' => 'hierarchical', // hierarchical, network
        'pagination' => [
            'enabled' => true,
            'per_page' => 50,
        ],
    ],
    
    // Export settings
    'export' => [
        'path' => storage_path('app/route-maps'),
        'formats' => ['html', 'json', 'svg'],
        'templates' => ['default', 'minimal', 'detailed'],
    ],
    
    // Security settings
    'security' => [
        'hide_sensitive_routes' => true,
        'sensitive_patterns' => [
            'admin/*',
            'api/admin/*',
            '*/password/*',
            'telescope/*',
            'horizon/*',
        ],
    ],
    
    // Validation settings
    'validation' => [
        'check_duplicates' => true,
        'check_missing_controllers' => true,
        'check_missing_methods' => true,
    ],
    
    // Integration settings
    'integrations' => [
        'telescope' => [
            'enabled' => class_exists(\Laravel\Telescope\TelescopeServiceProvider::class),
            'base_url' => '/telescope',
        ],
    ],
];

Usage

Web Interface

Once installed, visit the route visualizer dashboard:

http://your-app.com/route-visualizer

The dashboard provides:

Overview Statistics: Total routes, controllers, middleware, domains, namespaces, and validation issues
Advanced Search & Filtering: Real-time search with filters for methods, middleware, domains, namespaces, and more
Multiple View Modes:
- List View: Detailed tabular view with pagination and copy-to-clipboard functionality
- Graph View: Interactive network visualization using Vis.js
- Tree View: Hierarchical visualization organized by route structure
Route Validation: Visual indicators for duplicate routes, missing controllers, and missing methods
Export Options: Download filtered route data in various formats
Telescope Integration: Direct links to route performance data (when available)

Artisan Commands

Install Package

Install and publish all package files:

php artisan route-visualizer:install

Export Routes

Export your route structure to static files with advanced filtering:

# Export to HTML (default)
php artisan route:export

# Export to JSON
php artisan route:export --format=json

# Export to SVG
php artisan route:export --format=svg

# Export with filters
php artisan route:export --filter-method=GET --filter-search=api

# Filter by middleware
php artisan route:export --filter-middleware=auth

# Filter by domain
php artisan route:export --filter-domain=api.example.com

# Filter by namespace
php artisan route:export --filter-namespace="App\Http\Controllers\Api"

# Filter by middleware group
php artisan route:export --filter-middleware-group=web

# Specify custom output path
php artisan route:export --output=/path/to/routes.html

# Use custom template
php artisan route:export --template=minimal

Programmatic Usage

You can also use the route scanner programmatically:

use onamfc\LaravelRouteVisualizer\Services\RouteScanner;

class YourController extends Controller
{
    public function analyzeRoutes(RouteScanner $scanner)
    {
        // Get all routes with validation
        $routes = $scanner->scanRoutes();
        
        // Get routes grouped by controller
        $byController = $scanner->getRoutesGroupedByController();
        
        // Get routes grouped by middleware
        $byMiddleware = $scanner->getRoutesGroupedByMiddleware();
        
        // Get routes grouped by domain
        $byDomain = $scanner->getRoutesGroupedByDomain();
        
        // Get routes grouped by namespace
        $byNamespace = $scanner->getRoutesGroupedByNamespace();
        
        // Find duplicate routes
        $duplicates = $scanner->findDuplicateRoutes();
        
        // Get hierarchical tree data
        $treeData = $scanner->getTreeData();
        
        // Clear cache
        $scanner->clearCache();
        
        return response()->json($routes);
    }
}

API Endpoints

The package provides several API endpoints:

GET /route-visualizer/routes - Get filtered route data with pagination
GET /route-visualizer/graph - Get network graph data for Vis.js
GET /route-visualizer/tree-data - Get hierarchical tree data
POST /route-visualizer/clear-cache - Clear route cache

Query Parameters

Filter routes using query parameters:

GET /route-visualizer/routes?search=api&method=POST&middleware=auth&domain=api.example.com&namespace=App\Http\Controllers\Api&middleware_group=web&page=1&per_page=50

Customization

Custom Views

After publishing views, you can customize the dashboard:

php artisan vendor:publish --tag=route-visualizer-views

Edit the views in resources/views/vendor/route-visualizer/.

Custom Styling

You can customize colors and styling by:

Publishing the views and modifying the CSS
Overriding the Tailwind classes in your custom views
Adding custom CSS to your application's stylesheets

Custom Export Templates

Create custom export templates by extending the base export view:

// In your AppServiceProvider
View::composer('route-visualizer::export.html', function ($view) {
    $view->with('customData', 'Your custom data');
});

Network Visualization

The package uses Vis.js for interactive network graphs that show relationships between routes and controllers. The visualization provides:

Interactive node dragging and zooming
Color-coded nodes for different types (controllers vs routes)
Validation status indicators (errors in red, warnings in yellow)
Hover tooltips with detailed information

Security Considerations

Production Usage

The visualizer is automatically disabled in production environments. To enable it:

ROUTE_VISUALIZER_ENABLED=true

Sensitive Routes

Configure patterns to hide sensitive routes:

'security' => [
    'hide_sensitive_routes' => true,
    'sensitive_patterns' => [
        'admin/*',
        'api/admin/*',
        '*/password/*',
        'telescope/*',
        'horizon/*',
        'nova/*',
    ],
],

Access Control

Add authentication middleware:

'middleware' => ['web', 'auth', 'admin'],

Performance

Caching

Enable caching for better performance with large route sets:

'cache' => [
    'enabled' => true,
    'ttl' => 3600, // 1 hour
],

Pagination

The package includes built-in pagination and lazy loading:

'visualization' => [
    'pagination' => [
        'enabled' => true,
        'per_page' => 50,
    ],
],

Memory Usage

For applications with thousands of routes, consider:

Enabling route caching
Using pagination in the web interface
Filtering routes at the scanner level
Using the export functionality for static analysis

Validation Features

The package automatically validates your routes and identifies:

Duplicate Routes: Routes with identical URIs and HTTP methods
Missing Controllers: Routes pointing to non-existent controller classes
Missing Methods: Routes pointing to non-existent controller methods

Configure validation in your config file:

'validation' => [
    'check_duplicates' => true,
    'check_missing_controllers' => true,
    'check_missing_methods' => true,
],

Laravel Telescope Integration

When Laravel Telescope is installed, the visualizer automatically adds direct links to route performance data:

'integrations' => [
    'telescope' => [
        'enabled' => class_exists(\Laravel\Telescope\TelescopeServiceProvider::class),
        'base_url' => '/telescope',
    ],
],

Testing

Run the package tests:

vendor/bin/phpunit

The package includes comprehensive feature and unit tests covering:

Route scanning and data extraction
API endpoints and filtering
Export functionality
Validation features
Graph data generation

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This package is open-sourced software licensed under the MIT license.

onamfc / laravel-route-visualizer

Maintainers

Details