Installation

Get ZephyrPHP up and running in under 2 minutes. Multiple installation methods to fit your workflow.

System Requirements

Before installing ZephyrPHP, ensure your system meets these requirements:

Requirement	Version/Details
PHP	8.2 or higher
Composer	2.0 or higher
PHP Extensions	PDO, mbstring, openssl, json
Optional	Git (for installer --dev mode), Redis/APCu (for caching)

Installation Methods

ZephyrPHP offers three installation methods. Choose the one that best fits your workflow:

Method	Best For	Automation Level
ZephyrPHP Installer	Most users, quick setup	High (auto key, git, dev mode)
Composer Create-Project	Standard Composer workflow	Medium (namespace setup)
Git Clone	Development, contributing	Low (manual setup)

Method 1: ZephyrPHP Installer (Recommended)

The official installer provides the fastest and easiest way to create new ZephyrPHP projects with powerful automation options.

Step 1: Install the Installer Globally

composer global require zephyrphp/installer

Step 2: Add Composer to PATH

Ensure Composer's global bin directory is in your system PATH:

Platform	Path to Add
macOS/Linux	~/.composer/vendor/bin or ~/.config/composer/vendor/bin
Windows	%APPDATA%\Composer\vendor\bin

macOS/Linux:

export PATH="$HOME/.composer/vendor/bin:$PATH"

# Add permanently to your shell profile
echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows:

Add %APPDATA%\Composer\vendor\bin to your System Environment Variables via Control Panel.

Step 3: Verify Installation

zephyrphp --version

Step 4: Create a New Project

zephyrphp new my-project
cd my-project
php craftsman serve

That's it! Your application is running at http://localhost:8000.

Installer Options

The installer supports powerful options for customizing your project setup:

Option	Short	Description
--git	-g	Initialize Git repository with initial commit
--dev	-d	Install latest development version from GitHub
--branch	-b	Specify branch for dev mode (default: main)
--force	-f	Overwrite existing directory
--no-install		Skip running composer install

Usage Examples

# Basic project
zephyrphp new blog

# With Git initialization
zephyrphp new blog --git

# Development version (latest from GitHub)
zephyrphp new blog --dev

# Specific branch
zephyrphp new blog --dev --branch develop

# Force overwrite existing directory
zephyrphp new blog --force

# Skip composer install (install manually later)
zephyrphp new blog --no-install

# Combine options
zephyrphp new blog --git --dev

Other Installer Commands

Command	Description
zephyrphp version	Display installer version and system information
zephyrphp list	List all available commands
zephyrphp help <command>	Get help for a specific command

Method 2: Composer Create-Project

Use Composer's standard create-project command for a more traditional Composer workflow:

composer create-project zephyrphp/starter my-app
cd my-app
php craftsman key:generate
php craftsman serve

Method 3: Git Clone

Clone the starter repository directly (useful for development or contributing):

git clone https://github.com/Techwonia/zephyrphp-starter.git my-app
cd my-app
composer install
cp .env.example .env
php craftsman key:generate
php craftsman serve

Initialize Your Own Git Repository

rm -rf .git
git init
git add .
git commit -m "Initial commit - ZephyrPHP project"

Post-Installation Setup

Generate Application Key

The APP_KEY is critical for encryption and security. If not generated automatically, run:

php craftsman key:generate

This generates a secure 32-byte random key, encodes it as base64, and updates your .env file.

Configure Environment Variables

Edit the .env file to configure your application:

# Application Settings
APP_NAME="My ZephyrPHP App"
APP_DEBUG=true
ENV=dev
APP_URL=http://localhost:8000
APP_TIMEZONE=UTC
APP_LOCALE=en

# Security Key (Generated by key:generate)
APP_KEY=base64:your-generated-key-here

# Views
VIEWS_PATH=/pages

Database Setup (Optional)

If you're using the database module, configure your database interactively:

php craftsman db:setup

This interactive command:

• Prompts for database driver (MySQL, PostgreSQL, SQLite, SQL Server)
• Asks for connection details (host, port, database name, credentials)
• Tests the connection
• Optionally creates the database if it doesn't exist
• Updates your .env file automatically

Supported Database Drivers:

• MySQL (pdo_mysql)
• MariaDB (pdo_mysql)
• PostgreSQL (pdo_pgsql)
• SQLite (pdo_sqlite)
• SQL Server (pdo_sqlsrv)

Authentication Setup (Optional)

Configure authentication for your application:

php craftsman auth:setup

This interactive command configures:

