README

Advanced Laravel application mapping and visualization toolkit. Analyze, document, and visualize your Laravel project architecture with comprehensive dependency mapping and multiple export formats.

📖 Table of Contents

Overview
✨ Features
📦 Installation
🚀 Quick Start
🗺️ Architecture Mapping
📊 Export Formats
🔍 Analysis Tools
⚙️ Configuration
📚 Documentation
💡 Examples
🧪 Testing
🔧 Requirements
🚀 Performance
🤝 Contributing
🔒 Security
📄 License

Overview

Laravel Atlas is an advanced application mapping and visualization toolkit that scans your Laravel project to generate comprehensive architectural documentation. It analyzes models, services, routes, jobs, events, commands, and their interconnections, then exports visual representations in multiple formats.

Perfect for code documentation, team onboarding, architecture reviews, and maintaining large enterprise applications.

🎯 Use Cases

Laravel Atlas is perfect for:

Code Documentation - Generate comprehensive application maps
Team Onboarding - Visual architecture overviews for new developers
Architecture Reviews - Analyze application structure and dependencies
Legacy Code Analysis - Understand complex existing applications
Compliance Reporting - Generate architectural documentation

✨ Features

🚀 Comprehensive Scanning - Analyze 17 different Laravel component types
🗺️ Architecture Mapping - Generate detailed application structure maps
📊 Multiple Export Formats - Export to JSON, HTML, Markdown, Image, PDF, and PHP
🔍 Dependency Analysis - Track relationships and dependencies between components
📋 Extensible Architecture - Support for custom mappers and exporters
🎯 Smart Detection - Intelligent component discovery and classification
📈 Visual Diagrams - Generate beautiful architectural diagrams
🧪 Analysis Reports - Comprehensive architectural analysis reports
⚡ CLI Integration - Powerful Artisan commands for map generation
💻 Programmatic API - Full PHP API with Atlas facade
🔧 Intelligent HTML Export - Advanced PHP-to-HTML workflow for complex visualizations
📝 Documentation Generation - Auto-generate architecture documentation

📦 Installation

Install the package via Composer:

composer require grazulex/laravel-atlas --dev

💡 Auto-Discovery
The service provider will be automatically registered thanks to Laravel's package auto-discovery.

Publish configuration:

php artisan vendor:publish --tag=atlas-config

🚀 Quick Start

1. Generate Your First Map

php artisan atlas:generate

This creates a JSON output showing all discovered components in your application.

2. Generate Specific Component Maps

# Generate model architecture map
php artisan atlas:generate --type=models --format=markdown

# Generate service layer map
php artisan atlas:generate --type=services --format=html

# Generate complete application map
php artisan atlas:generate --type=all --format=json --output=docs/architecture.json

3. Customize Export Formats

# Generate JSON output (default)
php artisan atlas:generate --format=json

# Generate comprehensive markdown documentation
php artisan atlas:generate --format=markdown

# Generate interactive HTML map with intelligent workflow
php artisan atlas:generate --format=html

# Generate visual diagrams as images
php artisan atlas:generate --format=image

# Generate PDF reports
php artisan atlas:generate --format=pdf

4. Access Generated Maps Programmatically

use LaravelAtlas\Facades\Atlas;

// Scan specific component types
$modelData = Atlas::scan('models');
$routeData = Atlas::scan('routes');

// Export to different formats
$jsonOutput = Atlas::export('models', 'json');
$markdownDocs = Atlas::export('routes', 'markdown');
$htmlReport = Atlas::export('services', 'html');
$pdfDocument = Atlas::export('controllers', 'pdf');

🗺️ Architecture Mapping

Laravel Atlas provides comprehensive architecture mapping capabilities through specialized mappers:

use LaravelAtlas\Facades\Atlas;

// Model architecture mapping
$modelData = Atlas::scan('models', [
    'include_relationships' => true,
    'include_observers' => true,
    'include_factories' => true,
]);

// Service layer mapping
$serviceData = Atlas::scan('services', [
    'include_dependencies' => true,
    'include_interfaces' => true,
]);

