Artisan Commands

⚡ 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:

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:

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:

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

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

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:

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:

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

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:

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:

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

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

# 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

# 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

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

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:

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:

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

# 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

# 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

# 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

# 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

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

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

Publish config to customize:

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

Script Integration

Bash Scripts

#!/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

# 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 - Create your first DTO using these commands
• Understanding YAML Structure - Learn what to put in your YAML files
• Configuration - Customize command behavior
• Example API Integration - 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. ⚡