Download the PHP package mghrby/laravel-modular-ddd without Composer

Laravel Modular DDD - Complete Developer Guide

A comprehensive Laravel package for implementing modular Domain-Driven Design architecture with advanced tooling, performance monitoring, CQRS implementation, and enterprise-grade features.

🌟 Features Overview

Core Architecture

• 🏗️ Complete Modular DDD: Vertical slice modules with Domain, Application, Infrastructure, and Presentation layers
• 🔄 Dynamic Module Management: Install, enable, disable, and remove modules without system disruption
• 🔗 Dependency Resolution: Automatic dependency management with version constraints and conflict detection
• 📡 Event-Driven Communication: Inter-module communication through domain events and service contracts

Advanced Development Tools

• ⚡ CQRS Command/Query Bus: Built-in CQRS implementation with validation, caching, and handler auto-registration
• 🛠️ API Scaffolding: Complete REST API generation with authentication, validation, and Swagger documentation
• 🔄 Enterprise API Versioning: Multi-strategy version negotiation with backward compatibility and deprecation management
• 🎯 Domain Events System: Event sourcing support with automatic event discovery and listener generation
• 🗄️ Automatic Migration Generation: Auto-creates migrations when generating modules with smart table naming and structure
• ✅ Validation Rule Generation: Custom validation rule scaffolding with proper module namespace organization
• 🧪 Automated Testing: Intelligent test generation for unit, feature, and integration tests with factory support

Performance & Monitoring

• 📊 Query Performance Analysis: Real-time query monitoring with N+1 detection and optimization recommendations
• 💾 Cache Performance Monitoring: Hit/miss rate tracking with intelligent cache warming suggestions
• 📈 Resource Usage Tracking: Module memory, disk, and execution time monitoring with threshold alerts
• 🚀 Performance Middleware: Comprehensive HTTP request performance analysis with automatic reporting

Security & Authorization

• 🔐 Module Authorization System: Fine-grained permission management with role-based access control
• 🛡️ Security Scanner: Automated security vulnerability detection and recommendations
• 🔍 Health Monitoring: Comprehensive module health checks with dependency validation
• ✅ Code Quality Analysis: Automated code quality assessment and improvement suggestions

📦 Installation

Requirements

• PHP 8.2+
• Laravel 11.0+
• Composer 2.0+

Install via Composer

Publish Configuration

Database Setup

🚀 Quick Start Guide

1. Create Your First Module

2. Module Structure Created

3. Check Module Health

📋 Complete Command Reference

🏗️ Module Management Commands

Core Module Operations

🛠️ Code Generation Commands

CQRS Components

Complete API Scaffolding

Domain Components

Testing Components

Authorization Components

Database Components

Validation Components

🔄 API Versioning Commands

Version Management

API Version Generation

Version Discovery & Testing

📚 API Documentation & Swagger Commands

The package provides comprehensive Swagger/OpenAPI 3.0.3 documentation with dedicated management commands for scanning, generating, and validating API documentation across all modules.

🔍 Swagger Management Commands

Scan Modules for Swagger Annotations:

Generate Comprehensive Documentation Files:

Validate Documentation Quality:

🚀 Enhanced API Generation with Comprehensive Swagger

When you generate APIs using the module:make-api command, the package now creates comprehensive Swagger documentation by default:

📊 Generated Documentation Features

Comprehensive OpenAPI 3.0.3 Annotations:

• Detailed Parameter Documentation: Query parameters, path parameters, request bodies
• Authentication Integration: Bearer tokens, OAuth2 flows, API key support
• Response Examples: Success and error responses with realistic data
• Schema Definitions: Automatic model schema extraction from validation rules
• HATEOAS Support: Hypermedia links for API navigation
• Error Handling: Standard HTTP error responses with proper descriptions

Example Generated Controller:

🎯 Accessing Generated Documentation

Local Documentation Server:

File-based Documentation:

• JSON Format: storage/api-docs/ModuleName.json
• YAML Format: storage/api-docs/ModuleName.yaml
• Swagger UI: storage/api-docs/ModuleName-ui.html
• Combined Docs: storage/api-docs/api-documentation.json

⚙️ Swagger Configuration

Configure comprehensive documentation in config/modular-ddd.php:

🔐 Authentication Integration

Automatic Authentication Detection:

• Bearer Tokens: JWT and personal access tokens
• Laravel Passport: OAuth2 flows with automatic client detection
• API Keys: Custom header-based authentication

OAuth2 Configuration Example:

📋 Validation and Quality Assurance

Documentation Quality Checks:

Quality Metrics:

