Artisan Commands

The starter includes several custom Artisan commands for managing your application’s database, configuration, and Northwestern integrations.

Database Commands

db:rebuild

Completely rebuild the database by dropping all tables, running migrations, and executing all auto-discovered seeders.

php artisan db:rebuild

What it does:

1. Drops all tables, views, and types
2. Runs all migrations
3. Executes all seeders marked with #[AutoSeed] attribute
4. Regenerates IDE helper files

Destructive Operation

This command will completely wipe your database. Only use in local and testing environments. Never run this in production.

When to use:

• Initial project setup
• After pulling schema changes from git
• When switching between feature branches with different schemas
• Resetting test data during development

Related: db:wipe, migrate:fresh, db:seed

---

db:seed:list

Display all auto-discovered seeders with their dependencies and execution order.

php artisan db:seed:list

Output example:

 ┌───┬──────────────────┬──────────────────────────────────┐
 │ # │ Seeder           │ Dependencies                     │
 ├───┼──────────────────┼──────────────────────────────────┤
 │ 1 │ PermissionSeeder │ none                             │
 │ 2 │ RoleTypeSeeder   │ none                             │
 │ 3 │ RoleSeeder       │ RoleTypeSeeder, PermissionSeeder │
 └───┴──────────────────┴──────────────────────────────────┘

When to use:

• Verify seeder discovery and dependencies
• Troubleshoot seeding order issues
• Document available seeders for your team

See also: Idempotent Seeding documentation

---

db:snapshot:create {name}

Create a snapshot of the current database state.

php artisan db:snapshot:create my-snapshot-name

Options:

• {name} - (optional) Descriptive name for the snapshot. Defaults to database-dump if omitted.
• --skip-schema-validation - Skip schema validation checks

What it does:

1. Validates database schema matches current migrations (unless skipped)
2. Dumps database to database/snapshots/{name}.sql
3. Stores metadata about the snapshot (checksum, timestamp, migration/seeder counts)

Tip

Use descriptive snapshot names like clean-test-data or before-feature-x to make them easier to identify later.

When to use:

• Before making risky database changes
• Saving a known-good state for testing
• Creating test data fixtures
• Preserving demo data

See also: Database Snapshots documentation

---

db:snapshot:restore {name}

Restore a previously created database snapshot.

php artisan db:snapshot:restore my-snapshot-name

Options:

• {name} - (optional) Name of the snapshot to restore. Defaults to database-dump if omitted.
• --skip-schema-validation - Skip schema validation checks
• --backup - Create a backup of the current database before restoring

What it does:

1. Validates snapshot exists
2. Checks schema compatibility (unless skipped)
3. Creates a backup if requested
4. Drops all current database tables
5. Restores data from snapshot SQL file

Destructive Operation

Restoring a snapshot will completely replace your current database. All current data will be lost.

When to use:

• Resetting to a known state during testing
• Recovering from bad data changes during development
• Switching between test scenarios

---

db:snapshot:list

List all available database snapshots.

php artisan db:snapshot:list

---

db:snapshot:info {name}

Display detailed information about a specific snapshot.

php artisan db:snapshot:info my-snapshot-name

Options:

• {name} - (optional) Name of the snapshot to inspect. If omitted, an interactive selector is shown.

What it does:

1. Displays file information (path, size, modification date)
2. Shows schema metadata (checksum, migration/seeder counts)
3. Compares snapshot schema with current codebase

When to use:

• Verifying a snapshot’s contents before restoring
• Checking if a snapshot is compatible with current code
• Reviewing snapshot metadata

---

db:snapshot:delete {name}

Delete a database snapshot and its associated metadata.

php artisan db:snapshot:delete my-snapshot-name

Options:

• {name} - (optional) Name of the snapshot to delete. If omitted, an interactive selector is shown.
• --all - Delete all snapshots

What it does:

1. Removes the SQL snapshot file from database/snapshots/
2. Cleans up associated metadata from the checksum map

When to use:

• Removing old or unused snapshots
• Freeing up disk space
• Cleaning up after testing

---

db:wake

Wake up a potentially-inactive serverless RDS database by establishing a connection.

php artisan db:wake

What it does:

Attempts to connect to the database and execute a simple query, causing serverless databases (like AWS Aurora Serverless) to wake from sleep mode.

When to use:

• Before running migrations
• As part of deployment scripts
• When you know the database has been idle

Note

This is primarily useful for AWS Aurora Serverless or similar serverless database configurations that automatically pause after periods of inactivity.

---

Configuration Commands

config:validate

Validate application configuration and environment variables.

php artisan config:validate

What it does:

Runs all auto-discovered config validators and reports their status. Built-in validators check:

