Craftsman CLI

ZephyrPHP's powerful command-line interface for rapid application development. Generate code, manage databases, handle modules, and streamline your workflow with 25+ built-in commands.

Overview

The Craftsman CLI is built on Symfony Console and provides an intuitive, interactive interface for common development tasks. Commands are auto-discovered from the framework, making it easy to extend with custom commands.

Basic Usage

php craftsman [command] [arguments] [options]

Listing All Commands

# Show all available commands
php craftsman list

# Show help for a specific command
php craftsman help [command]

Command Categories

Craftsman commands are organized into logical categories to help you quickly find what you need. Explore each category below to learn about the available commands.

Quick Reference

Here's a quick overview of the most commonly used commands:

Command	Description
serve	Start development server
key:generate	Generate encryption key
db:setup	Interactive database configuration
db:schema	Create/update database tables
make:model	Create a simple model
model:wizard	Interactive model builder
model:build	Quick model via CLI syntax
make:controller	Create controller class
make:route	Create route with controller & view
make:crud	Generate complete CRUD application
route:list	List all registered routes
cache:clear	Clear application cache
add	Install and enable module
module:list	List available modules
auth:setup	Configure authentication

Common Workflows

New Project Setup

# 1. Generate application key
php craftsman key:generate

# 2. Configure database (if needed)
php craftsman db:setup

# 3. Install database module
php craftsman add database

# 4. Create database
php craftsman db:create

# 5. Start development server
php craftsman serve

Creating a Complete CRUD Resource

# Option 1: Interactive CRUD generator
php craftsman make:crud

# Option 2: Direct CRUD generation
php craftsman make:crud Post

# Then create the database schema
php craftsman db:schema

Adding a New Feature

# 1. Create model
php craftsman model:wizard

# 2. Update database schema
php craftsman db:schema

# 3. Create controller
php craftsman make:controller PostController

# 4. Create routes and views
php craftsman make:route /posts --controller PostController

Best Practices

Naming Conventions

• Models: PascalCase singular (e.g., User, BlogPost)
• Controllers: PascalCase with "Controller" suffix (e.g., PostController)
• Middleware: PascalCase with "Middleware" suffix (e.g., AuthMiddleware)
• Jobs: PascalCase verb + noun (e.g., SendEmail, ProcessPayment)
• Migrations: snake_case descriptive (e.g., create_users_table)

Development Workflow

• Start with serve - Always use php craftsman serve for local development
• Generate keys first - Run key:generate immediately after installation
• Use wizards for complex tasks - model:wizard and make:crud are faster than manual creation
• Clear cache after changes - Run cache:clear if your changes aren't showing
• List routes to debug - Use route:list to verify your routes are registered

Troubleshooting

Command Not Found

If a command isn't recognized:

• Run php craftsman list to see all available commands
• Ensure the command file exists in framework/src/ZephyrPHP/Console/Commands/
• Check that the class name ends with Command.php
• Verify the #[AsCommand] attribute is present

Database Connection Errors

If database commands fail:

• Run php craftsman db:test to verify connection
• Check .env has correct credentials
• Ensure the database module is enabled: php craftsman module:enable database
• Verify database server is running

Permission Errors

If you encounter permission errors:

• Ensure storage/ directory is writable: chmod -R 775 storage
• Check file ownership matches your user
• On shared hosting, use chmod 755 instead of 775

Next Steps

Explore the command categories to learn about specific commands:

• Getting Started Commands - Set up and run your application
• Database Commands - Manage database connections and schema
• Model Generation - Create data models efficiently
• Code Generation - Scaffold application components