GEMVC - The PHP Multi-Platform Microservices REST API Framework

🚀 Start in 30 Seconds

composer require gemvc/library
php vendor/bin/gemvc init

Stop using a Swiss Army Knife when you need a Scalpel. GEMVC is a PHP Multi-Platform(OpenSwoole, Apache and NginX) specialized, ultra-lightweight framework designed for high-performance REST APIs and Microservices.

Not to replace, but to complete

GEMVC is not a replacement for lovely Laravel or powerful Symfony; it is a complementary tool designed to solve special challenges. It is always good to have it in your arsenal!

You are the Master of your Code

In GEMVC, architecture is just a recommendation. GEMVC NEVER forces you to follow its rules. You can implement the recommended 4-layer architecture, or write your own familiar 3, 2, or even single-layer code!

AI-Ready - Born for AI Agents

Thanks to its transparent structure, strict naming conventions, and clean 4-layer separation of concerns (with no magic functions or hidden classes), GEMVC is natively AI-Friendly. AI Assistants can easily understand your code context and assist you efficiently. Writing code with GEMVC is a joy for both humans and AI. GEMVC is designed to work seamlessly with Cursor, Copilot, and ChatGPT. We include pre-configured context files (AI_API_REFERENCE.md, .cursorrules) right in the root. Your AI assistant already knows how to write GEMVC code perfectly!

Easy to Learn

It takes only a couple of hours to master this tool. GEMVC respects your time and is not here to replace your existing knowledge, but to sharpen it.

No-Hassle Documentation

In GEMVC, Sanitization IS Documentation. When you sanitize API inputs (as you normally should), the framework automatically generates full documentation for your endpoints. You get beautiful, well-designed documentation simply by defining your validation rules. Plus, you get out-of-the-box support to export your latest API version to Postman with a single click. Your frontend developers will love GEMVC!

⚡ The "Async Magic"

Write standard, synchronous PHP code (like you always do) on Apache/Nginx. Switch to OpenSwoole, and your exact same code automatically runs as Asynchronous Non-blocking I/O. Zero code changes required.

Fully and Easily Customizable

You can easily define custom Class Templates for any layer, and then CLI Commands will generate your classes in seconds!

Library or Framework? The Choice is Yours.

You can use GEMVC as a library within a legacy project to migrate to a modern architecture step-by-step, without breaking existing functionality. Or, for new projects, simply install it via Composer and run the gemvc init command to use it as a modern framework from day one.

Testing & Quality Assurance

When coding with GEMVC, you can enjoy PHPStan Level 9 compliance! The framework natively supports strong typing—while not forced, it is strongly recommended. It also comes with PHPUnit and Pest support right out of the box during the installation process. You can easily test your product using your beloved PHPUnit or the beautiful Pest framework. Plus, the 4-layer architecture makes creating comprehensive Unit and Integration tests a breeze.

Full Transparency Policy

It is Open Source, MIT Licensed, and small. There is no hidden code or "black box". You can download the source code, analyze it, test it, and use it with peace of mind. It is built with love to make your life as a developer more enjoyable.

---

🤖 FOR AI ASSISTANTS - READ THIS FIRST!

ATTENTION: If you are an AI assistant (Cursor AI, GitHub Copilot, Claude, etc.), you MUST read the following file first:

GEMVC is NOT Laravel or Symfony - It has its own unique architecture, naming conventions, and design philosophy. This guide will teach you how to write code the GEMVC way.

⚠️ QUICK_START_AI.md - MASTER INSTRUCTIONS FOR AI ASSISTANTS

This file will:

1. ✅ Instruct you to read ALL GEMVC documentation files
2. ✅ Teach you the complete 4-layer architecture (MANDATORY)
3. ✅ Show you correct method signatures and return types
4. ✅ Explain security features (90% automatic)
5. ✅ Provide code generation patterns you MUST follow
6. ✅ List common mistakes you MUST avoid

After reading QUICK_START_AI.md, you should read:

• .cursorrules - Complete framework rules
• AI_API_REFERENCE.md - All method signatures
• AI_CONTEXT.md - Quick examples
• GEMVC_GUIDE.md - Code generation patterns