• Application key
• SSO credentials (Entra ID or Online Passport)
• Directory Search API key
• Database connectivity
• Queue connection
• S3 storage access
• EventHub credentials (when not mocked)

Validators that aren’t relevant to the current configuration (e.g., EventHub when mocked) are automatically skipped and shown separately in the output.

When to use:

• After initial installation
• After environment variable changes
• Before deployment
• Troubleshooting integration issues

Adding Custom Validators

Validators are discovered automatically using the #[StarterValidator] attribute, following the same pattern as #[AutoSeed] for seeders.

1. Create a validator class implementing ConfigValidator in a Services/ConfigValidation directory within your domain:

<?php

namespace App\Domains\Billing\Services\ConfigValidation;

use App\Domains\Core\Attributes\StarterValidator;
use App\Domains\Core\Contracts\ConfigValidator;

#[StarterValidator(description: 'Stripe')]
class StripeValidator implements ConfigValidator
{
    public function shouldRun(): bool
    {
        // Return false to skip when the integration isn't configured
        return filled(config('services.stripe.secret'));
    }

    public function validate(): bool
    {
        return filled(config('services.stripe.secret'))
            && filled(config('services.stripe.key'));
    }

    public function successMessage(): string
    {
        return 'Stripe API keys are configured';
    }

    public function errorMessage(): string
    {
        return 'Stripe configuration is incomplete';
    }

    public function hints(): array
    {
        return [
            'Set <comment>STRIPE_KEY</comment> and <comment>STRIPE_SECRET</comment> in your .env file',
        ];
    }
}

2. That’s it. The validator is automatically discovered from any app/Domains/*/Services/ConfigValidation directory. No registration or configuration needed.

Tip

The description parameter on #[StarterValidator] controls the label shown in the command output. The shouldRun() method determines whether the validator is relevant — return false for optional integrations that aren’t configured to avoid false negatives.

---

Maintenance Commands

access-tokens:notify-expiration

Send expiration reminder emails for access tokens approaching their expiration date.

php artisan access-tokens:notify-expiration

What it does:

1. Queries for active access tokens with upcoming expiration dates
2. Checks which tokens are due for notifications (30, 14, 7, 3, 1 days before)
3. Sends reminder emails to token owners

See also: API Documentation

---

Health Check Commands

health:check

Run health checks for all external integrations and services.

php artisan health:check

What it does:

Validates connectivity and configuration for:

• Database - Connection and query execution (production only)
• Queue - Queue worker connectivity
• Cache - Cache store read/write
• Schedule - Scheduler heartbeat
• Debug Mode - Ensures debug mode is off (non-local)
• Optimized App - Ensures app is optimized (non-local)
• Security Advisories - Checks for known package vulnerabilities
• Directory Search - API connectivity and test query

When to use:

• After deployment
• Troubleshooting integration issues
• Monitoring service connectivity
• As part of CI/CD pipelines

Integration:

The /api/health endpoint also runs these checks for automated monitoring:

curl https://your-app.northwestern.edu/api/health

---

Starter Commands

starter:check

Check for newer releases of the Northwestern Laravel Starter.

php artisan starter:check

What it does:

1. Reads the current version from .starter-version.yaml
2. Queries the GitHub Releases API for newer versions
3. Displays release notes and a compare URL for any available updates

Options:

• --version-file - Path to .starter-version.yaml (defaults to project root)

This command runs automatically via composer install and composer update in local environments. Results are cached for 4 hours to avoid unnecessary API calls.

---

Changelog Commands

make:changelog

Scaffold a new changelog Markdown file in resources/changelogs/.

php artisan make:changelog

In interactive mode, the command prompts for a slug, date, and title with sensible defaults. Arguments and options can also be passed directly:

php artisan make:changelog 2026-03-01 --date=2026-03-01 --title="Search Improvements"

Options:

• {slug} - (optional) URL-safe identifier. Defaults to today’s date.
• --date - Authored date in YYYY-MM-DD format. Defaults to today.
• --title - Human-readable title. Defaults to “Month Year Release” when the slug is a date.

If a file with the same slug already exists, a numeric suffix is appended automatically.

See also: Changelog documentation

---

IDE Helper Commands

The starter uses laravel-ide-helper to generate IDE autocomplete files. These commands are automatically run after db:rebuild:

ide-helper:generate

Generate IDE helper file for Laravel facades.

php artisan ide-helper:generate

ide-helper:models

Generate PHPDoc annotations for Eloquent models.

php artisan ide-helper:models --write --reset

ide-helper:meta

Generate PhpStorm meta file for container bindings.

php artisan ide-helper:meta

Tip

These commands are automatically executed as part of db:rebuild. You rarely need to run them manually unless you’re specifically updating IDE helpers.