• API Coverage: Percentage of endpoints with documentation
• Schema Completeness: Validation of request/response schemas
• Security Documentation: Authentication scheme coverage
• Error Handling: Standard HTTP error response coverage
• Example Completeness: Request/response example availability

🎨 Advanced Features

HATEOAS Support:

Multi-Version Support:

Custom Schema Definitions:

• Automatic schema extraction from validation rules
• Support for nested objects and arrays
• Enum values from validation rules
• Custom format validation (email, date, etc.)

🔧 Troubleshooting

Documentation Not Generating:

Missing Authentication:

Quality Issues:

📊 Performance Analysis Commands

Comprehensive Performance Analysis

🔐 Authorization Management Commands

Permission Management

🗄️ Automatic Migration Generation

The package automatically generates database migrations when creating modules, following smart naming conventions and providing a solid foundation that you can customize.

Default Behavior (Automatic Migration)

Opt-out (No Migration)

Generated Migration Structure

Manual Migration Creation

🗄️ Database Operations

🏥 Health & Security Commands

Health Monitoring

Security Analysis

🔧 Development Tools

Cache Management

Development Utilities

💻 Usage Examples

Basic Module Creation Workflow

CQRS Usage in Code

API Versioning Usage

Authorization Usage

Performance Monitoring

⚙️ Configuration

Main Configuration (config/modular-ddd.php)

Module Permissions Configuration

Create modules/YourModule/Config/permissions.php:

🗃️ Database Schema

Required Tables for Authorization

🏗️ Architecture Principles

Domain-Driven Design (DDD)

• Bounded Contexts: Each module represents a bounded context with clear boundaries
• Ubiquitous Language: Consistent terminology throughout each module
• Aggregate Roots: Clear aggregate boundaries with proper encapsulation
• Domain Events: Event-driven communication between bounded contexts

CQRS (Command Query Responsibility Segregation)

• Commands: Write operations with validation and business logic
• Queries: Read operations with caching and optimization
• Handlers: Separate handlers for commands and queries
• Bus Pattern: Centralized command and query dispatching

Event Sourcing

• Domain Events: Capture state changes as events
• Event Store: Persistent storage of domain events
• Event Replay: Ability to rebuild state from events
• Projections: Read models built from events

Module Independence

• Vertical Slices: Complete feature implementation within modules
• Service Contracts: Interface-based communication between modules
• Dependency Injection: Loose coupling through dependency injection
• Event-Driven Communication: Asynchronous communication via domain events

📚 Advanced Features Documentation

CQRS Implementation

• Complete CQRS Guide
• Command and Query patterns
• Handler registration and discovery
• Validation and caching strategies

API Scaffolding & Versioning

• API Scaffolding Guide
• REST API generation
• Authentication and authorization
• Swagger documentation
• API Versioning Guide
• Multi-version support
• Backward compatibility
• Version negotiation strategies

Performance Monitoring

• Performance Monitoring Guide
• Query performance analysis
• Cache optimization
• Resource usage tracking

Authorization System

• Authorization Guide
• Permission management
• Role-based access control
• Policy generation

🛡️ Security Best Practices

Permission Management

• Use fine-grained permissions with clear naming conventions
• Implement permission dependencies to prevent privilege escalation
• Regular permission audits using matrix commands
• Cache permissions for performance while maintaining security

Input Validation

• Always validate input at the request level
• Use form requests for complex validation rules
• Implement CQRS command validation
• Sanitize data before processing

Authorization Checks

• Use middleware for route protection
• Implement policy-based authorization for complex logic
• Check permissions at multiple layers (route, controller, service)
• Log authorization failures for security monitoring

📈 Performance Optimization

Query Optimization

• Monitor for N+1 query patterns
• Use eager loading appropriately
• Implement query result caching
• Set appropriate slow query thresholds

Cache Strategy

• Cache frequently accessed data
• Implement cache warming for critical data
• Monitor cache hit/miss rates
• Use appropriate TTL values

Resource Management

• Monitor module resource usage
• Set memory and execution time thresholds
• Implement lazy loading for non-critical modules
• Regular performance audits

🐛 Troubleshooting

Common Issues

Module Not Loading

Permission Issues

Performance Issues

🤝 Contributing

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

Development Setup

📄 License

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

🆘 Support

• Documentation: Check the comprehensive guides in the src/ directories
• Issues: Report bugs and request features on GitHub Issues
• Discussions: Join community discussions on GitHub Discussions

🙏 Acknowledgments

• Laravel Framework team for the excellent foundation
• DDD Community for architectural guidance
• Contributors and users who make this package better

Built with ❤️ for the Laravel community