Search by

masgeek / artisan-toolkit

masgeek

A collection of custom and override Artisan commands for Laravel. Enable only what you need via a published config.

Package info

github.com/masgeek/artisan-toolkit

pkg:composer/masgeek/artisan-toolkit

Statistics

Installs: 802

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 2

3.0.0 2026-10-09 09:39 UTC

This package is auto-updated.

Last update: 2026-11-16 13:10:29 UTC


README

Opinionated Artisan commands for Laravel applications — scaffolding generators, model tooling, and safe replacements for two built-in commands.

Every command is opt-out. Nothing replaces a built-in unless you enable it in the published config.

  • PHP 8.2+
  • Laravel 11, 12, 13

Table of contents

Installation

composer require masgeek/artisan-toolkit

Publish the config file:

php artisan vendor:publish --tag=artisan-toolkit-config

This creates config/artisan-toolkit.php. Publishing is optional: without a published file the shipped defaults are used, and every command is registered with default settings.

Verify the install:

php artisan app:status

How configuration works

The service provider merges the package defaults with your published config rather than letting the published file replace them wholesale:

// ArtisanToolkitServiceProvider
$defaults  = ['overrides' => [...], 'commands' => [...]];
$overrides = array_merge($defaults['overrides'], config('artisan-toolkit.overrides', []));
$commands  = array_merge($defaults['commands'], config('artisan-toolkit.commands', []));

Three consequences worth knowing:

  1. New commands appear automatically. Install a version that ships make:dto and it works immediately — you do not need to re-publish the config or add the entry by hand.
  2. Your false wins. Set any entry to false to disable it, and it stays disabled across upgrades.
  3. Your class replacements win. Pointing schema:dump at your own subclass overrides the package default.

Run php artisan config:diff at any time to see exactly which settings deviate from the shipped defaults.

Command reference

Overrides

These replace built-in Laravel commands. Disable any of them by setting the value to false.

schema:dump

Dumps the database schema. The override changes what --prune does: Laravel's built-in deletes every file in database/migrations, which destroys pending migrations. This version only deletes migration files already recorded in the migrations table.

php artisan schema:dump --prune
2024_01_01_000000_create_users_table.php .............. deleted
2026_05_07_085600_rename_playground_role.php .......... kept (pending)
Database schema dumped and pruned (1 deleted, 1 pending kept) successfully.
Option Description
--database= Connection to dump
--path= Where the dump file is written
--prune Delete only already-run migration files
--no-schema Force a schema-agnostic dump for this run, overriding schema_dump_include_schema
--without-migration-data Omit migration data from the dump

The command uses Laravel's Prohibitable trait: call SchemaDumpCommand::prohibit() (for example from a service provider when running in production) to block it.

By default the dump keeps the schema qualifier (public. for PostgreSQL, dbo. for SQL Server) on every identifier. Set schema_dump_include_schema to false to strip it, producing a schema-agnostic dump you can load into any schema. This also removes the statements that bind the dump to a named schema: CREATE SCHEMA ...; and search_path pinning such as SET search_path = ...; or SELECT pg_catalog.set_config('search_path', '', false);.

'schema_dump_include_schema' => false,

key:generate

Rotates APP_KEY and re-encrypts every attribute listed in encrypted_models.

⚠️ Dry run by default. This command only writes when you pass --apply. Without it you get a preview of what would change and nothing is modified.

php artisan key:generate                    # dry run — reports what would happen
php artisan key:generate --apply            # actually rotate and re-encrypt
php artisan key:generate --reverse --apply  # roll back the last rotation
Option Description
--apply Execute the rotation. Without this the command is a dry run.
--new Fresh setup. Generates a key, skips rotation and re-encryption entirely.
--show Print a generated key without touching any files.
--force Skip the confirmation prompt and allow running in production.
--no-env-file Skip .env writes; prints values for manual injection (Docker).
--reverse Roll back using stored previous keys.
--steps=N How many rotations to roll back. Default 1. Requires --reverse.

