PHPackages                             mghrby/laravel-modular-ddd - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. mghrby/laravel-modular-ddd

ActiveLibrary[Framework](/categories/framework)

mghrby/laravel-modular-ddd
==========================

A comprehensive Laravel package for building modular applications using Domain-Driven Design principles

1.1.4(9mo ago)045MITPHPPHP ^8.1|^8.2|^8.3CI failing

Since Sep 14Pushed 9mo agoCompare

[ Source](https://github.com/theaddresstech/laravel-modular-ddd)[ Packagist](https://packagist.org/packages/mghrby/laravel-modular-ddd)[ Docs](https://github.com/theaddresstech/laravel-modular-ddd)[ GitHub Sponsors](https://github.com/sponsors/tai-crm)[ OpenCollective](https://opencollective.com/tai-crm)[ RSS](/packages/mghrby-laravel-modular-ddd/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (21)Versions (8)Used By (0)

Laravel Modular DDD - Complete Developer Guide
==============================================

[](#laravel-modular-ddd---complete-developer-guide)

[![Latest Version](https://camo.githubusercontent.com/d1a2c2727a73248611a70e03d3692c2f7ba94b2371fa1f224e67193f74102811/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d67687262792f6c61726176656c2d6d6f64756c61722d6464642e737667)](https://packagist.org/packages/mghrby/laravel-modular-ddd)[![License](https://camo.githubusercontent.com/4e62fd8592e5d5d9c932258d5d9e8c24540947edb25991488b5015d7c73f97ee/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d67687262792f6c61726176656c2d6d6f64756c61722d6464642e737667)](https://packagist.org/packages/mghrby/laravel-modular-ddd)[![PHP Version](https://camo.githubusercontent.com/f7dd8aec0b4a943b7778b73857c12a1259c0293f7bad35bf83cce6a94c8e35cb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6d67687262792f6c61726176656c2d6d6f64756c61722d6464642e737667)](https://packagist.org/packages/mghrby/laravel-modular-ddd)

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

🌟 Features Overview
-------------------

[](#-features-overview)

### Core Architecture

[](#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

[](#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

[](#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

[](#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
--------------

[](#-installation)

### Requirements

[](#requirements)

- PHP 8.2+
- Laravel 11.0+
- Composer 2.0+

### Install via Composer

[](#install-via-composer)

```
composer require mghrby/laravel-modular-ddd
```

### Publish Configuration

[](#publish-configuration)

```
# Publish configuration files
php artisan vendor:publish --provider="TaiCrm\LaravelModularDdd\ModularDddServiceProvider" --tag="config"

# Publish stub templates (optional)
php artisan vendor:publish --provider="TaiCrm\LaravelModularDdd\ModularDddServiceProvider" --tag="stubs"
```

### Database Setup

[](#database-setup)

```
# Create required tables for authorization system
php artisan migrate
```

🚀 Quick Start Guide
-------------------

[](#-quick-start-guide)

### 1. Create Your First Module

[](#1-create-your-first-module)

```
# Generate a complete module with DDD structure + migration
php artisan module:make UserModule --aggregate=User

# Or create module without migration
php artisan module:make UserModule --aggregate=User --no-migration

# Generate complete REST API for the module
php artisan module:make-api UserModule User --auth --validation --swagger --comprehensive --examples

# Install and enable the module
php artisan module:install UserModule
php artisan module:enable UserModule
```

### 2. Module Structure Created

[](#2-module-structure-created)

```
modules/UserModule/
├── manifest.json              # Module configuration and dependencies
├── Config/
│   └── permissions.php        # Module permissions configuration
├── Domain/
│   ├── Entities/             # Domain entities and aggregates
│   ├── ValueObjects/         # Value objects
│   ├── Events/               # Domain events
│   ├── Services/             # Domain services
│   └── Contracts/            # Domain interfaces
├── Application/
│   ├── Commands/             # CQRS commands
│   ├── Queries/              # CQRS queries
│   ├── Handlers/             # Command and query handlers
│   └── Services/             # Application services
├── Infrastructure/
│   ├── Repositories/         # Data repositories
│   ├── External/             # External service integrations
│   └── Persistence/          # Database models
├── Presentation/
│   └── Http/
│       ├── Controllers/      # HTTP controllers
│       ├── Requests/         # Form request validation
│       ├── Resources/        # API resources
│       └── Middleware/       # HTTP middleware
├── Database/
│   ├── Migrations/           # Database migrations
│   ├── Seeders/              # Database seeders
│   └── Factories/            # Model factories
├── Routes/
│   ├── api.php              # API routes
│   └── web.php              # Web routes
├── Tests/
│   ├── Unit/                # Unit tests
│   ├── Feature/             # Feature tests
│   └── Integration/         # Integration tests
├── Policies/                # Authorization policies
└── Docs/                    # Module documentation

```

### 3. Check Module Health

[](#3-check-module-health)

```
# Comprehensive health check
php artisan module:health UserModule

# Performance analysis
php artisan module:performance:analyze --module=UserModule

# Security scan
php artisan module:security UserModule
```

📋 Complete Command Reference
----------------------------

[](#-complete-command-reference)

### 🏗️ Module Management Commands

[](#️-module-management-commands)

#### Core Module Operations

[](#core-module-operations)

```
# List all modules with detailed status
php artisan module:list

# Create new module with full DDD structure + migration
php artisan module:make {ModuleName} [--aggregate={AggregateName}] [--no-migration]

# Install module and resolve dependencies
php artisan module:install {ModuleName}

# Enable module and register services
php artisan module:enable {ModuleName}

# Disable module safely
php artisan module:disable {ModuleName}

# Remove module and cleanup
php artisan module:remove {ModuleName}

# Show detailed module status
php artisan module:status {ModuleName}

# Update module to newer version
php artisan module:update {ModuleName}
php artisan module:update --all

# Create and restore backups
php artisan module:backup {ModuleName}
php artisan module:restore {BackupFile}
```

### 🛠️ Code Generation Commands

[](#️-code-generation-commands)

#### CQRS Components

[](#cqrs-components)

```
# Create CQRS command with validation
php artisan module:make-command {Module} {CommandName} [--aggregate={Name}] [--validation]

# Create CQRS query with caching
php artisan module:make-query {Module} {QueryName} [--aggregate={Name}] [--cacheable]

# Examples:
php artisan module:make-command UserModule CreateUser --aggregate=User --validation
php artisan module:make-query UserModule GetUser --aggregate=User --cacheable
```

#### Complete API Scaffolding

[](#complete-api-scaffolding)

```
# Generate complete REST API with all components and versioning
php artisan module:make-api {Module} {Resource} [--auth] [--validation] [--swagger] [--api-version={v1|v2}] [--all-versions] [--examples] [--comprehensive] [--guard={api|web}]

# Option explanations:
# --auth              : Add authentication middleware to routes
# --validation        : Generate request validation classes
# --swagger           : Generate Swagger/OpenAPI documentation
# --api-version=v2    : Generate for specific API version
# --all-versions      : Generate for all configured API versions
# --examples          : Include usage examples in documentation
# --comprehensive     : Generate detailed validation rules and examples
# --guard=api         : Specify authentication guard (default: api)

# Generate individual API components
php artisan module:make-controller {Module} {Controller} [--api] [--resource={Model}] [--middleware={Name}]
php artisan module:make-request {Module} {Request} [--resource={Name}] [--validation]
php artisan module:make-resource {Module} {Resource} [--collection] [--model={Name}]
php artisan module:make-middleware {Module} {Middleware} [--auth] [--rate-limit] [--cors]

# Examples:
php artisan module:make-api UserModule User --auth --validation --swagger --comprehensive --examples
php artisan module:make-api UserModule User --auth --validation --swagger --api-version=v2 --guard=api
php artisan module:make-api UserModule User --auth --validation --swagger --all-versions --comprehensive
php artisan module:make-controller UserModule UserController --api --resource=User
php artisan module:make-request UserModule CreateUserRequest --validation
php artisan module:make-resource UserModule UserResource --model=User
```

#### Domain Components

[](#domain-components)

```
# Create domain events and listeners
php artisan module:make-event {Module} {EventName} [--aggregate={Name}]
php artisan module:make-listener {Module} {ListenerName} [--event={EventName}]

# Examples:
php artisan module:make-event UserModule UserRegistered --aggregate=User
php artisan module:make-listener UserModule SendWelcomeEmail --event=UserRegistered
```

#### Testing Components

[](#testing-components)

```
# Generate intelligent tests
php artisan module:make-test {Module} {TestName} [--type={unit|feature|integration}]
php artisan module:make-factory {Module} {ModelName}

# Examples:
php artisan module:make-test UserModule UserServiceTest --type=unit
php artisan module:make-test UserModule UserApiTest --type=feature
php artisan module:make-factory UserModule User
```

#### Authorization Components

[](#authorization-components)

```
# Create authorization policies
php artisan module:make-policy {Module} {PolicyName} [--model={Name}] [--resource] [--api]

# Examples:
php artisan module:make-policy UserModule UserPolicy --model=User --resource
php artisan module:make-policy UserModule UserApiPolicy --model=User --resource --api
```

#### Database Components

[](#database-components)

```
# Migrations are auto-generated with module creation
# For additional migrations, use:
php artisan module:make-migration {Module} {MigrationName} [--create={table}] [--table={table}]

# Examples:
php artisan module:make-migration UserModule CreateUsersTable --create=users
php artisan module:make-migration UserModule AddEmailToUsersTable --table=users
php artisan module:make-migration UserModule UpdateUserPermissions
```

#### Validation Components

[](#validation-components)

```
# Create custom validation rules
php artisan module:make-rule {Module} {RuleName}

# Examples:
php artisan module:make-rule UserModule Uppercase
php artisan module:make-rule UserModule ValidEmail
php artisan module:make-rule UserModule StrongPassword
```

### 🔄 API Versioning Commands

[](#-api-versioning-commands)

#### Version Management

[](#version-management)

```
# Check available API versions
curl -H "Accept: application/json" http://localhost/api/versions

# Get module-specific version information
curl -H "Accept: application/json" http://localhost/api/modules/{module}/versions

# Test different version negotiation strategies
curl -H "Accept-Version: v2" http://localhost/api/users                    # Header-based
curl http://localhost/api/v2/users                                          # URL-based
curl http://localhost/api/users?api_version=v2                             # Query parameter
curl -H "Accept: application/vnd.api+json;version=2" http://localhost/api/users  # Content negotiation
```

#### API Version Generation

[](#api-version-generation)

```
# Generate API for specific version
php artisan module:make-api UserModule User --api-version=v2 --auth --validation --swagger --comprehensive

# Generate API for all supported versions
php artisan module:make-api UserModule User --all-versions --auth --validation --swagger --comprehensive --examples

# The above commands will create:
# - Http/Controllers/Api/v1/UserController.php
# - Http/Controllers/Api/v2/UserController.php
# - Routes/api.php (with versioned routes)
# - Docs/v1/UserApi.php (version-specific documentation)
# - Docs/v2/UserApi.php
```

#### Version Discovery & Testing

[](#version-discovery--testing)

```
# Test version negotiation
curl -i -H "Accept-Version: v1" http://localhost/api/users
# Response headers will include:
# X-API-Version: v1
# X-API-Supported-Versions: v1, v2
# Warning: 299 - "This API version (v1) is deprecated. It will be sunset on 2025-12-31."

# Test unsupported version
curl -i -H "Accept-Version: v99" http://localhost/api/users
# Returns HTTP 406 with supported versions list
```

### 📚 API Documentation & Swagger Commands

[](#-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

[](#-swagger-management-commands)

**Scan Modules for Swagger Annotations:**

```
# Scan all modules for Swagger annotations
php artisan module:swagger:scan

# Scan specific module
php artisan module:swagger:scan BlogModule

# Scan with export to files
php artisan module:swagger:scan --export --format=json --output=storage/api-docs

# Generate combined documentation and Swagger UI
php artisan module:swagger:scan --export --combined --ui --format=json
```

**Generate Comprehensive Documentation Files:**

```
# Generate documentation for all modules
php artisan module:swagger:generate

# Generate for specific module with UI
php artisan module:swagger:generate BlogModule --ui --output=public/docs

# Generate in YAML format with combined docs
php artisan module:swagger:generate --format=yaml --combined --individual

# Serve documentation locally
php artisan module:swagger:generate --serve --port=8080
```

**Validate Documentation Quality:**

```
# Validate all module documentation
php artisan module:swagger:validate

# Validate specific module with strict mode
php artisan module:swagger:validate BlogModule --strict

# Auto-fix common issues
php artisan module:swagger:validate --fix

# Generate validation report
php artisan module:swagger:validate --report=validation-report.json
```

#### 🚀 Enhanced API Generation with Comprehensive Swagger

[](#-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:

```
# Generate API with comprehensive Swagger documentation (default behavior)
php artisan module:make-api BlogModule Post --auth --validation --swagger

# The above generates:
# ✅ Full OpenAPI 3.0.3 annotations
# ✅ Authentication schemes (Bearer, OAuth2)
# ✅ Comprehensive parameter documentation
# ✅ Response examples with proper HTTP status codes
# ✅ Error response handling (400, 401, 403, 404, 422, 500)
# ✅ HATEOAS links for resource navigation
# ✅ Schema definitions with validation rules
# ✅ Request/response examples with realistic data
```

#### 📊 Generated Documentation Features

[](#-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:**

```
/**
 * @OA\Get(
 *     path="/api/v1/posts",
 *     operationId="listPostsv1",
 *     tags={"Post"},
 *     summary="Get paginated list of Posts",
 *     description="Retrieve a paginated list of Posts with optional filtering, sorting, and pagination parameters.",
 *     security={{"bearerAuth": {}}, {"oauth2": {}}},
 *     @OA\Parameter(name="page", in="query", description="Page number for pagination", required=false, @OA\Schema(type="integer", minimum=1, default=1, example=1)),
 *     @OA\Parameter(name="per_page", in="query", description="Number of items per page", required=false, @OA\Schema(type="integer", minimum=1, maximum=100, default=15, example=15)),
 *     @OA\Response(
 *         response=200,
 *         description="Successfully retrieved Posts",
 *         @OA\JsonContent(
 *             @OA\Property(property="data", type="array", @OA\Items(ref="#/components/schemas/Post")),
 *             @OA\Property(property="links", type="object", example={"first": "http://localhost/api/v1/posts?page=1", "last": "http://localhost/api/v1/posts?page=5", "prev": null, "next": "http://localhost/api/v1/posts?page=2"}),
 *             @OA\Property(property="meta", type="object", example={"current_page": 1, "from": 1, "last_page": 5, "per_page": 15, "to": 15, "total": 67})
 *         )
 *     ),
 *     @OA\Response(response=401, description="Unauthenticated", @OA\JsonContent(@OA\Property(property="message", type="string", example="Unauthenticated."))),
 *     @OA\Response(response=403, description="Forbidden", @OA\JsonContent(@OA\Property(property="message", type="string", example="This action is unauthorized."))),
 *     @OA\Response(response=500, description="Internal Server Error", @OA\JsonContent(@OA\Property(property="message", type="string", example="Internal server error occurred")))
 * )
 */
public function index(): JsonResponse
{
    // Controller implementation
}
```

#### 🎯 Accessing Generated Documentation

[](#-accessing-generated-documentation)

**Local Documentation Server:**

```
# Start documentation server
php artisan module:swagger:generate --serve --port=8080

# Access documentation at:
# http://localhost:8080/api-documentation-ui.html
```

**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

[](#️-swagger-configuration)

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

```
'api' => [
    'documentation' => [
        'swagger' => [
            // Enable comprehensive documentation by default
            'enabled' => env('MODULAR_DDD_SWAGGER_ENABLED', true),

            // Documentation metadata
            'title' => env('MODULAR_DDD_SWAGGER_TITLE', 'Laravel Modular DDD API'),
            'description' => env('MODULAR_DDD_SWAGGER_DESCRIPTION', 'Comprehensive API documentation for modular application'),
            'version' => env('MODULAR_DDD_SWAGGER_VERSION', '1.0.0'),

            // Contact information
            'contact' => [
                'name' => env('MODULAR_DDD_SWAGGER_CONTACT_NAME', 'API Support'),
                'url' => env('MODULAR_DDD_SWAGGER_CONTACT_URL', ''),
                'email' => env('MODULAR_DDD_SWAGGER_CONTACT_EMAIL', ''),
            ],

            // Security schemes
            'security' => [
                'bearer_auth' => env('MODULAR_DDD_SWAGGER_BEARER_AUTH', true),
                'oauth2' => env('MODULAR_DDD_SWAGGER_OAUTH2_AUTH', true),
                'api_key' => env('MODULAR_DDD_SWAGGER_API_KEY_AUTH', false),
            ],

            // Generation settings
            'generation' => [
                'comprehensive_by_default' => env('MODULAR_DDD_SWAGGER_COMPREHENSIVE_DEFAULT', true),
                'auto_examples' => env('MODULAR_DDD_SWAGGER_AUTO_EXAMPLES', true),
                'include_hateoas' => env('MODULAR_DDD_SWAGGER_INCLUDE_HATEOAS', true),
                'include_validation_errors' => env('MODULAR_DDD_SWAGGER_INCLUDE_VALIDATION', true),
            ],

            // Export settings
            'export' => [
                'output_dir' => storage_path('api-docs'),
                'json_options' => JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES,
            ],

            // UI customization
            'ui' => [
                'try_it_out_enabled' => env('MODULAR_DDD_SWAGGER_TRY_IT_OUT', true),
                'deep_linking' => env('MODULAR_DDD_SWAGGER_DEEP_LINKING', true),
                'display_request_duration' => true,
                'doc_expansion' => 'list', // 'list', 'full', 'none'
                'filter' => true,
                'show_extensions' => true,
            ],
        ],
    ],
],
```

#### 🔐 Authentication Integration

[](#-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:**

```
// Automatically detected when Laravel Passport is installed
'oauth2_flows' => [
    'authorizationCode' => [
        'authorizationUrl' => config('app.url') . '/oauth/authorize',
        'tokenUrl' => config('app.url') . '/oauth/token',
        'scopes' => [
            '*' => 'Full access to API',
            'read' => 'Read access to resources',
            'write' => 'Write access to resources',
        ],
    ],
    'clientCredentials' => [
        'tokenUrl' => config('app.url') . '/oauth/token',
        'scopes' => [
            '*' => 'Full access to API',
        ],
    ],
],
```

#### 📋 Validation and Quality Assurance

[](#-validation-and-quality-assurance)

**Documentation Quality Checks:**

```
# Comprehensive validation with detailed reporting
php artisan module:swagger:validate --strict --report=quality-report.json

# Validation output example:
# ✅ BlogModule: 4 endpoints, 2 schemas - Good
# ⚠️  UserModule: 3 warnings (missing descriptions)
# ❌ ProductModule: 2 errors (missing required responses)
```

**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

[](#-advanced-features)

**HATEOAS Support:**

```
{
  "data": {
    "id": 1,
    "title": "Sample Post",
    "content": "Post content here"
  },
  "links": {
    "self": "/api/v1/posts/1",
    "edit": "/api/v1/posts/1",
    "delete": "/api/v1/posts/1",
    "comments": "/api/v1/posts/1/comments"
  }
}
```

**Multi-Version Support:**

```
# Generate documentation for all API versions
php artisan module:make-api BlogModule Post --all-versions --swagger

# Generates:
# - v1/PostController.php with v1-specific documentation
# - v2/PostController.php with v2-specific documentation
# - Version-aware Swagger annotations
```

**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

[](#-troubleshooting)

**Documentation Not Generating:**

```
# Check module status and scan results
php artisan module:swagger:scan ModuleName

# Verify controller annotations
php artisan module:swagger:validate ModuleName --strict

# Clear cache and regenerate
php artisan config:clear && php artisan module:swagger:generate ModuleName
```

**Missing Authentication:**

```
# Verify Passport installation
php artisan passport:client --personal

# Check OAuth2 configuration
php artisan route:list | grep oauth

# Validate security schemes
php artisan module:swagger:validate --strict
```

**Quality Issues:**

```
# Run comprehensive validation
php artisan module:swagger:validate --strict --fix

# Generate detailed quality report
php artisan module:swagger:validate --report=quality-report.json
```

### 📊 Performance Analysis Commands

[](#-performance-analysis-commands)

#### Comprehensive Performance Analysis

[](#comprehensive-performance-analysis)

```
# Analyze all performance aspects
php artisan module:performance:analyze

# Module-specific analysis
php artisan module:performance:analyze --module={ModuleName}

# Type-specific analysis
php artisan module:performance:analyze --type=queries    # Query performance only
php artisan module:performance:analyze --type=cache      # Cache performance only
php artisan module:performance:analyze --type=resources  # Resource usage only

# Real-time monitoring
php artisan module:performance:analyze --watch --duration=120

# Export analysis results
php artisan module:performance:analyze --export=performance-report.json

# Examples:
php artisan module:performance:analyze --module=UserModule --type=queries
php artisan module:performance:analyze --watch --duration=300
```

### 🔐 Authorization Management Commands

[](#-authorization-management-commands)

#### Permission Management

[](#permission-management)

```
# List all permissions
php artisan module:permission list

# List module-specific permissions
php artisan module:permission list --module={ModuleName}

# Grant permissions to users
php artisan module:permission grant --user={email|id} --module={ModuleName} --permission={PermissionName}

# Revoke permissions from users
php artisan module:permission revoke --user={email|id} --module={ModuleName} --permission={PermissionName}

# Synchronize all module permissions
php artisan module:permission sync

# Show permission matrix
php artisan module:permission matrix
php artisan module:permission matrix --user={email|id}
php artisan module:permission matrix --export=permissions.json

# Examples:
php artisan module:permission grant --user=john@example.com --module=UserModule --permission=view-users
php artisan module:permission matrix --user=admin@example.com --export=admin-permissions.json
```

### 🗄️ Automatic Migration Generation

[](#️-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)

[](#default-behavior-automatic-migration)

```
# Creates module + migration automatically
php artisan module:make OrderModule --aggregate=Order
# ✅ Creates: modules/OrderModule/Database/Migrations/xxxx_create_orders_table.php
```

#### Opt-out (No Migration)

[](#opt-out-no-migration)

```
# Creates module only, skips migration
php artisan module:make OrderModule --aggregate=Order --no-migration
# ✅ Creates: Complete module structure without migration
```

#### Generated Migration Structure

[](#generated-migration-structure)

```
Schema::create('orders', function (Blueprint $table) {
    $table->uuid('id')->primary();
    $table->string('name');
    $table->text('description')->nullable();
    $table->timestamps();

    // Smart indexes for performance
    $table->index(['created_at']);
    $table->index(['name']);
});
```

#### Manual Migration Creation

[](#manual-migration-creation)

```
# Create additional migrations manually
php artisan module:make-migration {Module} {MigrationName} [--create={table}] [--table={table}]
```

### 🗄️ Database Operations

[](#️-database-operations)

```
# Run module migrations
php artisan module:migrate {ModuleName}
php artisan module:migrate --all

# Run module seeders
php artisan module:seed {ModuleName}
php artisan module:seed --all

# Rollback module migrations
php artisan module:migrate:rollback {ModuleName}
```

### 🏥 Health & Security Commands

[](#-health--security-commands)

#### Health Monitoring

[](#health-monitoring)

```
# Comprehensive health check
php artisan module:health {ModuleName}
php artisan module:health --all

# Check specific health aspects
php artisan module:health {ModuleName} --dependencies
php artisan module:health {ModuleName} --performance
```

#### Security Analysis

[](#security-analysis)

```
# Security vulnerability scan
php artisan module:security {ModuleName}
php artisan module:security --all

# Export security report
php artisan module:security {ModuleName} --export=security-report.json
```

### 🔧 Development Tools

[](#-development-tools)

#### Cache Management

[](#cache-management)

```
# Clear module cache
php artisan module:cache clear

# Rebuild module registry
php artisan module:cache rebuild
```

#### Development Utilities

[](#development-utilities)

```
# Watch modules for file changes
php artisan module:dev watch

# Generate dependency visualization
php artisan module:visualization

# Show module metrics
php artisan module:metrics {ModuleName}

# Generate DDD components
php artisan module:stub {ComponentType} {Name} {ModuleName}
```

💻 Usage Examples
----------------

[](#-usage-examples)

### Basic Module Creation Workflow

[](#basic-module-creation-workflow)

```
# 1. Create a complete e-commerce product module with migration
php artisan module:make ProductModule --aggregate=Product

# 2. Generate complete API with authentication and comprehensive documentation
php artisan module:make-api ProductModule Product --auth --validation --swagger --comprehensive --examples

# 3. Create additional domain components
php artisan module:make-event ProductModule ProductCreated --aggregate=Product
php artisan module:make-listener ProductModule UpdateInventory --event=ProductCreated

# 4. Generate comprehensive tests
php artisan module:make-test ProductModule ProductServiceTest --type=unit
php artisan module:make-test ProductModule ProductApiTest --type=feature
php artisan module:make-factory ProductModule Product

# 5. Create authorization policy
php artisan module:make-policy ProductModule ProductPolicy --model=Product --resource

# 6. Install and enable the module
php artisan module:install ProductModule
php artisan module:enable ProductModule

# 7. Run health checks and performance analysis
php artisan module:health ProductModule
php artisan module:performance:analyze --module=ProductModule
```

### CQRS Usage in Code

[](#cqrs-usage-in-code)

```
// Using helper functions
$command = new CreateProductCommand('iPhone 15', 999.99, 'Electronics');
$product = dispatch_command($command);

$query = new GetProductQuery($productId);
$productData = ask_query($query);

// Using facades
use TaiCrm\LaravelModularDdd\Foundation\Facades\CommandBus;
use TaiCrm\LaravelModularDdd\Foundation\Facades\QueryBus;

$product = CommandBus::dispatch(new CreateProductCommand($name, $price, $category));
$productData = QueryBus::ask(new GetProductQuery($productId));

// Using dependency injection
class ProductController extends Controller
{
    public function __construct(
        private CommandBus $commandBus,
        private QueryBus $queryBus
    ) {}

    public function store(CreateProductRequest $request)
    {
        $command = new CreateProductCommand(...$request->validated());
        $product = $this->commandBus->dispatch($command);

        return new ProductResource($product);
    }
}
```

### API Versioning Usage

[](#api-versioning-usage)

```
// Using version-aware routes in modules/YourModule/Routes/api.php
Route::prefix('api/{version}')
    ->middleware(['api', 'api.version'])
    ->where('version', 'v[1-2]')
    ->group(function () {
        Route::apiResource('users', UserController::class);
    });

// Version-specific controllers
// modules/UserModule/Http/Controllers/Api/V1/UserController.php
class UserController extends Controller
{
    public function index()
    {
        // v1 implementation
        return UserResource::collection(User::all());
    }
}

// modules/UserModule/Http/Controllers/Api/V2/UserController.php
class UserController extends Controller
{
    public function index()
    {
        // v2 implementation with enhanced features
        return UserResource::collection(
            User::with('profile', 'preferences')->get()
        );
    }
}

// Custom version transformations
use TaiCrm\LaravelModularDdd\Http\Compatibility\BaseRequestTransformer;

class UserV1ToV2RequestTransformer extends BaseRequestTransformer
{
    protected function getDescription(): string
    {
        return 'Transform user requests from v1 to v2';
    }

    public function transform(Request $request, string $fromVersion, string $toVersion): Request
    {
        $data = $request->all();

        // Transform old 'full_name' field to 'first_name' and 'last_name'
        if (isset($data['full_name'])) {
            $names = explode(' ', $data['full_name'], 2);
            $data['first_name'] = $names[0];
            $data['last_name'] = $names[1] ?? '';
            unset($data['full_name']);
        }

        return $this->cloneRequest($request)->replace($data);
    }
}

// Register transformers in a service provider
$registry = app(TransformationRegistry::class);
$registry->registerRequestTransformer('v1', 'v2', new UserV1ToV2RequestTransformer('v1', 'v2'));
```

### Authorization Usage

[](#authorization-usage)

```
// In your User model
use TaiCrm\LaravelModularDdd\Authorization\Traits\HasModulePermissions;

class User extends Authenticatable
{
    use HasModulePermissions;

    // ... your existing code
}

// Grant permissions programmatically
$user = User::find(1);
$user->grantModulePermission('ProductModule', 'view-products');
$user->grantModulePermissions('ProductModule', ['create-products', 'update-products']);

// Check permissions
if ($user->hasModulePermission('ProductModule', 'view-products')) {
    // User can view products
}

// In routes/web.php or routes/api.php
Route::middleware(['auth', 'module.permission:product-module.view-products'])
    ->get('/products', [ProductController::class, 'index']);

Route::middleware(['auth', 'module.role:product-module.admin'])
    ->delete('/products/{product}', [ProductController::class, 'destroy']);
```

### Performance Monitoring

[](#performance-monitoring)

```
// Automatic monitoring with middleware
use TaiCrm\LaravelModularDdd\Monitoring\EnhancedPerformanceMiddleware;

// Global middleware in app/Http/Kernel.php
protected $middleware = [
    EnhancedPerformanceMiddleware::class,
];

// Manual performance monitoring
use TaiCrm\LaravelModularDdd\Monitoring\QueryPerformanceAnalyzer;

$analyzer = app(QueryPerformanceAnalyzer::class);
$analyzer->startMonitoring();

// Your database operations
User::with('products')->get();

$report = $analyzer->stopMonitoring();
// Check for slow queries and N+1 issues
$slowQueries = $analyzer->getSlowQueries();
$nPlusOneQueries = $analyzer->detectNPlusOneQueries();
```

⚙️ Configuration
----------------

[](#️-configuration)

### Main Configuration (`config/modular-ddd.php`)

[](#main-configuration-configmodular-dddphp)

```