# 📦 Installation & Setup

Get Laravel Arc up and running in your Laravel application in just a few minutes.

## Requirements

- **PHP**: 8.3 or higher
- **Laravel**: 10.x or 11.x
- **Composer**: Latest version recommended

## Installation

### 1. Install via Composer

```bash
composer require grazulex/laravel-arc
```

### 2. Publish Configuration (Optional)

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

This creates `config/arc.php` with default settings.

### 3. Create DTO Directory Structure

Laravel Arc follows Laravel conventions. Create your YAML definitions in:

```
resources/
└── arc/
    ├── user.yaml
    ├── product.yaml
    └── nested/
        └── address.yaml
```

## Basic Configuration

The default configuration works out of the box, but you can customize it in `config/arc.php`:

```php
<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Default DTO Namespace
    |--------------------------------------------------------------------------
    | The default namespace for generated DTOs when not specified in YAML
    */
    'default_namespace' => 'App\\DTOs',

    /*
    |--------------------------------------------------------------------------
    | Default Output Directory
    |--------------------------------------------------------------------------
    | Where generated DTO files will be saved
    */
    'output_path' => app_path('DTOs'),

    /*
    |--------------------------------------------------------------------------
    | YAML Definitions Path
    |--------------------------------------------------------------------------
    | Default location for YAML definition files
    */
    'definitions_path' => resource_path('arc'),

    /*
    |--------------------------------------------------------------------------
    | Field Transformers
    |--------------------------------------------------------------------------
    | Enable automatic field transformation
    */
    'enable_transformers' => true,

    /*
    |--------------------------------------------------------------------------
    | Validation Integration
    |--------------------------------------------------------------------------
    | Auto-generate Laravel validation rules
    */
    'auto_validation' => true,
];
```

## Verification

Verify your installation by running:

```bash
php artisan arc:list
```

You should see available Arc commands:

```
Available commands:
  arc:generate    Generate DTO from YAML definition
  arc:list        List all available YAML definitions
  arc:validate    Validate YAML definition syntax
```

## Directory Structure After Setup

After installation, your project structure should look like:

```
your-laravel-app/
├── app/
│   └── DTOs/                 # Generated DTO classes (auto-created)
├── config/
│   └── arc.php              # Configuration file (optional)
├── resources/
│   └── arc/                 # YAML definitions directory
└── vendor/
    └── grazulex/laravel-arc/ # Package files
```

## Quick Test

Create a simple test to verify everything works:

### 1. Create Test YAML

```bash
mkdir -p resources/arc
```

Create `resources/arc/test.yaml`:

```yaml
header:
  class: TestDto
  namespace: App\DTOs

fields:
  message:
    type: string
    required: true
```

### 2. Generate DTO

```bash
php artisan arc:generate resources/arc/test.yaml
```

### 3. Use in Code

```php
use App\DTOs\TestDto;

$dto = TestDto::from(['message' => 'Hello Laravel Arc!']);
echo $dto->message; // "Hello Laravel Arc!"
```

## Common Issues & Solutions

### Permission Issues

If you encounter permission errors:

```bash
sudo chown -R $USER:$USER app/DTOs
chmod -R 755 app/DTOs
```

### Namespace Issues

Ensure your `composer.json` has the correct PSR-4 autoloading:

```json
{
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            "App\\DTOs\\": "app/DTOs/"
        }
    }
}
```

Run `composer dump-autoload` after changes.

### Class Not Found

If generated classes aren't found:

1. Check the namespace in your YAML matches your autoloader
2. Run `composer dump-autoload`
3. Clear Laravel cache: `php artisan cache:clear`

## What's Next?

✅ **Installation Complete!** 

Now you're ready to:
- **[Create Your First DTO](Your-First-DTO.md)** - Build your first DTO in 5 minutes
- **[Understand YAML Structure](Understanding-YAML-Structure.md)** - Learn the schema basics
- **[Explore Field Types](Field-Types.md)** - See all available field types

---

*Need help? Check the [troubleshooting guide](#common-issues--solutions) above or refer to our [examples](Example-API-Integration.md).*