How a rotation proceeds:

  1. A new key is generated.
  2. The old key is pushed to the front of APP_PREVIOUS_KEYS in .env.
  3. Every attribute in encrypted_models is decrypted with the old key and re-encrypted with the new one, in database transactions, with a progress bar.
  4. If key_storage_path is set, keys are also written to that JSON file.

The command exits early with a failure if encrypted_models is empty or if none of the configured models are valid. This prevents rotating a key without re-encrypting the data it protects.

--reverse walks back through N previous keys, re-encrypting data forward into each one in sequence. It fails if fewer previous keys exist than the requested --steps.

encrypted_models

Maps models to the attributes using Laravel's encrypted cast:

'encrypted_models' => [
    \App\Models\ApiCredential::class => ['api_key', 'api_secret'],
    \App\Models\User::class           => ['two_factor_secret'],
],

Every model listed must exist and declare at least one field. Models that fail are skipped with a warning; if all fail, the command aborts rather than rotating unsafely.

key_storage_path

Writes current and previous keys to a JSON file after each rotation, for Docker sidecars that need keys without reading .env.

'key_storage_path' => env('KEY_STORAGE_PATH', storage_path('app/keys/app-keys.json')),
KEY_STORAGE_PATH=/run/secrets/app-keys.json   # Docker secret mount
KEY_STORAGE_PATH=null                         # disable
{
    "current_key": "base64:...",
    "previous_keys": ["base64:...", "base64:..."],
    "updated_at": "2026-07-23T12:00:00+00:00"
}

🔐 This file stores encryption keys in plain text. Restrict it to 0600, never commit it, and prefer a tmpfs mount or Docker secrets over writing to disk.

Scaffolding

All generators write to the directories configured under paths.

make:enum

Generates a PHP enum. If the name is omitted you are prompted for it.

php artisan make:enum Status
php artisan make:enum UserRole --backed=string --cases=Admin,Partner,User
php artisan make:enum Billing/InvoiceStatus --backed=int --cases=Draft,Pending,Paid,Void
Option Description
--backed= string or int. Omit for a pure enum.
--cases= Comma-separated case names.
--table= Generate cases from the distinct values of a DB column, e.g. users.role.
--force Overwrite an existing file.
--dry-run Show the file that would be created without writing it.

--table requires the value to already exist in the database:

php artisan make:enum UserRole --backed=string --table=users.role
<?php

namespace App\Enums;

enum UserRole: string
{
    case Admin = 'admin';
    case Partner = 'partner';
}

Slash-separated names become sub-namespaces: Billing/InvoiceStatus → app/Enums/Billing/InvoiceStatus.php.

make:api-scaffold

Generates a complete API slice in one pass: controller, repository, resource, resource collection, and a form request. Prompts for the name if omitted.

php artisan make:api-scaffold Currency
php artisan make:api-scaffold Currency --model=MyCurrency
php artisan make:api-scaffold Currency --prefix=my-currencies
php artisan make:api-scaffold Currency --no-route
php artisan make:api-scaffold Currency --force
php artisan make:api-scaffold Currency --with-tests --with-factory
Option Description
--model= Model class name. Defaults to the name argument.
--prefix= URL prefix. Defaults to the kebab-case plural of the name.
--force Overwrite existing files.
--with-routes Register the index route. This is the default; use --no-route to skip.
--with-tests Also generate a feature test for the index endpoint in paths.tests.
--with-factory Also generate a model factory in paths.factories.
--no-route Skip route registration.

Files created:

File Purpose
Http/Controllers/Api/{Name}Controller.php Controller using a HasPaginationParams trait
Repositories/{Name}Repo.php Repository extending base_classes.repository
Http/Resources/{Name}Resource.php Resource with fields read from the model's table
Http/Resources/Collections/{Name}ResourceCollection.php Resource collection
Http/Requests/{Name}Request.php Form request with rules inferred from the model's columns
{paths.tests}/Api/{Name}ControllerTest.php Index-endpoint feature test (--with-tests)
{paths.factories}/{Model}Factory.php Model factory stub (--with-factory)

