README

Production-ready PHP REST API boilerplate that lets you focus on building your business logic, not the infrastructure.

Why Use This?

Stop wasting time configuring infrastructure. This template provides everything you need to build professional REST APIs:

✅ Start coding in minutes - Not hours or days
✅ Production-ready - Security, authentication, and best practices built-in
✅ Code generator - Automatically create CRUD operations from database tables
✅ Two architectural patterns - Choose between Repository or ActiveRecord
✅ OpenAPI documentation - Auto-generated, always in sync
✅ Fully tested - Includes a functional test suite
✅ Docker-ready - Containerized development and deployment

Quick Start

# Create your project
composer -sdev create-project byjg/rest-reference-architecture my-api ^6.0

# Start containers
cd my-api
docker compose -f docker-compose.yml up -d

# Run migrations
composer migrate -- --env=dev reset

# Your API is ready!
curl http://localhost:8080/sample/ping

📚 Complete Getting Started Guide →

Architecture Overview

mindmap
  (("Reference Architecture"))
    ("PSR Standards")
      ("WebRequests")
      ("Container & Dependency Injection")
      ("Cache")
    ("Authentication & Authorization")
    ("Decoupled Code")
    ("Database")
      ("ORM Integration")
      ("Migration")
      ("Routing")
    ("OpenAPI Integration")
      ("Rest Methods")
      ("Contract Testing")
      ("Documentation")
    ("Error Handling")

Key Features

🚀 Code Generation

Automatically generate Models, Repositories, Services, REST Controllers, and Tests from your database schema.

composer codegen -- --env=dev --table=users all --save

📚 Code Generator Documentation →

🏗️ Two Architectural Patterns

Repository Pattern (default)

Clean separation of concerns
Service layer for business logic
Full dependency injection

ActiveRecord Pattern

Rapid prototyping
Less boilerplate
Direct database access from models

📚 Choose Your Pattern →

🔐 Authentication & Authorization Built-in

JWT-based authentication
Role-based access control (RBAC)
Secure by default
Ready-to-use login endpoints

📚 Authentication Guide →

📖 OpenAPI Integration

Auto-generated documentation
Interactive API explorer (Swagger UI)
Always synchronized with your code
Contract testing support

📚 REST API Documentation →

🗄️ Database Management

Migrations

Version control your database schema
Up/down migration support
Zero-downtime deployments

📚 Migration Guide →

ORM Integration

MicroORM for lightweight data access
Query builder
Relationship mapping

📚 ORM Documentation →

🧪 Testing Built-in

Functional test suite included
Test helpers and fixtures
OpenAPI contract testing
Supports custom test scenarios

📚 Testing Guide →

🐳 Docker Ready

Pre-configured Docker setup
Development and production configurations
MySQL, PHP-FPM, and Nginx
One command to start

🔧 Scriptify - Interactive Development

Interactive PHP Terminal: REPL with your project's autoloader
CLI Script Runner: Execute any PHP method from command line
Service Management: Install PHP classes as system daemons
Quick prototyping and debugging

composer terminal  # Start interactive PHP shell

📚 Scriptify Guide →

⚙️ Modern PHP Standards

Implements PSR standards:

PSR-7: HTTP Message Interface
PSR-11: Container Interface
PSR-6 & PSR-16: Cache Interface
And more...

📚 PSR-11 Container → | Dependency Injection →

What's Included

Feature	Description	Documentation
Code Generator	Generate CRUD from database tables	→ Docs
REST API	OpenAPI-documented endpoints	→ Docs
Authentication	JWT with role-based access	→ Docs
Database	Migrations + ORM	→ Docs
Testing	Functional test suite	→ Docs
Service Layer	Business logic separation	→ Docs
Scriptify	Interactive terminal & CLI scripts	→ Docs
Unattended Setup	CI/CD friendly installation	→ Docs

Documentation

Getting Started

Installation & Setup – Install the template, configure environments, and review prerequisites.
Create Your First Table – Define your first migration and schema.
Add Fields – Safely evolve existing tables.
Create REST Endpoints – Generate REST handlers from your tables.

Build Your API

Code Generator – Automate models, repositories, services, controllers, and tests.
REST API – Implement endpoints that stay in sync with OpenAPI contracts.
Authentication – Configure JWT login flows and RBAC enforcement.
Database Migration – Version and run schema migrations in every environment.
ORM – Use MicroORM for repository and ActiveRecord patterns.
Service Layer – Organize business logic and transaction boundaries.
Service Patterns – Adopt advanced orchestration, validation, and DTO patterns.
Repository Patterns – Implement complex queries, UUID handling, and filtering helpers.
Attributes System – Apply RequireRole, ValidateRequest, and custom attributes to controllers.
Traits Reference – Reuse timestamp and soft-delete helpers inside models.
Template Customization – Tailor the generator templates to match your coding standards.

Architecture & Operations

Configuration Deep Dive – Layer configurations, secrets, and environment overrides.
Architecture Decisions – Decide when to use Repository or ActiveRecord implementations.
PSR-11 Container – Understand the default container bindings that power src/.
Dependency Injection – Wire repositories, services, and factories through the container.
Scriptify – Use the REPL, CLI runner, and service manager utilities.
Unattended Setup – Automate installs for CI/CD pipelines.
Windows Setup – Follow the WSL/Windows specific checklist.

Testing & Quality

Complete Testing Guide – Unit, integration, and contract testing reference.
Functional Tests – Use FakeApiRequester and fixtures for end-to-end coverage.
JWT Authentication Advanced – Extend tokens with custom claims and refresh logic.
Error Handling – Map exceptions to HTTP responses and logging patterns.

Real-World Example

# 1. Create database table
cat > db/migrations/up/00002-create-products.sql << 'EOF'
CREATE TABLE products (
    id INT AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    price DECIMAL(10,2) NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
EOF

# 2. Run migration
composer migrate -- --env=dev update

# 3. Generate all code
composer codegen -- --env=dev --table=products all --save

# 4. Your CRUD API is ready!
curl http://localhost:8080/products

You just created a complete CRUD API with:

✅ Model with validation
✅ Repository for data access
✅ Service for business logic
✅ REST controller with GET, POST, PUT endpoints
✅ Functional tests
✅ OpenAPI documentation
✅ JWT authentication

Requirements

PHP 8.3+ (8.5 recommended)
Docker & Docker Compose (optional but recommended)
Composer
Git

Support & Community

📖 Full Documentation
🐛 Report Issues
💡 Request Features
🌐 ByJG Open Source

Not a Framework

This is a template, not a framework. You own the code:

✅ Full control over every file
✅ No vendor lock-in
✅ Customize anything you need
✅ Remove what you don't need

License

This project is open source. See LICENSE for details.

Dependencies

📚 Complete Component Dependency Graph →

Open source ByJG

byjg / resttemplate

Maintainers

Details