Do NOT skip layers or use Laravel patterns. Follow GEMVC conventions only!

🎯 What is GEMVC?

GEMVC is a multi-platform PHP REST API framework that works identically on:

• ✅ OpenSwoole (async, WebSocket, hot reload)
• ✅ Apache (traditional PHP-FPM)
• ✅ Nginx (high performance, reverse proxy)

Key Features:

• 🔒 90% Security Automatic - Input sanitization, SQL injection prevention, path protection
• 🌐 Webserver-Agnostic - Same code works on all platforms
• 🛠️ CLI Code Generation - Generate Services, Controllers, Models, Tables
• 📝 Simple API - Clean, straightforward code structure
• ⚡ High Performance - Connection pooling, async capabilities
• ✅ PHPStan Level 9 - Write type-safe, bug-free code with the highest static analysis level
• 📊 Native APM Integration - Automatic Application Performance Monitoring with zero configuration
  • Automatic request tracing (root spans)
  • Controller operation tracing (optional)
  • Database query tracing (optional)
  • Environment-controlled via .env flags
  • Works with any APM provider (TraceKit, Datadog, New Relic, etc.)
  • Fire-and-forget pattern (zero performance impact)
• 📈 Server Monitoring - Built-in RAM, CPU, network, and database metrics

---

🏗️ Architecture Overview

GEMVC uses a 4-layer architecture pattern:

API Layer (app/api/)          → URL endpoints, schema validation
    ↓
Controller Layer (app/controller/) → Business logic orchestration
    ↓
Model Layer (app/model/)      → Data logic, validations
    ↓
Table Layer (app/table/)      → Database access, queries

Example Flow:

POST /api/User/create
    ↓
app/api/User.php::create()        → Validates schema
    ↓
app/controller/UserController.php  → Handles business logic
    ↓
app/model/UserModel.php           → Data validations, transformations
    ↓
app/table/UserTable.php           → Database operations

---

📊 Native APM Integration

GEMVC includes native Application Performance Monitoring (APM) integration that works automatically with zero code changes. The APM system captures the full request lifecycle and provides deep insights into your application's performance.

Key Features

✅ Automatic Root Trace - Captures full request lifecycle from Bootstrap
✅ Controller Tracing - Automatic spans for controller operations (optional)
✅ Database Query Tracing - Automatic spans for all SQL queries (optional)
✅ Exception Tracking - Automatic exception recording in traces
✅ Environment-Controlled - Enable/disable via .env variables
✅ Zero Performance Impact - Fire-and-forget pattern, traces sent after HTTP response
✅ Provider-Agnostic - Works with any APM provider (TraceKit, Datadog, New Relic, etc.)

Quick Setup

1. Install APM Provider:

composer require gemvc/apm-tracekit

2. Configure Environment:

APM_NAME=TraceKit
TRACEKIT_API_KEY=your-api-key
TRACEKIT_API_URL=https://app.tracekit.dev/v1/traces

# Optional: Enable controller and database tracing
APM_TRACE_CONTROLLER=1
APM_TRACE_DB_QUERY=1

3. Use callController() in API Services:

// app/api/User.php
public function create(): JsonResponse
{
    // Automatic controller tracing (if APM_TRACE_CONTROLLER=1)
    return $this->UserController->create();
}

Note: You can still use $this->callController(new UserController($this->request)) if you prefer, but the magic property syntax is recommended.

4. Use createModel() in Controllers:

// app/controller/UserController.php
public function create(): JsonResponse
{
    // Automatic Request propagation for database tracing
    $model = $this->createModel(new UserModel());
    // ... rest of code
}

That's it! APM tracing works automatically. No code changes needed beyond using callController() and createModel().

What Gets Traced

• Root Request - Full request lifecycle (automatic)
• Controller Operations - Method calls with response codes (if APM_TRACE_CONTROLLER=1)
• Database Queries - All SQL queries with execution time (if APM_TRACE_DB_QUERY=1)
• Exceptions - All exceptions automatically recorded

Trace Structure

Root Tr