Configuration

⚙️ Configuration

Configure Laravel Arc to match your project structure and preferences. This guide covers all available configuration options.

Default Configuration

Laravel Arc comes with sensible defaults that work out of the box. The configuration file is located at src/Config/dto.php in the package.

Publishing Configuration

To customize Laravel Arc, publish the configuration file:

php artisan vendor:publish --provider="Grazulex\LaravelArc\LaravelArcServiceProvider" --tag="config"

This creates config/dto.php in your Laravel application.

Configuration Options

Core Paths

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | DTO Definition Files Path
    |--------------------------------------------------------------------------
    |
    | This is the absolute or relative path (from base_path) where your YAML
    | definition files for DTOs are located.
    |
    */
    'definitions_path' => base_path('database/dto_definitions'),

    /*
    |--------------------------------------------------------------------------
    | DTO Output Path
    |--------------------------------------------------------------------------
    |
    | The directory where the generated DTO PHP classes will be written.
    | This should typically point to app/DTO or a custom directory.
    |
    */
    'output_path' => base_path('app/DTO'),
];

Common Configuration Examples

Standard Laravel Structure

// config/dto.php
return [
    'definitions_path' => resource_path('arc'),    // resources/arc/
    'output_path' => app_path('DTOs'),             // app/DTOs/
];

Domain-Driven Design Structure

// config/dto.php
return [
    'definitions_path' => base_path('src/Definitions'), // src/Definitions/
    'output_path' => base_path('src/DTOs'),             // src/DTOs/
];

Modular Structure

// config/dto.php
return [
    'definitions_path' => base_path('modules/definitions'), // modules/definitions/
    'output_path' => base_path('modules/DTOs'),             // modules/DTOs/
];

Directory Structure Examples

Default Structure

With default configuration:

your-laravel-app/
├── database/
│   └── dto_definitions/        # YAML definitions
│       ├── user.yaml
│       ├── product.yaml
│       └── order.yaml
├── app/
│   └── DTO/                    # Generated DTOs
│       ├── UserDTO.php
│       ├── ProductDTO.php
│       └── OrderDTO.php

Recommended Structure

With customized configuration:

your-laravel-app/
├── resources/
│   └── arc/                    # YAML definitions
│       ├── users/
│       │   ├── user.yaml
│       │   └── profile.yaml
│       ├── catalog/
│       │   ├── product.yaml
│       │   └── category.yaml
│       └── orders/
│           ├── order.yaml
│           └── order-item.yaml
├── app/
│   └── DTOs/                   # Generated DTOs
│       ├── Users/
│       │   ├── UserDto.php
│       │   └── ProfileDto.php
│       ├── Catalog/
│       │   ├── ProductDto.php
│       │   └── CategoryDto.php
│       └── Orders/
│           ├── OrderDto.php
│           └── OrderItemDto.php

Environment-Specific Configuration

Development Environment

// config/dto.php
return [
    'definitions_path' => env('ARC_DEFINITIONS_PATH', resource_path('arc')),
    'output_path' => env('ARC_OUTPUT_PATH', app_path('DTOs')),
    
    // Development-specific options
    'debug_mode' => env('APP_DEBUG', false),
    'auto_generate' => env('ARC_AUTO_GENERATE', true),
];

Production Environment

// .env
ARC_DEFINITIONS_PATH=/var/www/definitions
ARC_OUTPUT_PATH=/var/www/app/DTOs
ARC_AUTO_GENERATE=false

Advanced Configuration

Namespace Mapping

Configure default namespaces for different directories:

// config/dto.php
return [
    'definitions_path' => resource_path('arc'),
    'output_path' => app_path('DTOs'),
    
    'namespace_mapping' => [
        'users' => 'App\\DTOs\\Users',
        'catalog' => 'App\\DTOs\\Catalog',
        'orders' => 'App\\DTOs\\Orders',
        'default' => 'App\\DTOs',
    ],
];

File Extensions

Configure which files to process:

// config/dto.php
return [
    'definitions_path' => resource_path('arc'),
    'output_path' => app_path('DTOs'),
    
    'file_extensions' => ['yaml', 'yml'],
    'output_extension' => 'php',
];

