Laravel Module Generator

v 1.3.*

🚀 Complete workflow — from YAML to a working API

This page walks through a recommended, safe workflow to go from a YAML schema to a production-ready API, including authentication scaffolding, migrations, Postman collection for testing, and DB diagram visualization.

Steps below assume you are working from a Git branch and have a local development environment ready.

1. Generate or scaffold authentication (optional)

If your project needs an auth system (users, roles, permissions), run the authentication generator first. This ensures the User model and related auth scaffolding exist before other modules reference them.

php artisan auth:generate

Notes:

  • If you run auth:generate, the generator may create a User model and related controllers/migrations. To avoid overwriting these later, set User.generate.* flags to false in your module/models.yaml.

2. Create or edit your YAML schema

Open module/models.yaml (or your custom file) and declare your models, fields and relations. Keep these tips in mind:

  • Use foreignId:table_name for foreign keys and ensure table_name matches the target migration/table naming.
  • Use requestParent for nested child resources so validation and Postman bodies are generated as nested payloads.
  • If a relation should be eagerly loaded by default in the index method, set with: true under that relation.

Example quick edit:

vim module/models.yaml
# or use your editor of choice

3. Dry-run / Review generated files (recommended)

Before applying destructive changes, run the generator without --force so it creates outputs and backups where applicable. Review the generated files and migrations in app/, database/migrations/, and module/.

php artisan module:generate --file=module/models.yaml

Review points:

  • Check migrations to ensure column names and types match expectations.
  • Inspect Form Request validation rules for correctness.
  • Verify Controller and Service method signatures if you plan to customize business logic.

4. Apply database changes

When you're satisfied with generated migrations, run them:

php artisan migrate

If migrations conflict with existing schema, consider creating new migrations to alter tables instead of editing generated migrations that may already be applied in other environments.

5. Import Postman collection for manual testing

