# ⚡ Artisan Commands

Laravel Arc provides essential Artisan commands for generating and managing your DTOs. Here are the actual commands available in the package.

## Available Commands

Laravel Arc includes these core commands:

```bash
php artisan dto:generate           # Generate DTO from YAML definition
php artisan dto:definition-list    # List all YAML definitions
php artisan dto:definition-init    # Initialize/create new YAML definition
```

## Command Reference

### `dto:generate`

Generate DTOs from YAML definitions - the main command you'll use.

**Signature:**
```bash
php artisan dto:generate [filename] [options]
```

**Options:**
- `filename` - The YAML filename to generate (relative to config)
- `--force` - Overwrite existing DTO file if present
- `--output=` - Manually specify output path for generated DTO
- `--dry-run` - Output the result to console instead of saving
- `--all` - Generate all YAML files in the base path

**Examples:**
```bash
# Generate single DTO
php artisan dto:generate user.yaml

# Generate with force overwrite
php artisan dto:generate user.yaml --force

# Generate all DTOs
php artisan dto:generate --all

# Dry run (preview without creating files)
php artisan dto:generate user.yaml --dry-run

# Custom output directory
php artisan dto:generate user.yaml --output=app/DataObjects
```

**Basic Usage:**
```bash
# Create YAML file first
echo "header:
  class: UserDto
  namespace: App\DTOs

fields:
  name:
    type: string
    required: true
  email:
    type: email
    required: true" > resources/arc/user.yaml

# Generate the DTO
php artisan dto:generate user.yaml
```

**Output Example:**
```bash
php artisan dto:generate user.yaml

🛠 Generating DTO from: /path/to/resources/arc/user.yaml
✅ DTO generated successfully!
📁 Generated: App\DTOs\UserDto
📄 File: app/DTOs/UserDto.php
```

### `dto:definition-list`

List all available YAML definitions in your project.

**Signature:**
```bash
php artisan dto:definition-list [options]
```

**Options:**
- `--path=` - Directory containing DTO YAML definitions (overrides config)
- `--compact` - Display only DTO names
- `--json` - Output results as JSON

**Examples:**
```bash
# List all definitions
php artisan dto:definition-list

# List from specific directory
php artisan dto:definition-list --path=resources/custom-dtos

# Compact output (names only)
php artisan dto:definition-list --compact

# JSON output for scripting
php artisan dto:definition-list --json
```

**Example Output:**
```bash
php artisan dto:definition-list

📁 Laravel Arc - Available DTO Definitions

Found YAML definitions:
├─ user.yaml → UserDto
├─ product.yaml → ProductDto  
├─ order.yaml → OrderDto
└─ address.yaml → AddressDto

Total: 4 DTO definitions found
```

### `dto:definition-init`

Initialize or create new YAML definition files from existing models or tables.

**Signature:**
```bash
php artisan dto:definition-init name [options]
```

**Arguments:**
- `name` - The name of the DTO (e.g. UserDTO)

**Options:**
- `--model=` - Fully qualified model class (e.g. App\Models\User)
- `--table=` - Table name (e.g. users)
- `--path=` - Optional path to store the YAML file (overrides config)
- `--force` - Overwrite existing file

**Examples:**
```bash
# Create DTO from Eloquent model
php artisan dto:definition-init UserDto --model=App\\Models\\User --table=users

# Create in custom directory
php artisan dto:definition-init ProductDto --model=App\\Models\\Product --table=products --path=resources/arc/catalog

# Force overwrite existing
php artisan dto:definition-init UserDto --model=App\\Models\\User --table=users --force
```

**Interactive Creation:**
```bash
php artisan dto:definition-init UserDto --model=App\\Models\\User --table=users

Creating DTO definition: UserDto
Model: App\Models\User
Table: users

✅ Created: resources/arc/user-dto.yaml
🎯 Edit the file and run: php artisan dto:generate user-dto.yaml
```

## Real Command Examples

### Complete Workflow with Model

```bash
# 1. Create DTO definition from existing model
php artisan dto:definition-init UserDto --model=App\\Models\\User --table=users

# 2. Edit the generated YAML file to customize
# resources/arc/user-dto.yaml

# 3. Generate the DTO
php artisan dto:generate user-dto.yaml

# 4. List all definitions to verify
php artisan dto:definition-list
```

### Bulk Generation Workflow

```bash
# List all available definitions
php artisan dto:definition-list

# Generate all DTOs at once
php artisan dto:generate --all

# Or generate specific ones
php artisan dto:generate user.yaml
php artisan dto:generate product.yaml --force
php artisan dto:generate order.yaml --dry-run
```

### Development Workflow

