Pular para o conteúdo principal

Gluo — PHP REST API Starter

Sponsor Build Status Opensource ByJG GitHub source GitHub license GitHub release

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) — controllers, models, config, migrations, Docker files. 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​

# Create your project
composer create-project byjg/gluo my-api ^7.0

# Start containers
cd my-api
docker compose 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​

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
  • 🐳 Docker ready — MySQL, PHP-FPM, and Nginx 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)
# Generate a complete CRUD API from a single table
composer codegen -- --env=dev --table=products all --save

Documentation​

Getting Started​

  1. Installation & Setup – Install the starter, configure environments, and review prerequisites.
  2. Create Your First Table – Define your first migration and schema.
  3. Add Fields – Safely evolve existing tables.
  4. Create REST Endpoints – Generate REST handlers from your tables.
  5. Windows Setup – WSL/Windows-specific checklist.
  6. Unattended Setup – Automate installs for CI/CD pipelines.

Guides​

  • 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​

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​

# 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. Generate the OpenAPI spec so routing is active
composer run openapi

# 5. Log in and capture the token
TOKEN=$(curl -s -X POST http://localhost:8080/login \
  -H "Content-Type: application/json" \
  -d '{"username":"[email protected]","password":"!P4ssw0rdstr!"}' \
  | jq -r '.token')

# 6. Call your new endpoint
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8080/products | jq

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​

Your Code vs. the Framework​

The starter generates a project that is fully yours — src/, config/, db/, 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 — 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