The controller is generated with a ready index() endpoint using paginateWithSort(), and the resource's toArray() is pre-filled from the real database columns, with date-cast and timestamp columns routed through formatDate().

Route registration. Unless --no-route is passed, a GET /{api_version}/{prefix} route is written into routes/api.php:

  • If the file contains the // Mutating anchor, the route is inserted just above it.
  • Otherwise it is appended to the end of the file, which is correct for standard Laravel 11+ files.
  • If routes/api.php does not exist you are told to run php artisan install:api.
  • Duplicate prefixes are detected and skipped.

make:repo

Generates a repository class extending base_classes.repository. The generated class defines a model() method returning the bound model.

php artisan make:repo UserRepo
php artisan make:repo PostRepo --model=Post
Option Description
--model= Model the repository is bound to.
--force Overwrite an existing repository.
--with-interface Also generate {Name}Interface in paths.repository_interfaces and implement it.
--dry-run Show the files that would be created without writing them.

make:resource-full

Generates a resource and its collection, inferring the model from a *Resource name when --model is omitted.

php artisan make:resource-full UserResource
php artisan make:resource-full UserResource --model=User
php artisan make:resource-full UserResource --model=User --with-relationships
Option Description
--model= Model to inspect. Inferred from the name when omitted.
--force Overwrite existing resources.
--with-relationships Detect relations, add them to toArray(), and generate the related resources.

make:dto

Generates a data transfer object. With --model, one typed public readonly property is created per column in the model's table.

php artisan make:dto UserData
php artisan make:dto UserData --model=User
php artisan make:dto UserData --from-request=App\Http\Requests\StoreUserRequest
Option Description
--model= Model whose table columns become DTO properties. Types and nullability come from the schema.
--from-request= FormRequest class; one typed property is derived from each validation rule.
--force Overwrite an existing DTO.
--dry-run Show the file that would be created without writing it.

make:request

Generates a form request. With --model, validation rules are inferred from the model's columns, skipping the primary key, timestamps and soft-delete columns.

php artisan make:request StoreUserRequest
php artisan make:request StoreUserRequest --model=User
Option Description
--model= Model whose columns drive the inferred rules.
--force Overwrite an existing request.
--dry-run Show the file that would be created without writing it.

make:service

Generates an empty service class.

php artisan make:service Billing
Option Description
--force Overwrite an existing service.
--dry-run Show the file that would be created without writing it.

make:api-endpoint

Appends a single method to an existing controller and generates the matching form request.

php artisan make:api-endpoint Currency store
php artisan make:api-endpoint Currency update --model=MyCurrency
Argument Description
name Base name; the controller must already exist
method Method to add, e.g. store, update

Fails with a helpful message if the controller has not been scaffolded yet.

Model tooling

model:relations

Lists a model's relationships as a table, including those inherited from a base model in App\Models\Base.

php artisan model:relations "App\Models\User"
php artisan model:relations "App\Models\User" --depth=2
php artisan model:relations "App\Models\User" --json
┌────────────┬────────────┬──────────────┬─────────┬───────┐
│ Method     │ Type       │ Target Model │ Inverse │ Pivot │
├────────────┼────────────┼──────────────┼─────────┼───────┤
│ posts      │ HasMany    │ Post         │ user    │ —     │
│ profile    │ HasOne     │ Profile      │ user    │ —     │
└────────────┴────────────┴──────────────┴─────────┴───────┘
Option Description
--depth= Recurse into related models up to this depth (default 1). Deeper rows show a Path column such as posts.comments.
--json Emit results as JSON, including path, target, inverse, pivot and depth.

Inverse is the relation method on the related model that points back (when one exists). Pivot lists belongsToMany pivot columns declared with withPivot().