```bash
# 1. Check what DTOs are available
php artisan dto:definition-list --compact

# 2. Preview generation without creating files
php artisan dto:generate user.yaml --dry-run

# 3. Generate and overwrite if needed
php artisan dto:generate user.yaml --force

# 4. Generate all updated DTOs
php artisan dto:generate --all --force
```

## Command Options Deep Dive

### `--dry-run` Option

Perfect for testing and debugging:
```bash
php artisan dto:generate user.yaml --dry-run

# Shows what would be generated without creating files
🛠 Generating DTO from: resources/arc/user.yaml
📋 Would generate:
   Class: App\DTOs\UserDto
   File: app/DTOs/UserDto.php
   Fields: name, email, age
   
[Generated code preview...]
```

### `--all` Option

Generate all DTOs in the definitions directory:
```bash
php artisan dto:generate --all

🛠 Generating DTO from: resources/arc/user.yaml
✅ Generated: App\DTOs\UserDto

🛠 Generating DTO from: resources/arc/product.yaml  
✅ Generated: App\DTOs\ProductDto

🛠 Generating DTO from: resources/arc/order.yaml
✅ Generated: App\DTOs\OrderDto

Summary: 3 DTOs generated successfully
```

### `--output` Option

Custom output directory:
```bash
php artisan dto:generate user.yaml --output=app/DataTransferObjects

✅ Generated: App\DataTransferObjects\UserDto
📄 File: app/DataTransferObjects/UserDto.php
```

## Integration with Development Workflow

### Basic Development Cycle

```bash
# 1. Create DTO definition from model
php artisan dto:definition-init UserDto --model=App\\Models\\User --table=users

# 2. Customize YAML (add validation, transformers, etc.)
# 3. Preview generation
php artisan dto:generate user-dto.yaml --dry-run

# 4. Generate DTO
php artisan dto:generate user-dto.yaml

# 5. Use in code
# 6. If changes needed, edit YAML and regenerate
php artisan dto:generate user-dto.yaml --force
```

### CI/CD Integration

```bash
# Generate all DTOs in deployment
php artisan dto:generate --all --force

# Check which DTOs are available
php artisan dto:definition-list --json > dto-inventory.json

# Verify specific DTO can be generated
php artisan dto:generate user.yaml --dry-run
```

## Troubleshooting Commands

### Check Available Commands

```bash
# See all DTO commands
php artisan list | grep dto

# Get help for specific commands
php artisan dto:generate --help
php artisan dto:definition-list --help
php artisan dto:definition-init --help
```

### Common Issues and Solutions

```bash
# If YAML file not found
php artisan dto:definition-list  # Check available files

# If generation fails
php artisan dto:generate user.yaml --dry-run  # Test without creating files

# If output directory doesn't exist
php artisan dto:generate user.yaml --output=app/DTOs  # Specify output

# Clear cache if commands don't appear
php artisan cache:clear
php artisan config:clear
```

### Debugging with Verbose Output

```bash
# Get detailed generation information
php artisan dto:generate user.yaml --dry-run -v

# Shows ModelSchema integration details
🔧 ModelSchema: full_delegation - delegated_to_modelschema
📍 Fields processed: 5
⚡ Status: coordinator_role
```

## Command Configuration

Commands use configuration from `config/arc.php`:

```php
// config/arc.php
return [
    'default_namespace' => 'App\\DTOs',
    'output_path' => app_path('DTOs'),
    'definitions_path' => resource_path('arc'),
];
```

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

## Script Integration

### Bash Scripts

```bash
#!/bin/bash
# regenerate-dtos.sh

echo "🚀 Regenerating all DTOs..."

# List current DTOs
echo "📋 Current DTOs:"
php artisan dto:definition-list --compact

# Generate all
php artisan dto:generate --all --force

echo "✅ All DTOs regenerated!"
```

### JSON Processing

```bash
# Get DTO list as JSON for processing
DTOS=$(php artisan dto:definition-list --json)
echo $DTOS | jq '.[] | .name'

# Generate specific DTOs from JSON list
echo $DTOS | jq -r '.[] | .file' | xargs -I {} php artisan dto:generate {} --force
```

## What's Next?

Now that you know the real commands:

- **[Your First DTO](Your-First-DTO.md)** - Create your first DTO using these commands
- **[Understanding YAML Structure](Understanding-YAML-Structure.md)** - Learn what to put in your YAML files
- **[Configuration](Configuration.md)** - Customize command behavior
- **[Example API Integration](Example-API-Integration.md)** - See commands in real-world usage

---

*These are the actual commands available in Laravel Arc. Simple, focused, and powerful for DTO generation from models and custom definitions.* ⚡