Generation Options

// config/dto.php
return [
    'definitions_path' => resource_path('arc'),
    'output_path' => app_path('DTOs'),
    
    'generation' => [
        'strict_types' => true,
        'readonly_properties' => true,
        'final_classes' => true,
        'add_docblocks' => true,
        'format_code' => true,
    ],
];

Working with Multiple Environments

Docker Configuration

# docker-compose.yml
services:
  app:
    volumes:
      - ./resources/arc:/var/www/resources/arc
      - ./app/DTOs:/var/www/app/DTOs
    environment:
      - ARC_DEFINITIONS_PATH=/var/www/resources/arc
      - ARC_OUTPUT_PATH=/var/www/app/DTOs

Shared Definitions

For teams sharing DTO definitions:

// config/dto.php
return [
    // Shared definitions from version control
    'definitions_path' => base_path('shared/dto-definitions'),
    
    // Local output directory
    'output_path' => app_path('DTOs'),
    
    // Version control settings
    'track_definitions' => true,
    'ignore_output' => true, // Add DTOs to .gitignore
];

Configuration Validation

Validate Paths

Ensure your configured paths exist:

# Check if definitions path exists
php artisan dto:definition-list

# Test generation to verify output path
php artisan dto:generate --dry-run

Create Missing Directories

# Create definitions directory
mkdir -p $(php -r "echo config('dto.definitions_path');")

# Create output directory
mkdir -p $(php -r "echo config('dto.output_path');")

Configuration Examples by Use Case

API-First Development

// config/dto.php - API-focused structure
return [
    'definitions_path' => resource_path('api/definitions'),
    'output_path' => app_path('Http/DTOs'),
    
    'namespace_mapping' => [
        'requests' => 'App\\Http\\DTOs\\Requests',
        'responses' => 'App\\Http\\DTOs\\Responses',
        'default' => 'App\\Http\\DTOs',
    ],
];

Directory structure:

resources/
└── api/
    └── definitions/
        ├── requests/
        │   ├── create-user-request.yaml
        │   └── update-user-request.yaml
        └── responses/
            ├── user-response.yaml
            └── user-list-response.yaml

Microservices Architecture

// config/dto.php - Service-specific DTOs
return [
    'definitions_path' => base_path('services/definitions'),
    'output_path' => base_path('services/DTOs'),
    
    'service_mapping' => [
        'user-service' => 'Services\\User\\DTOs',
        'order-service' => 'Services\\Order\\DTOs',
        'catalog-service' => 'Services\\Catalog\\DTOs',
    ],
];

Legacy Integration

// config/dto.php - Legacy system integration
return [
    'definitions_path' => base_path('legacy/dto-specs'),
    'output_path' => app_path('Legacy/DTOs'),
    
    'legacy_support' => true,
    'backward_compatibility' => true,
];

Troubleshooting Configuration

Common Issues

Permission Errors

# Fix permissions for definitions directory
chmod -R 755 $(php -r "echo config('dto.definitions_path');")

# Fix permissions for output directory
chmod -R 755 $(php -r "echo config('dto.output_path');")

Path Resolution

# Check resolved paths
php -r "
echo 'Definitions: ' . config('dto.definitions_path') . PHP_EOL;
echo 'Output: ' . config('dto.output_path') . PHP_EOL;
"

Autoloader Issues

# Dump autoloader after changing output path
composer dump-autoload

Debugging Configuration

// Temporary debugging in config/dto.php
return [
    'definitions_path' => tap(resource_path('arc'), function($path) {
        logger("DTO definitions path: {$path}");
    }),
    'output_path' => tap(app_path('DTOs'), function($path) {
        logger("DTO output path: {$path}");
    }),
];

What's Next?

Now that you understand configuration:

• Nested DTOs - Working with complex data structures
• Artisan Commands - Using commands with your configuration
• Example API Integration - Real-world usage examples

---

Proper configuration ensures Laravel Arc fits perfectly into your project structure and development workflow. ⚙️