// Route mapping
$routeData = Atlas::scan('routes', [
    'include_middleware' => true,
    'include_controllers' => true,
    'group_by_prefix' => true,
]);

// Additional component types available
$jobData = Atlas::scan('jobs');
$eventData = Atlas::scan('events');
$commandData = Atlas::scan('commands');
$middlewareData = Atlas::scan('middleware');
$policyData = Atlas::scan('policies');
$resourceData = Atlas::scan('resources');
$notificationData = Atlas::scan('notifications');
$requestData = Atlas::scan('requests');
$ruleData = Atlas::scan('rules');
$observerData = Atlas::scan('observers');
$listenerData = Atlas::scan('listeners');
$actionData = Atlas::scan('actions');

Available Component Types

Laravel Atlas can analyze 17 different component types:

models - Eloquent models with relationships, observers, and factories
routes - Application routes with middleware and controllers
jobs - Queued jobs and their properties
services - Service classes and their dependencies
controllers - Controllers and their methods
events - Application events and listeners
commands - Artisan commands
middleware - HTTP middleware
policies - Authorization policies
resources - API resources
notifications - Notification classes
requests - Form request classes
rules - Custom validation rules
observers - Eloquent model observers
listeners - Event listeners
actions - Action classes


## 📊 Export Formats

Multiple export formats for different use cases:

```bash
# JSON for data processing and API integration
php artisan atlas:generate --format=json --output=storage/atlas/map.json

# Markdown documentation for README files
php artisan atlas:generate --format=markdown --output=docs/ARCHITECTURE.md

# Interactive HTML maps with intelligent workflow
php artisan atlas:generate --format=html --output=public/atlas/map.html

# Visual diagrams as PNG/JPG images
php artisan atlas:generate --format=image --output=docs/architecture.png

# PDF reports for documentation
php artisan atlas:generate --format=pdf --output=reports/architecture.pdf

# PHP code for advanced processing
php artisan atlas:generate --format=php --output=storage/atlas/map.php

Programmatic Export

use LaravelAtlas\Facades\Atlas;

// Export specific types to different formats
$jsonOutput = Atlas::export('models', 'json');
$markdownDocs = Atlas::export('routes', 'markdown');
$htmlReport = Atlas::export('controllers', 'html');
$imageFile = Atlas::export('services', 'image');
$pdfReport = Atlas::export('all', 'pdf');

🔍 Analysis Tools

Laravel Atlas provides comprehensive component analysis:

use LaravelAtlas\Facades\Atlas;

// Analyze specific component types
$modelAnalysis = Atlas::scan('models', [
    'include_relationships' => true,
    'include_observers' => true
]);

$routeAnalysis = Atlas::scan('routes', [
    'include_middleware' => true,
    'include_controllers' => true
]);

// Generate detailed reports
$allComponents = Atlas::scan('all', ['detailed' => true]);

// Export analysis results
$analysisReport = Atlas::export('all', 'markdown', [
    'include_stats' => true,
    'detailed_sections' => true
]);

⚙️ Configuration

Laravel Atlas provides extensive configuration options:

// config/atlas.php
return [
    'enabled' => env('ATLAS_ENABLED', true),
    
    'status_tracking' => [
        'enabled' => env('ATLAS_STATUS_TRACKING_ENABLED', true),
        'file_path' => env('ATLAS_STATUS_FILE_PATH', storage_path('logs/atlas_status.log')),
        'track_history' => env('ATLAS_TRACK_HISTORY', true),
        'max_entries' => env('ATLAS_MAX_ENTRIES', 1000),
    ],
    
    'generation' => [
        'output_path' => env('ATLAS_OUTPUT_PATH', base_path('atlas')),
        'formats' => [
            'image' => env('ATLAS_FORMAT_IMAGE', true),
            'json' => env('ATLAS_FORMAT_JSON', true),
            'markdown' => env('ATLAS_FORMAT_MARKDOWN', true),
        ],
    ],
    
    'analysis' => [
        'include_vendors' => env('ATLAS_INCLUDE_VENDORS', false),
        'max_depth' => env('ATLAS_MAX_DEPTH', 10),
        'scan_paths' => [
            app_path(),
            database_path(),
            config_path(),
        ],
    ],
];
];

📚 Documentation

For detailed documentation, examples, and advanced usage:

💡 Examples

Generate Complete Application Map

# Generate comprehensive application architecture
php artisan atlas:generate --type=all --format=html --output=docs/architecture.html

# Generate specific component maps
php artisan atlas:generate --type=models --format=markdown --output=docs/models.md
php artisan atlas:generate --type=services --format=json --output=docs/services.json
php artisan atlas:generate --type=routes --format=image --output=docs/routes.png

Custom Architecture Analysis

use LaravelAtlas\Facades\Atlas;

// Custom analysis workflow
$modelData = Atlas::scan('models', ['include_relationships' => true]);
$routeData = Atlas::scan('routes', ['include_middleware' => true]);

$markdownReport = Atlas::export('models', 'markdown', [
    'include_stats' => true,
    'detailed_sections' => true,
]);

file_put_contents('docs/architecture-analysis.md', $markdownReport);

Interactive Architecture Explorer

// Generate intelligent HTML map with advanced features
$htmlOutput = Atlas::export('all', 'html');
file_put_contents('public/atlas/explorer.html', $htmlOutput);

// Or use the intelligent HTML workflow for complex applications
use LaravelAtlas\AtlasManager;

$manager = app(AtlasManager::class);
$intelligentHtml = $manager->exportIntelligentHtml([
    'models' => Atlas::scan('models'),
    'routes' => Atlas::scan('routes'),
    'services' => Atlas::scan('services'),
]);
file_put_contents('public/atlas/intelligent-map.html', $intelligentHtml);

CI/CD Integration

# In your CI/CD pipeline
php artisan atlas:generate --type=all --format=json --output=docs/architecture.json
php artisan atlas:generate --type=all --format=markdown --output=docs/ARCHITECTURE.md
php artisan atlas:generate --type=all --format=html --output=public/docs/architecture.html

# Generate specific component documentation
php artisan atlas:generate --type=models --format=markdown --output=docs/models.md
php artisan atlas:generate --type=routes --format=json --output=api/routes.json

Advanced Export Examples

use LaravelAtlas\Facades\Atlas;

// Generate PDF report for architecture review
$pdfReport = Atlas::export('all', 'pdf');
file_put_contents('reports/architecture-review.pdf', $pdfReport);

// Export raw PHP data for custom processing
$phpData = Atlas::export('models', 'php');
file_put_contents('storage/atlas/models-data.php', $phpData);

// Generate visual diagrams
$imageData = Atlas::export('services', 'image');
file_put_contents('public/diagrams/services.png', $imageData);

Check out the examples directory for more examples.

🧪 Testing

Laravel Atlas includes testing utilities and can be tested in your application:

use Tests\TestCase;
use LaravelAtlas\Facades\Atlas;

class ArchitectureTest extends TestCase
{
    public function test_models_can_be_scanned(): void
    {
        $data = Atlas::scan('models');
        
        $this->assertIsArray($data);
        $this->assertArrayHasKey('type', $data);
        $this->assertEquals('models', $data['type']);
        $this->assertArrayHasKey('data', $data);
    }

    public function test_json_export_is_valid(): void
    {
        $json = Atlas::export('models', 'json');
        
        $decoded = json_decode($json, true);
        $this->assertIsArray($decoded);
    }
}

🔧 Requirements

PHP: ^8.3
Laravel: ^12.0
Carbon: ^3.10

🚀 Performance

Laravel Atlas is optimized for performance:

Efficient Scanning: Optimized file system scanning and parsing
Smart Caching: Intelligent caching of analysis results
Memory Management: Efficient memory usage for large applications
Incremental Updates: Only scan changed files when possible

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🔒 Security

If you discover a security vulnerability, please review our Security Policy before disclosing it.

📄 License

Laravel Atlas is open-sourced software licensed under the MIT license.

Made with ❤️ for the Laravel community

Resources

Community Links

CODE_OF_CONDUCT.md - Our code of conduct
CONTRIBUTING.md - How to contribute
SECURITY.md - Security policy
RELEASES.md - Release notes and changelog

grazulex / laravel-atlas

Maintainers

Details