model:analyze

Shows a model's table columns alongside their Laravel casts. Accepts a fully qualified class name, a short name, or even a table name.

php artisan model:analyze "App\Models\User"
php artisan model:analyze User
php artisan model:analyze users        # infers App\Models\User

Resolution order: exact class → model_base_namespace + studly name → each entry in paths.model_scan → singularized/studly name in model_base_namespace.

model:prune-orphaned

Finds models with no backing table and no references anywhere in the codebase. Lists by default; deletes only with --delete.

php artisan model:prune-orphaned
php artisan model:prune-orphaned --path=app/Models --path=app/Domain/Models
php artisan model:prune-orphaned --delete
php artisan model:prune-orphaned --delete --force
Option Description
--path=* Directories to scan. Defaults to paths.model_scan.
--search= Root directory for reference scanning. Defaults to prune_search_root.
--delete Delete the files that are found.
--force Skip the confirmation prompt.

References are matched across .php, .blade.php, and .json files, so a model referenced only from a Blade view or a JSON config is correctly treated as used. Use -v to print per-model reasoning.

model:fillable-audit

Compares a model's $fillable and $casts arrays against the actual database schema, reporting mismatches and missing cast suggestions.

php artisan model:fillable-audit
php artisan model:fillable-audit --model=User --model=Post
php artisan model:fillable-audit --json                     # JSON output for CI
php artisan model:fillable-audit --fail                     # non‑zero exit when missing attributes or casts are found
Option Description
--model=* Limit to the given model classes (FQCN or short name).
--json Emit JSON containing issues with kind, attribute, detail and severity.
--fail Exit non‑zero when any error‑severity issue (missing columns or casts) is found.

The command flags:

  • missing-fillable – $fillable entries that do not exist in the table.
  • missing-cast – $casts entries that do not exist.
  • unfillable – Table columns not listed in $fillable (ignoring primary key, timestamps, soft‑deletes).
  • uncast – Columns that have a type that Laravel can cast but lack an explicit cast entry (suggested cast shown).
Option Description
--model=* Limit to specific models (FQCN or short name).
--search= Root directory to scan. Defaults to prune_search_root.
--exclude=* Extra columns to treat as always-used.
--include-timestamps Also report timestamp columns instead of skipping them.
--fix Generate a migration that drops the reported columns.
--apply With --fix, actually write the migration file (dry run otherwise).
--json Emit JSON instead of a table.

--fix only creates a migration; it never touches the database. Review the generated file before running it, and note that down() cannot restore dropped columns automatically.

Automatically skips the primary key, created_at/updated_at, and soft-delete columns (pass --include-timestamps to report the timestamp and soft-delete columns too). The model's own file is excluded from reference scanning, so a column declared only in $fillable/$casts does not count as used and is still reported.

Searchable file types: .php, .blade.php, .json, .vue, .js, .ts. A column counts as referenced if it appears as ->column, ['column'], or 'column' => anywhere.

⚠️ Attributes accessed dynamically or in raw SQL will produce false positives. Treat the output as a review list, not an auto-delete list.

Queues

These operate on every queue listed in queues, so you declare your queue topology once and get a consistent set of commands.

queues:list

php artisan queues:list

queues:listen

Listens on all configured queues at once, using queue_timeout.

php artisan queues:listen

queues:clear

php artisan queues:clear

All three fail with a clear message if queues is empty.

Utilities

env:diff

Compares two env files by key without revealing values. Useful for CI to ensure required keys exist.

php artisan env:diff
php artisan env:diff --base=.env.example --target=.env
php artisan env:diff --json                     # machine‑readable JSON output
php artisan env:diff --fail                     # non‑zero exit when required keys are missing
Option Description
--base= Reference env file (default .env.example).
--target= Env file to compare (default .env).
--json Emit JSON with missing, extra, empty, duplicates arrays.
--fail Exit with error code when any required key is missing.

