Artisan Commands

Artisan Commands

Complete reference for all Artisan commands provided by Laravel ApiRoute.

---

Overview

Command	Description
api:status	Display status of all API versions
api:version	Scaffold a new API version
api:deprecate	Mark a version as deprecated
api:sunset	Mark a version as sunset
api:stats	Display usage statistics

---

api:status

Display the status of all registered API versions.

Basic Usage

php artisan api:status

Output

┌─────────┬────────────┬──────────────┬──────────────┬────────────┐
│ Version │ Status     │ Deprecated   │ Sunset       │ Usage (30d)│
├─────────┼────────────┼──────────────┼──────────────┼────────────┤
│ v3      │ beta       │ -            │ -            │ 2.1%       │
│ v2      │ active     │ -            │ -            │ 78.4%      │
│ v1      │ deprecated │ 2025-06-01   │ 2025-12-01   │ 19.5%      │
└─────────┴────────────┴──────────────┴──────────────┴────────────┘

Warning: v1 will be sunset in 180 days (2025-12-01)

Options

Option	Description
--api-version=v1	Show details for a specific version
--json	Output as JSON
--routes	Include route list

Examples

# Show details for specific version
php artisan api:status --api-version=v1

# Output as JSON (for scripts)
php artisan api:status --json

# Include routes
php artisan api:status --routes

Version Details Output

php artisan api:status --api-version=v1

┌─────────────────┬─────────────────────────────────────────┐
│ Property        │ Value                                   │
├─────────────────┼─────────────────────────────────────────┤
│ Name            │ v1                                      │
│ Status          │ deprecated                              │
│ Deprecated      │ 2025-06-01                              │
│ Sunset          │ 2025-12-01                              │
│ Successor       │ v2                                      │
│ Documentation   │ https://docs.example.com/api/v1         │
│ Rate Limit      │ 100/min                                 │
│ Requests (30d)  │ 45,678                                  │
└─────────────────┴─────────────────────────────────────────┘

---

api:version

Scaffold a new API version with controller structure.

Basic Usage

php artisan api:version v3

Output

Created: V3/Controller.php

API version V3 scaffolded successfully!

Next steps:
  1. Add your routes to routes/api.php using ApiRoute::version('v3', ...)
  2. Create your controllers in app/Http/Controllers/Api/V3/

Options

Option	Description
--copy-from=v2	Copy controllers from another version
--controllers=User,Post	Only copy specific controllers
--force	Overwrite existing files

Examples

# Create empty version
php artisan api:version v3

# Copy all controllers from v2
php artisan api:version v3 --copy-from=v2

# Copy only specific controllers
php artisan api:version v3 --copy-from=v2 --controllers=User,Post

# Overwrite existing version
php artisan api:version v3 --copy-from=v2 --force

Generated Structure

app/Http/Controllers/Api/
├── V2/
│   ├── Controller.php
│   ├── UserController.php
│   └── PostController.php
└── V3/
    ├── Controller.php       (new)
    ├── UserController.php   (copied from V2, namespace updated)
    └── PostController.php   (copied from V2, namespace updated)

Custom Stubs

Create custom stubs in stubs/apiroute/:

// stubs/apiroute/controller.stub
<?php

declare(strict_types=1);

namespace {{ namespace }};

use App\Http\Controllers\Controller as BaseController;

abstract class Controller extends BaseController
{
    // Custom base controller code
}

---

api:deprecate

Mark an API version as deprecated.

Basic Usage

php artisan api:deprecate v1 --on=2025-06-01

Options

Option	Description
--on=2025-06-01	Deprecation date
--sunset=2025-12-01	Sunset date
--successor=v2	Successor version
--notify	Send notifications

Examples

# Simple deprecation
php artisan api:deprecate v1 --on=2025-06-01

# With sunset date
php artisan api:deprecate v1 --on=2025-06-01 --sunset=2025-12-01

# With successor
php artisan api:deprecate v1 --on=2025-06-01 --sunset=2025-12-01 --successor=v2

# With notification
php artisan api:deprecate v1 --on=2025-06-01 --notify

---

api:sunset

Mark an API version as sunset (end-of-life).

Basic Usage

php artisan api:sunset v1

Options

Option	Description
--remove-routes	Remove routes from configuration
--archive	Archive controllers

Examples

# Mark as sunset
php artisan api:sunset v1

# Remove routes
php artisan api:sunset v1 --remove-routes

# Archive controllers
php artisan api:sunset v1 --archive

---

api:stats

Display API version usage statistics.

Basic Usage

php artisan api:stats

Output

API Version Usage Statistics (Last 30 days)

Total Requests: 1,234,567

┌──────────────────────┬────────────┬────────────┬──────────┬────────┐
│ Version              │ Requests   │ Percentage │ Success  │ Errors │
├──────────────────────┼────────────┼────────────┼──────────┼────────┤
│ v2                   │ 967,901    │ 78.4%      │ 960,123  │ 7,778  │
│ v1 (deprecated)      │ 240,741    │ 19.5%      │ 238,456  │ 2,285  │
│ v3                   │ 25,925     │ 2.1%       │ 25,800   │ 125    │
└──────────────────────┴────────────┴────────────┴──────────┴────────┘

Warning: 19.5% of traffic still uses deprecated version v1

Options

Option	Description
--period=30	Number of days to analyze (default: 30)
--api-version=v1	Show stats for specific version
--json	Output as JSON

Examples

# Last 30 days (default)
php artisan api:stats

# Last 7 days
php artisan api:stats --period=7

# Specific version
php artisan api:stats --api-version=v1

# JSON output
php artisan api:stats --json

Version-Specific Output

php artisan api:stats --api-version=v1 --period=7

Statistics for version v1 (Last 7 days)

┌─────────────────────┬───────────┐
│ Metric              │ Value     │
├─────────────────────┼───────────┤
│ Total Requests      │ 56,789    │
│ Successful Requests │ 56,234    │
│ Failed Requests     │ 555       │
│ Success Rate        │ 99.0%     │
└─────────────────────┴───────────┘

---

Scheduling Commands

Add commands to your scheduler for regular monitoring:

// app/Console/Kernel.php
protected function schedule(Schedule $schedule): void
{
    // Daily status report
    $schedule->command('api:status --json')
        ->daily()
        ->sendOutputTo(storage_path('logs/api-status.json'));

    // Weekly usage stats
    $schedule->command('api:stats --period=7 --json')
        ->weekly()
        ->sendOutputTo(storage_path('logs/api-stats.json'));
}

---

Command Output Formats

All commands support JSON output for scripting:

# Pipe to jq for processing
php artisan api:status --json | jq '.[] | select(.status == "deprecated")'

# Save to file
php artisan api:stats --json > api-stats.json

---

Next Steps

• Usage Tracking - Set up tracking for stats
• Version Lifecycle - Manage version transitions
• Configuration - Configure commands behavior