Getting Started Commands

Essential commands for starting your development server and configuring your application's security foundation.

serve - Start Development Server

Quickly spin up PHP's built-in development server for local testing and development.

Command

php craftsman serve [host] [port]

Arguments

Argument	Type	Default	Description
`host`	Optional	`localhost`	Server hostname or IP address
`port`	Optional	`8000`	Server port number

Examples

# Start on default localhost:8000
php craftsman serve

# Custom host and port
php craftsman serve 127.0.0.1 9000

# Expose to network (access from other devices on same network)
php craftsman serve 0.0.0.0 8080

# Specific local IP
php craftsman serve 192.168.1.100 8000

Functionality

Starts PHP's built-in development server
Serves from the public/ directory
Displays a clickable hyperlink to access the server
Shows all incoming requests in real-time
Press Ctrl+C to stop the server

Development Only

The serve command uses PHP's built-in server and is NOT suitable for production. Use Apache, Nginx, or another production-grade web server for deployment.

Common Use Cases

Local Development

# Quick local development
php craftsman serve

# Then visit http://localhost:8000 in your browser

Testing on Mobile Devices

# Expose server to local network
php craftsman serve 0.0.0.0 8000

# Access from phone/tablet using computer's IP
# Example: http://192.168.1.100:8000

Running Multiple Projects

# Project 1 on port 8000
php craftsman serve localhost 8000

# Project 2 on port 8001
php craftsman serve localhost 8001

# Project 3 on port 8002
php craftsman serve localhost 8002

key:generate - Generate Encryption Key

Generate a secure 32-byte base64-encoded application key used for encryption, hashing, CSRF tokens, and other security features.

Command

php craftsman key:generate

Functionality

Generates a cryptographically secure random key using random_bytes()
Base64-encodes the key with base64: prefix
Automatically updates .env file with APP_KEY
Creates .env from .env.example if it doesn't exist
Backs up existing key before overwriting (commented out in .env)

Example Output

$ php craftsman key:generate

Application key set successfully!
APP_KEY=base64:a3f4d2e9c8b1f6a7e4c9d2b8f1e4a7c3f6d9e2b5a8c1f4e7b0a3d6c9f2e5

What Gets Updated

Before running the command, your .env file might look like:

APP_NAME=ZephyrPHP
APP_DEBUG=true
ENV=dev
APP_KEY=

After running key:generate:

APP_NAME=ZephyrPHP
APP_DEBUG=true
ENV=dev
APP_KEY=base64:a3f4d2e9c8b1f6a7e4c9d2b8f1e4a7c3f6d9e2b5a8c1f4e7b0a3d6c9f2e5

Security Best Practices

Critical Security Information

Never share your APP_KEY publicly or with unauthorized individuals
Never commit .env to version control (always add to .gitignore)
Generate unique keys for each environment (dev, staging, production)
Regenerating the key invalidates:
- All encrypted data (passwords, sensitive fields)
- All active sessions
- All CSRF tokens
- All signed URLs

When to Generate Keys

Fresh Installation

# Immediately after installing ZephyrPHP
php craftsman key:generate

New Environment Setup

# Production server
cp .env.example .env.production
php craftsman key:generate
# Manually edit .env.production for production settings

# Staging server
cp .env.example .env.staging
php craftsman key:generate
# Manually edit .env.staging for staging settings

Security Breach Response

If your APP_KEY is ever compromised:

# 1. Generate a new key
php craftsman key:generate

# 2. Re-encrypt all sensitive data
# 3. Force all users to log out (sessions are invalidated automatically)
# 4. Audit access logs for unauthorized access

What Uses the Application Key

The APP_KEY is used throughout ZephyrPHP for:

Encryption - Encrypting sensitive database fields
Hashing - Creating secure hashes for data integrity
CSRF Protection - Generating CSRF tokens
Session Security - Signing session cookies
Password Reset Tokens - Creating secure password reset links
Remember Me Tokens - Creating "remember me" cookies
Signed URLs - Creating tamper-proof URLs with expiration

Typical Startup Workflow

Here's the recommended workflow when starting a new ZephyrPHP project:

# 1. Install ZephyrPHP (via installer, Composer, or Git)
# See installation documentation

# 2. Generate application key
php craftsman key:generate

# 3. Configure environment (optional at this stage)
# Edit .env file with your settings

# 4. Start development server
php craftsman serve

# 5. Visit http://localhost:8000 in browser
# You should see the ZephyrPHP welcome page

Troubleshooting

Port Already in Use

If you get an error that the port is already in use:

# Try a different port
php craftsman serve localhost 8001

# Or find and kill the process using the port (Linux/Mac)
lsof -ti:8000 | xargs kill -9

# Windows
netstat -ano | findstr :8000
taskkill /PID [process_id] /F

Permission Denied

If you can't bind to the port (Linux/Mac):

# Use a port above 1024 (don't require root)
php craftsman serve localhost 8080

# Or use sudo for ports below 1024 (not recommended)
sudo php craftsman serve localhost 80

.env File Not Writable

If key:generate fails to write:

# Check file permissions
ls -l .env

# Make writable
chmod 644 .env

# Check directory permissions
ls -ld .

# Ensure current directory is writable
chmod 755 .

Key Already Exists Warning

If a key already exists, the command will ask for confirmation before overwriting. The old key will be preserved as a comment in the .env file in case you need to revert.

Next Steps

Now that you have your development environment running: