PHPackages gemvc/library - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. gemvc/library ActiveLibrary[Framework](/categories/framework) gemvc/library ============= Server Agnostic (openSwoole/Nginx/Apache) Rest Api Microservice ready Framework/Library 5.6.6(2mo ago)221.4k17MITPHP Since Aug 18Pushed 2mo ago5 watchersCompare [ Source](https://github.com/gemvc/gemvc)[ Packagist](https://packagist.org/packages/gemvc/library)[ Docs](https://gemvc.de)[ RSS](/packages/gemvc-library/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (10)Versions (277)Used By (0) [![gemvc-tracekit](https://private-user-images.githubusercontent.com/211101824/531768259-c730d3b8-877f-4793-9261-34ca392cf692.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzU1NDU3MjUsIm5iZiI6MTc3NTU0NTQyNSwicGF0aCI6Ii8yMTExMDE4MjQvNTMxNzY4MjU5LWM3MzBkM2I4LTg3N2YtNDc5My05MjYxLTM0Y2EzOTJjZjY5Mi5qcGc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwNDA3JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDQwN1QwNzAzNDVaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1mMjk5NDMwNGNiNGJjMTAzYmQ0YmY4YjZjYjBmZTk2MjU1MmU5NzM4YTQyNjczNzlmYzE4YmYwNmZjNGU5NzcyJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.E1ro8cq4_PH8a6OGZTIO1vfBp0ZUqOvhwYSOoFWQwJo)](https://private-user-images.githubusercontent.com/211101824/531768259-c730d3b8-877f-4793-9261-34ca392cf692.jpg?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzU1NDU3MjUsIm5iZiI6MTc3NTU0NTQyNSwicGF0aCI6Ii8yMTExMDE4MjQvNTMxNzY4MjU5LWM3MzBkM2I4LTg3N2YtNDc5My05MjYxLTM0Y2EzOTJjZjY5Mi5qcGc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjYwNDA3JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI2MDQwN1QwNzAzNDVaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1mMjk5NDMwNGNiNGJjMTAzYmQ0YmY4YjZjYjBmZTk2MjU1MmU5NzM4YTQyNjczNzlmYzE4YmYwNmZjNGU5NzcyJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.E1ro8cq4_PH8a6OGZTIO1vfBp0ZUqOvhwYSOoFWQwJo) [GEMVC](https://www.gemvc.de) - The PHP Multi-Platform Microservices REST API Framework ======================================================================================= [](#gemvc---the-php-multi-platform-microservices-rest-api-framework) [![PHP Version](https://camo.githubusercontent.com/a74117f6cfdca449bfb1c98dd9f40f669e7a315e2176a439d1aac1569e30d2f1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d3737376262342e7376673f7374796c653d666c61742d737175617265266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://www.php.net/releases/)[![License](https://camo.githubusercontent.com/942e017bf0672002dd32a857c95d66f28c5900ab541838c6c664442516309c8a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![Swoole](https://camo.githubusercontent.com/1adc2279a028575b92dd52f70dcbf828d0ad8eb7c5add86e9348715c47a41654/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53776f6f6c652d537570706f727465642d677265656e2e7376673f7374796c653d666c61742d737175617265266c6f676f3d73776f6f6c65266c6f676f436f6c6f723d7768697465)](https://openswoole.com/)[![Apache](https://camo.githubusercontent.com/36f5edb22be92c2ec3e32b953f37a3fd0e30fac8a281142a1d683865f98c9e30/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4170616368652d537570706f727465642d4432323132382e7376673f7374796c653d666c61742d737175617265266c6f676f3d617061636865266c6f676f436f6c6f723d7768697465)](https://httpd.apache.org/)[![Nginx](https://camo.githubusercontent.com/929ace7e41944c526c6de318d67d51ca26de1963768b5651a82dc58b38ee0f0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4e67696e782d537570706f727465642d3030393633392e7376673f7374796c653d666c61742d737175617265266c6f676f3d6e67696e78266c6f676f436f6c6f723d7768697465)](https://nginx.org/)[![PHPStan](https://camo.githubusercontent.com/a876ed48834d76bf15693fc02b9a7410d37709300f90373958b22ecdd3f0337e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c253230392d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](https://phpstan.org/)[![PHPUnit](https://camo.githubusercontent.com/a0f9db100f7d22443debe4a69bfd889d3a002c1230f18c1e41e0a6392682b1e9/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f504850556e69742d537570706f727465642d3362386333622e7376673f7374796c653d666c61742d737175617265266c6f676f3d706870756e6974266c6f676f436f6c6f723d7768697465)](https://phpunit.de/)[![Pest](https://camo.githubusercontent.com/0489f1ff5f3810124eae4a4852602de88ae4a2414ef8cdf540bee4a8612d8435/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f506573742d537570706f727465642d707572706c652e7376673f7374796c653d666c61742d737175617265266c6f676f3d70657374266c6f676f436f6c6f723d7768697465)](https://pestphp.com/) πŸš€ Start in 30 Seconds --------------------- [](#-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. [](#stop-using-a-swiss-army-knife-when-you-need-a-scalpel-gemvc-is-a-php-multi-platformopenswoole-apache-and-nginx-specialized-ultra-lightweight-framework-designed-for-high-performance-rest-apis-and-microservices) ### Not to replace, but to complete [](#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 [](#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 [](#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 [](#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 [](#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" [](#-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 [](#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. [](#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 [](#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 [](#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! -------------------------------------- [](#-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](QUICK_START_AI.md)** - MASTER INSTRUCTIONS FOR AI ASSISTANTS [](#️-quick_start_aimd---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!** ------------------------------------------------------------------------------ [](#do-not-skip-layers-or-use-laravel-patterns-follow-gemvc-conventions-only) 🎯 What is GEMVC? ---------------- [](#-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 ------------------------ [](#️-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 ------------------------ [](#-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 [](#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 [](#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 [](#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 [](#trace-structure) ``` Root Trace (Bootstrap) └─ controller-operation (UserController::create) └─ database-query (INSERT INTO users ...) ``` All spans share the same `traceId` for complete request visibility. ### Performance [](#performance) - **Zero Overhead When Disabled** - Environment flags control tracing - **Minimal Overhead When Enabled** - ~0.25ms per request - **Non-Blocking** - Traces sent after HTTP response (fire-and-forget) ### Documentation [](#documentation) For complete APM integration guide, see **[GEMVC\_APM\_INTEGRATION.md](GEMVC_APM_INTEGRATION.md)** --- πŸ“ 4-Layer Architecture ---------------------- [](#-4-layer-architecture) ### 1. **API Layer** (`app/api/`) [](#1-api-layer-appapi) **Purpose**: URL endpoints, request validation, authentication **Naming**: PascalCase (e.g., `User.php`, `Product.php`) **Responsibilities**: - Define request schemas (`definePostSchema()`, `defineGetSchema()`) - Handle authentication (`$request->auth()`) - Delegate to Controller layer **Example** (`app/api/User.php`): ```