Download the PHP package phastasf/app without Composer

Phast Framework Skeleton

A skeleton application for Phast Framework - a lightweight, modern PHP framework built on PSR standards.

Features

This skeleton application provides a clean starting point for building applications with Phast Framework, including:

• ✅ PSR Standards: Full compliance with PSR-7, PSR-11, PSR-15, PSR-3, PSR-6, PSR-16, and PSR-20
• ✅ Routing: Example routes demonstrating controller actions and closures
• ✅ Controllers: Base controller with helper methods for rendering views, JSON responses, and redirects
• ✅ Views: Template rendering with Phew template engine
• ✅ Console Commands: CLI entrypoint for running console commands
• ✅ Error Handling: Centralized exception handling
• ✅ Dependency Injection: Service container integration
• ✅ Docker Support: Complete Docker setup with Traefik, MySQL, Redis, and development tools
• ✅ Frontend Tooling: Vite + React setup with hot module replacement and production builds
• ✅ Seeders: Generate and run seeders for development and testing data

Requirements

• Docker and Docker Compose
• mkcert for local SSL certificates
• PHP 8.2 or higher (for local development without Docker)
• Node.js 22+ and Yarn (for frontend development)

Installation

Setup project:

Create SSL certificates:

This will create certificate files (local.dev+4.pem and local.dev+4-key.pem) in the project root.

Add hostnames to /etc/hosts:

Add the following lines:

Start services:

Usage

Available Services

Once the Docker services are running, you can access:

• Frontend (Vite Dev Server): https://web.local.dev/
• Backend API: https://api.local.dev/
• Traefik Dashboard: http://localhost:8080
• phpMyAdmin: https://phpmyadmin.local.dev/
• MailCatcher: https://mailcatcher.local.dev/
• Redis Insight: https://redis-insight.local.dev/

Example Routes

• GET / - Home page (renders welcome view)
• GET /health - Health check endpoint
• GET /error - Error handling test route
• GET /api/status - API status endpoint (example of route groups)

Docker Services

The Docker Compose setup includes:

• web - Node.js 22 container running Vite dev server for frontend development
• api - PHP 8.5 Apache container running the backend API
• worker - Queue worker container
• mysql - MySQL 8 database server
• redis - Redis 5 cache and queue backend
• traefik - Reverse proxy with automatic HTTPS
• phpmyadmin - Database management interface
• mailcatcher - Email testing tool
• redis-insight - Redis management interface

Structure

The project structure is as explained below:

Console Commands

Generators

Create command

Generate a new console command:

Create controller

Generate a new controller:

Create model

Generate a new model:

Create migration

Generate a new migration:

Create job

Generate a new job class:

Create event

Generate a new event class:

Create middleware

Generate a new middleware class:

Create service provider

Generate a new service provider:

Create seeder

Generate a new seeder class (for development/testing data):

Database

Run migrations

Run pending migrations:

Rollback migrations

Rollback migrations (default: 1):

Rollback multiple migrations:

Run seeders

Run database seeders (only those listed in config/database.php under seed):

Development

Start development server

Start the development server:

Run queue worker

Start a queue worker:

Interactive shell

Start an interactive PHP shell (REPL) with container access:

Clear cache

Clear cached config, routes, and application cache:

Configuration

Configuration files can be placed in the config/ directory to override framework defaults. The framework loads default configurations from the package and merges your project-specific overrides.

Environment variables are configured in the .env file. The .env.example file includes default values configured for the Docker setup:

• Database connection uses mysql as hostname (Docker service name)
• Redis connection uses redis as hostname (Docker service name)
• All services are accessible via .local.dev domain with SSL certificates

Middleware

Middleware allows you to intercept and modify HTTP requests and responses. Create a custom middleware using the generator:

This will create a middleware in app/Middleware/ that implements Psr\Http\Server\MiddlewareInterface.

The config/middleware.php file is automatically copied from the framework during composer install or composer update if it doesn't exist. This file defines the middleware pipeline that processes HTTP requests:

Middleware is executed in the order defined in the array. Core middleware must remain in their positions for the framework to function correctly.

The ClientIpMiddleware correctly detects client IP addresses when running behind a reverse proxy (like Traefik). It reads trusted proxy configuration from config/proxies.php if it exists.

Service Providers

Service providers allow you to register services in the dependency injection container. Create a custom provider using the generator:

This will create a provider in app/Providers/ that implements Phast\Providers\ProviderInterface. The provider has two methods:

• provide(Container $container) - Register services in the container
• init(Container $container) - Initialize services after all providers are registered

The config/providers.php file is automatically copied from the framework during composer install or composer update if it doesn't exist. You can customize it to add your own providers:

Database

Seeders

Seeders add fake or test data to the database. They live in database/seeders/, implement Phast\Database\SeederInterface, and receive dependencies (e.g. ConnectionInterface) via constructor injection. Only the seeders listed in config/database.php under the seed key are run when you execute the seed command.

To run your seeders, add their class names (no namespace) to config/database.php:

You can insert data via the raw connection or using models. Generate a new seeder with php console g:seeder SeederName.

The default database configuration in .env.example:

• Host: mysql (Docker service name)
• Database: phastapp
• Username: phastapp
• Password: phastapp

Emails

MailCatcher is configured to catch all emails. Configure your .env to use SMTP:

Frontend Environment Variables

Frontend environment variables are prefixed with VITE_ and are available via import.meta.env:

Development: Set VITE_API_BASE_URL=https://api.local.dev in .env for separate API container.

Production: Leave unset (defaults to /) when PHP and frontend are served together by Apache.

The .env.example file includes:

Frontend Development

This skeleton includes a modern frontend setup with Vite and React.

Frontend Structure

• resources/assets/ - Frontend source files (React components, styles, etc.)
• public_html/assets/ - Built frontend assets (generated by Vite)
• public_html/index.html - Built HTML entry point (generated by Vite)

Development Workflow

The frontend development server runs automatically in Docker via the web service. It provides:

• Hot Module Replacement (HMR) - Instant updates without page refresh
• Fast Refresh - React component state preservation during updates
• TypeScript Support - Full type checking and IntelliSense
• ESLint Integration - Code quality and style checking

Frontend Commands

Development Server

The Vite dev server runs automatically in Docker. To run it locally:

Build for Production

Build the frontend for production:

This compiles TypeScript, bundles assets, and outputs to public_html/.

Lint Code

Check code quality:

API Integration

The frontend includes an example API connection test that calls /api/status. The API endpoint returns a simple 200 OK response to verify connectivity.

Production Build

The Dockerfile includes a multi-stage build that:

1. Builds the frontend using Node.js in a separate stage
2. Copies the built assets to the PHP container
3. Serves everything together via Apache

This ensures optimized production builds while keeping development fast with HMR.

Development

Viewing Logs

View application logs:

View worker logs:

Executing Commands

Run any PHP command in the web container:

Access the container shell:

Stopping Services

Stop all services:

Stop and remove volumes:

Documentation

For complete documentation, visit the Phast Framework documentation.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open-sourced software licensed under the MIT license.

Credits

Built with Phast Framework.