The command never prints values; it only reports key mismatches, empty values, and duplicate definitions.

Option Description
--fail Exit non-zero when differences are found.
--status= Comma-separated statuses to include, e.g. added,unset.
--json Emit {differences, rows} instead of a table.

Output is a table with a status badge per row, values rendered as indented JSON blocks, and class names shortened to their basename. Sensitive-looking keys (*_secret, *_token, api_key, …) are masked, with key_storage_path explicitly exempted since it holds a path rather than a secret. Masking also applies to --json.

Statuses: added, extended, modified, reordered, trimmed, disabled, unset.

app:status

Quick environment check.

php artisan app:status
Application Status
PHP Version: 8.4.24
Laravel Version: 12.x
Environment: local

Toolkit Status
Active Overrides: 2
Active Commands: 18

route:filter

Filters registered routes by URI or name substring.

php artisan route:filter v1/currencies
php artisan route:filter users
php artisan route:filter curren --method=POST --middleware=auth
php artisan route:filter api --except=admin,internal
php artisan route:filter v1 --json
Option Description
--method= Only routes handling this HTTP method.
--middleware= Only routes whose middleware contains this value.
--except= Comma-separated keywords to exclude by URI or name.
--json Emit uri, name, methods and middleware as JSON.

The pattern is treated as a regular expression when it is a valid delimited pattern (e.g. '/^api\/v1/'), otherwise as a case-sensitive substring match.

db:seed-partial

Runs a single seeder without invoking the full DatabaseSeeder.

php artisan db:seed-partial "Database\Seeders\UserSeeder"

Configuration reference

Key Default Purpose
overrides.* see config Built-in commands to replace
commands.* see config Package commands to register
paths.enums app/Enums Target for make:enum
paths.repositories app/Repositories Target for repositories
paths.repository_interfaces app/Repositories/Contracts Target for make:repo --with-interface
paths.services app/Services Target for make:service
paths.dtos app/DTOs Target for make:dto
paths.api_controllers app/Http/Controllers/Api Target for API controllers
paths.resources app/Http/Resources Target for resources
paths.resource_collections app/Http/Resources/Collections Target for resource collections
paths.requests app/Http/Requests Target for form requests
paths.tests tests/Feature Target for make:api-scaffold --with-tests
paths.factories database/factories Target for make:api-scaffold --with-factory
paths.model_scan ['app/Models', 'app/Models/Base'] Directories scanned for models
base_classes.repository App\Repositories\BaseRepo Parent class for generated repositories
base_classes.resource Illuminate\Http\Resources\Json\JsonResource Parent class for generated resources
model_base_namespace App\Models Namespace used to resolve short model names
api_version v1 Version segment in generated routes
encrypted_models [] Models and attributes to re-encrypt on key rotation
key_storage_path storage/app/keys/app-keys.json JSON file mirroring current/previous keys
queues ['default', 'high', 'low'] Queues managed by queues:*
queue_timeout 60 Seconds passed to queue:listen
prune_search_root app Root directory for reference scanning
schema_dump_include_schema true Keep the schema prefix in schema:dump output; false makes dumps schema-agnostic

Each entry is documented inline in config/artisan-toolkit.php.

Generated classes derive their namespace from the configured path, so moving paths.repositories to app/Domain/Repos produces files declaring namespace App\Domain\Repos;. Likewise base_classes.* controls which parent class is emitted (and imported) in the generated file.

Upgrading

Package updates add new commands to the service provider's defaults, so they register without any action from you. If you want them disabled, add an explicit false entry to your published config.

php artisan config:diff shows you exactly what differs from the shipped defaults after an upgrade.

Breaking changes

key:generate is now dry-run by default. Previously php artisan key:generate rotated immediately. It now previews and requires --apply:

# Before (≤ previous versions)
php artisan key:generate

# Now
php artisan key:generate --apply

Development

See DEVELOPMENT.md for local setup, running tests, and adding new commands.

License

MIT