• Authentication type (Session, JWT, or Both)
• User model class
• Session driver (file, database, redis) and lifetime
• JWT secret and token expiry
• Optionally creates User model with authentication methods
• Optionally creates Auth middleware

Directory Permissions

Ensure the storage/ directory is writable:

Linux/macOS:

chmod -R 775 storage
chmod -R 775 pages/compiled

# Or with www-data user
sudo chown -R www-data:www-data storage
sudo chmod -R 775 storage

Windows:

Ensure your web server user has write access to storage/ and pages/compiled/ directories.

Development Server

ZephyrPHP includes a built-in development server:

# Default (localhost:8000)
php craftsman serve

# Custom host and port
php craftsman serve 0.0.0.0 3000

Installing Optional Modules

ZephyrPHP's core is minimal. Add functionality with optional modules:

Using Craftsman CLI

php craftsman add database
php craftsman add auth
php craftsman add cache
php craftsman add api
php craftsman add authorization
php craftsman add mail
php craftsman add queue

The add command:

• Runs composer require zephyrphp/{module}
• Updates config/modules.php to enable the module
• Runs post-install setup hooks (e.g., db:setup for database)

Available Modules

Module	Install Command	Purpose
database	php craftsman add database	Doctrine ORM, Query Builder, Migrations
auth	php craftsman add auth	Session & JWT Authentication
authorization	php craftsman add authorization	Gates & Policies for Permissions
cache	php craftsman add cache	File, Redis, APCu, Array Drivers
api	php craftsman add api	API Resources & Responses
mail	php craftsman add mail	Email with SMTP, Mail, Log Drivers
queue	php craftsman add queue	Background Job Processing

Manual Module Installation

Alternatively, install modules manually with Composer:

composer require zephyrphp/database

Then enable in config/modules.php:

'modules' => [
    'session',
    'validation',
    'view',
    'database',  // Add this line
],

Web Server Configuration

Apache

ZephyrPHP includes an .htaccess file in public/ with security rules and URL rewriting.

Requirements:

• Apache with mod_rewrite enabled
• AllowOverride All for the document root

Virtual Host Configuration:

<VirtualHost *:80>
    ServerName myapp.local
    DocumentRoot "/var/www/myapp/public"

    <Directory "/var/www/myapp/public">
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog "/var/log/apache2/myapp-error.log"
    CustomLog "/var/log/apache2/myapp-access.log" combined
</VirtualHost>

Enable the virtual host:

sudo a2ensite myapp.conf
sudo a2enmod rewrite
sudo systemctl restart apache2

Nginx

For Nginx, configure URL rewriting manually:

server {
    listen 80;
    listen [::]:80;
    server_name myapp.local;
    root /var/www/myapp/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;
    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Verifying Your Installation

To verify everything is working:

1. Start the development server: php craftsman serve
2. Open http://localhost:8000 in your browser
3. You should see the ZephyrPHP welcome page

Verify CLI Tools

# List all Craftsman commands
php craftsman

# View registered routes
php craftsman route:list

# Test database connection (if database module installed)
php craftsman db:test

Troubleshooting

Installer Command Not Found

If zephyrphp command is not found:

macOS/Linux:

# Check Composer global bin directory
composer global config bin-dir --absolute

# Add to PATH permanently
export PATH="$HOME/.composer/vendor/bin:$PATH"
echo 'export PATH="$HOME/.composer/vendor/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Make executable
chmod +x ~/.composer/vendor/bin/zephyrphp

Windows:

1. Open System Properties → Environment Variables
2. Add %APPDATA%\Composer\vendor\bin to Path
3. Restart your terminal

Composer Not Found

Install Composer from getcomposer.org or via package manager:

# macOS (Homebrew)
brew install composer

# Ubuntu/Debian
sudo apt-get install composer

# Windows (Chocolatey)
choco install composer

Permission Denied Errors

Ensure your web server user has write access to:

• storage/logs/
• storage/compiled/
• storage/uploads/

# Linux/macOS
sudo chown -R www-data:www-data storage
sudo chmod -R 775 storage

Blank Page / No Errors

• Check storage/logs/app.log
• Check PHP error log
• Ensure APP_DEBUG=true in .env for development
• Verify storage directory is writable

404 Errors on All Pages

• Apache: Enable mod_rewrite and set AllowOverride All
• Nginx: Verify try_files directive is configured
• Ensure document root points to public/ directory

Database Connection Issues

# Test database connection
php craftsman db:test

# Reconfigure database
php craftsman db:setup

Next Steps

Now that ZephyrPHP is installed:

• Learn about the Directory Structure
• Understand Configuration options
• Explore Routing to define routes
• Create your first Controller