Download the PHP package byjg/rest-reference-architecture without Composer

Gluo — PHP REST API Starter

Gluo (Esperanto for glue) is a production-ready PHP REST API starter: create a project you fully own, powered by an updatable framework core — so you focus on business logic, not infrastructure.

Why Use This?

Every new REST API needs the same boilerplate: authentication, migrations, an ORM, OpenAPI docs, a test harness, and a DI container. Setting all of that up correctly takes days — and it's not the work your users care about.

Gluo splits the problem the right way:

• Your project (composer create-project byjg/gluo) — a full-stack monorepo: the PHP REST API at the repository root, an optional Vite + React frontend in frontend/, plus docker-compose.yml and docker/. Generated once, renamed to your namespace, fully yours: change, remove, or replace anything.
• The framework core (byjg/gluo-core) — base classes, auth flow, attributes, code generator, and test harness live in vendor/ and improve with a plain composer update. No copy-paste to stay current.

Quick Start

Commands like composer migrate, composer test, composer codegen, composer openapi, and composer psalm run from the repository root — there is a single composer.json, and the repository root is the PHP application root.

What you get

The create-project installer offers two toggles:

• Install Frontend — keep the frontend/ SPA (login, password-reset, dashboard, and profile screens, wired to the API over JWT). Say no and frontend/, its Docker image, and the frontend compose service are removed, leaving a pure API project.
• Install Examples — keep the demo entities (Project, Task, Note) and their frontend pages. Say no and you get a clean app shell (auth + profile only, no example CRUD).

When the frontend is enabled, docker compose up -d serves it at http://localhost:7080 (via byjg/static-httpserver) while the API answers on http://localhost:8080. See the Frontend guide →.

📚 Complete Getting Started Guide →

Architecture Overview

Key Features

• 🚀 Code generator — one command scaffolds Model, Repository, Service, REST controller, and tests from any database table
• 🏗️ Two patterns — choose Repository (DI + Service layer) or ActiveRecord per entity; mix them in the same project
• 🔐 Auth out of the box — JWT login, token refresh, password reset, and role-based access control (RBAC) included
• 📖 OpenAPI-first — routes are driven by openapi.json; Swagger UI, contract testing, and docs stay in sync automatically
• 🗄️ Database migrations — versioned up/down SQL migrations with a one-command runner and ORM integration
• 🧪 In-process testing — FakeApiRequester runs the full API stack inside PHPUnit, no web server needed
• 🎨 Optional React frontend — a Vite + React 19 + Tailwind SPA in frontend/ with login, password-reset, dashboard, and profile screens already wired to the API over JWT
• 🐳 Docker ready — MySQL, PHP-FPM, Nginx, and the frontend pre-configured; docker compose up -d and you're running
• 🔄 Updatable core — framework fixes and features arrive with composer update byjg/gluo-core; your code stays untouched
• ⚙️ PSR standards — PSR-7 (HTTP messages), PSR-11 (container), PSR-6/16 (cache)

Documentation

Getting Started

1. Installation & Setup – Install the starter, configure environments, and review prerequisites.
2. Coming from Laravel, Symfony or Drupal – Concept and command mapping, plus the four things that genuinely work differently.
3. Create Your First Table – Define your first migration and schema.
4. Add Fields – Safely evolve existing tables.
5. Create REST Endpoints – Generate REST handlers from your tables.
6. Windows Setup – WSL/Windows-specific checklist.
7. Unattended Setup – Automate installs for CI/CD pipelines.

Guides

• Frontend (Vite + React) – Run and customize the optional frontend/ SPA that talks to the API over JWT.
• REST Controllers – Define routes with PHP attributes; keep controllers thin.
• Authentication – Configure JWT login flows and RBAC enforcement.
• Database Migrations – Version and run schema migrations in every environment.
• ORM – Use MicroORM for repository and ActiveRecord patterns.
• Service Layer – Organize business logic, orchestration, and transaction boundaries.
• Repository Patterns – Implement complex queries, UUID handling, and filtering helpers.
• Template Customization – Tailor the generator templates to match your coding standards.
• Testing – Unit, integration, and contract testing with FakeApiRequester.
• JWT Authentication Advanced – Extend tokens with custom claims and refresh logic.
• Error Handling – Map exceptions to HTTP responses and logging patterns.
• Configuration – Layer configurations, secrets, and environment overrides.

Concepts

• Architecture – Architectural decisions: when to use Repository vs ActiveRecord.
• OpenAPI Integration – How swagger-php, the spec file, and Swagger UI fit together.
• Dependency Injection – PSR-11 container, environment hierarchy, and DI binding patterns.
• Request Lifecycle – Trace an HTTP request from entry point to JSON response.

Reference

• Code Generator – Automate models, repositories, services, controllers, and tests.
• Attributes – RequireAuthenticated, RequireRole, ValidateRequest, and custom attributes.
• Traits – Timestamp and soft-delete helpers for models.
• Scriptify – REPL, CLI runner, and service manager utilities.
• Components – Full PHP component dependency graph.

Real-World Example

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

Your Code vs. the Framework

The starter generates a project that is fully yours — src/, config/, db/, frontend/, docker/:

• ✅ Full control over every file the generator gave you
• ✅ Base classes are thin extension points (BaseLoginController, BaseRepository, BaseService, …) — override what you need
• ✅ Framework improvements arrive via composer update byjg/gluo-core
• ✅ Remove what you don't need — the frontend, auth, examples, and patterns are all optional

License

This project is open source. See LICENSE for details.

Dependencies

📚 Complete Component Dependency Graph →

Open source ByJG