The generator will output a Postman collection at module/postman_collection.json (unless skipped). Import it into Postman or Insomnia to run example requests and validate endpoints.

  • Set the collection/environment baseUrl to your local server (e.g., http://127.0.0.1:8000) and the prefix (e.g., api/v1).
  • If you generated auth, create a login request and use the returned token in subsequent requests.
File: module/postman_collection.json

6. Validate DB diagram and documentation

A DBML output is written to module/dbdiagram.dbml. You can copy/paste this into dbdiagram.io to visualize relationships and export diagrams to PNG/PDF for documentation.

File: module/dbdiagram.dbml

7. Run the app locally and perform end-to-end tests

Start your dev server and run any automated tests you have. Manually exercise the generated endpoints via Postman or your front-end.

php artisan serve
# or use your local setup (sail, valet, docker-compose)

Automated test tips:

  • Add feature tests for critical endpoints (create, update, index, show, delete).
  • Mock external services if your module depends on them.

8. Commit & push changes

Once you are satisfied locally, commit generated code and migrations to your branch. Keep generated Postman / DBML files in the repo if you want them versioned for documentation and QA.

Recommended commit steps:

git checkout -b feat/generated-products
git add .
git commit -m "chore: generate Product module from YAML"
git push origin feat/generated-products

9. Deploy and run migrations on staging/production

When merging to your main branch and deploying, ensure your CI/CD runs migrations or that you run them manually on the target environment. Use zero-downtime migration strategies for production if needed.

📋 CLI Command Reference

postman:generate — Generate a Postman collection

Generate a complete Postman collection for testing your API endpoints with example requests, authentication setup, and nested payloads.

Signature:

php artisan postman:generate
    {--file= : Path to the YAML schema file}
    {--base-url= : Base URL for API}
    {--prefix= : API prefix}
    {--output= : Output file path}

Options:

  • --file=path/to/file.yaml — Specify a custom YAML schema file (default: module/models.yaml)
  • --base-url=http://localhost:8000 — Set the base URL for all requests (e.g., http://127.0.0.1:8000 or your production URL)
  • --prefix=api/v1 — Set the API prefix for endpoints (e.g., api/v1)
  • --output=module/postman_collection.json — Specify output file path (default: module/postman_collection.json)

Examples:

# Generate with default settings
php artisan postman:generate

# Generate with custom base URL and prefix
php artisan postman:generate --base-url=http://127.0.0.1:8000 --prefix=api/v1

# Generate to a custom output location
php artisan postman:generate --output=exports/api-collection.json

# Generate with all options specified
php artisan postman:generate \
  --file=module/models.yaml \
  --base-url=https://api.example.com \
  --prefix=api/v2 \
  --output=postman/collection.json

Generated Collection Features:

  • REST endpoints for all CRUD operations (Create, Read, Update, Delete)
  • Pre-configured Bearer token authentication if auth was generated
  • Example request bodies with proper nesting for related resources
  • Response examples for each endpoint
  • Environment variables for base URL, prefix, and auth token
  • Ready-to-import into Postman or Insomnia

dbdiagram:generate — Export database schema as DBML

Generate a DBML (Database Markup Language) file that visualizes your database schema with all tables, columns, relationships, and constraints.

Signature:

php artisan dbdiagram:generate
    {--file= : Path to the YAML schema file}
    {--output= : Path to the output DBML file}

Options:

  • --file=path/to/file.yaml — Specify a custom YAML schema file (default: module/models.yaml)
  • --output=module/dbdiagram.dbml — Specify output file path (default: module/dbdiagram.dbml)

Examples:

# Generate with default settings
php artisan dbdiagram:generate

# Generate to a custom output location
php artisan dbdiagram:generate --output=docs/schema.dbml

# Generate with custom YAML and output
php artisan dbdiagram:generate \
  --file=schemas/custom.yaml \
  --output=exports/db-schema.dbml

Generated DBML Features:

  • Complete table definitions with all columns
  • Data types for each column (string, integer, boolean, timestamp, etc.)
  • Foreign key relationships and indexes
  • Unique constraints and default values
  • Can be imported into dbdiagram.io for visualization
  • Exportable to PNG/PDF for documentation and architecture diagrams

Workflow:

  1. Generate the DBML file
  2. Copy the content to dbdiagram.io
  3. Export the diagram as PNG or PDF for documentation
  4. Share with your team or include in project documentation

module:rollback — Rollback to a previous generation state

Restore your generated files and migrations to a previous state if something goes wrong. Each generation creates automatic backups.

Signature:

php artisan module:rollback
    {--backup= : Specific backup timestamp to rollback to}
    {--list : List available backups}
    {--cleanup : Clean up old backups}

Options:

  • --backup=2024-01-15_143022 — Rollback to a specific backup by timestamp
  • --list — Display all available backups with timestamps
  • --cleanup — Remove old backup files to free up space (keeps the most recent N backups)

Examples:

# List all available backups
php artisan module:rollback --list

# Rollback to a specific backup
php artisan module:rollback --backup=2024-01-15_143022

# Rollback to the most recent backup (without --backup flag)
php artisan module:rollback

# Clean up old backups and keep only recent ones
php artisan module:rollback --cleanup

Backup Storage:

  • Backups are stored in a dedicated backup directory (configured in your environment or defaults to module/backups/)
  • Each backup is timestamped for easy identification
  • Both generated code files and database migrations are included in backups

When to Use:

  • You accidentally overwrote important custom code
  • A migration caused unexpected database issues
  • You need to revert to a previous module structure
  • Testing different schema configurations and comparing results

Troubleshooting & quick fixes

  • Accidentally overwrote files: run php artisan module:rollback --list to see available backups, then php artisan module:rollback --backup=<timestamp> to restore.
  • Migration errors after generating: inspect the generated migration file and database schema; prefer writing a new migration that alters the table rather than editing a migration that has already been applied in other environments.
  • Postman token issues: make sure you run the generated login route and copy the Bearer token into the environment.
  • Database schema visibility: use php artisan dbdiagram:generate to export your schema and view it at dbdiagram.io for better understanding of relationships.
  • Backup space: periodically run php artisan module:rollback --cleanup to remove old backups and free up disk space.

Following this workflow will help you safely move from YAML schemas to fully-functional API endpoints while keeping a clear audit trail and documentation for QA and the rest of your team.

previous
next