# ⚙️ 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:

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

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

## Configuration Options

### Core Paths

```php
<?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

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

#### Domain-Driven Design Structure

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

#### Modular Structure

```php
// 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

```php
// 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

```php
// .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:

```php
// 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:

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

### Generation Options

```php
// 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

```yaml
# 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:

```php
// 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:

```bash
# 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

```bash
# 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

```php
// 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

```php
// 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

```php
// 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

```bash
# 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

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

#### Autoloader Issues

```bash
# Dump autoloader after changing output path
composer dump-autoload
```

### Debugging Configuration

```php
// 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](Nested-DTOs.md)** - Working with complex data structures
- **[Artisan Commands](Artisan-Commands.md)** - Using commands with your configuration
- **[Example API Integration](Example-API-Integration.md)** - Real-world usage examples

---

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