PHPackages cynchro/modux - 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. cynchro/modux ActiveProject[Framework](/categories/framework) cynchro/modux ============= A lightweight, dependency-injection-first PHP framework organized as a modular monolith. v2.1.0(1mo ago)24MITPHPPHP ^8.2CI passing Since Apr 25Pushed 1mo agoCompare [ Source](https://github.com/cynchro/modux)[ Packagist](https://packagist.org/packages/cynchro/modux)[ RSS](/packages/cynchro-modux/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (19)Versions (11)Used By (0) Modux ===== [](#modux) A production-ready PHP modular monolith framework. Each business domain lives in its own self-contained module. No facades, no magic statics, no hidden globals — every dependency is explicit and injected. **Best for:** teams that want full control over their codebase, clear request lifecycles, and testable code without learning a large framework's conventions. --- At a glance ----------- [](#at-a-glance) ``` Request → Kernel → Global pipeline (CORS, RequestSize, SecurityHeaders, Logger) → Route middlewares (Auth?, Admin?, Tenant?) → Controller (typed injection via reflection) → Response (always JSON, never echo+exit) ``` - **Zero magic** — no facades, no service locator calls in business code - **PSR-11 container** with reflection-based autowiring and `makeWith` for parameterized resolution - **PSR-3 structured logger** — JSON to file or stderr, falls back silently - **Middleware pipeline** — composable per-route and per-group, immutable via clone - **FormRequest** — validates on construction, throws `ValidationException` (422) automatically - **Exception hierarchy** — typed exceptions map directly to HTTP status codes - **JWT + refresh token rotation** — opaque refresh tokens, per-user revocation - **Rate limiting** — `CacheInterface`-backed (APCu in production, Array in tests), graceful no-op - **RBAC** — `PermissionMiddleware` checks `roles_permisos` at runtime via parameterized middleware - **Event system** — synchronous `EventDispatcher` with `listen()` / `dispatch()` - **Multi-tenancy** — row-level isolation via `TenantMiddleware` + JWT `tenant_id` claim (optional) - **Versioned migrations** — tracked with batch numbers, supports `rollback` and `fresh` - **152 unit tests**, PHPStan level 6 clean, PHPCS PSR-12 --- Requirements ------------ [](#requirements) - PHP 8.2+ - MySQL 8.0+ (or any PDO-compatible database) - Composer --- Installation ------------ [](#installation) Create a new project from the [Packagist](https://packagist.org/packages/cynchro/modux)skeleton (recommended): ``` composer create-project cynchro/modux my-app cd my-app cp .env.example .env # Edit .env — see Environment Variables ``` > To contribute to the framework itself instead, clone the repo: `git clone https://github.com/cynchro/modux.git && cd modux && composer install` --- Quick start ----------- [](#quick-start) ``` # 1. Configure environment cp .env.example .env # Set JWT_SECRET, DB_HOST, DB_NAME, DB_USER, DB_PASS # 2. Run migrations php modux migrate # 3. Start the server php -S localhost:8080 -t public/ ``` ``` # Login curl -X POST http://localhost:8080/auth/login \ -H "Content-Type: application/json" \ -d '{"usuario":"admin@admin.com","clave":"admin123"}' ``` ``` { "success": true, "data": { "access_token": "eyJ0eXAiOiJKV1QiLCJhbGci...", "refresh_token": "a8f3c1d9e..." } } ``` ``` # Health check curl http://localhost:8080/health ``` ``` { "success": true, "data": { "status": "ok", "php": "8.2.0", "checks": { "db": "ok", "cache": "ok" } } } ``` --- Project structure ----------------- [](#project-structure) ``` ├── app/ │ ├── Exceptions/ # Exception hierarchy + global JSON handler │ ├── Helpers/ # PaginatorHelper, EmailHelper │ ├── Http/ │ │ ├── Controllers/ # Infrastructure controllers (HealthController, LogsController) │ │ └── Middleware/ # CorsMiddleware, AuthMiddleware, AdminMiddleware, │ │ # TenantMiddleware, PermissionMiddleware, │ │ # SecurityHeadersMiddleware, RequestSizeLimitMiddleware, │ │ # RequestLoggerMiddleware │ ├── Modules/ # Business domain modules │ │ └── {Name}/ │ │ ├── Controllers/ │ │ ├── Repositories/ │ │ ├── Requests/ # Extend FormRequest │ │ ├── Services/ │ │ ├── ServiceProvider.php # Optional — auto-discovered at boot │ │ └── routes.php │ └── Support/ # Framework core │ ├── Cache/ # ApcuCache, ArrayCache (implement CacheInterface) │ ├── Config.php # Static config loader (config/*.php files) │ ├── Container.php # PSR-11 DI container with autowiring + makeWith │ ├── DB.php # withTransaction() helper │ ├── EventDispatcher.php # Synchronous event bus │ ├── FormRequest.php # Validated request base class │ ├── JWTConfig.php # JWT encode/decode/refresh helpers │ ├── Kernel.php # HTTP kernel — creates Request, dispatches │ ├── Logger.php # PSR-3 structured JSON logger │ ├── LogReader.php # Reads and parses app.log │ ├── Pipeline.php # Immutable middleware pipeline │ ├── RateLimiter.php # CacheInterface-backed rate limiting │ ├── Request.php # HTTP request wrapper │ ├── Response.php # Immutable JSON response (with getHeaders()) │ ├── Roles.php # Role constants (ADMIN, USER) │ ├── Router.php # Route registration + dispatch + prefix groups │ ├── ServiceProvider.php # Base provider (register/boot lifecycle) │ ├── UUIDGenerator.php # UUID v4 generation │ ├── Validator.php # Validation engine │ └── Contracts/ # CacheInterface, MiddlewareInterface, ServiceProviderInterface ├── modux # CLI entry point ├── bootstrap/ │ ├── app.php # Boot sequence (9 stages) │ └── test.php # Test bootstrap (skips HTTP dispatch) ├── config/ │ ├── app.php # App settings, trusted proxies, request size │ ├── auth.php # JWT secret, TTL, algorithm │ ├── cors.php # Allowed origins, methods, headers │ ├── database.php # PDO connection config │ ├── logging.php # Channel, driver, level, path │ └── mail.php # SMTP settings ├── migrations/ # 0001_*.php, 0002_*.php, ... ├── public/index.php # 3-line entry point ├── seeders/ └── tests/ ├── Feature/ # Full HTTP dispatch, real DB, transaction rollback └── Unit/ # Mocked repositories, no DB ``` --- Documentación ------------- [](#documentación) El manual completo vive en [`docs/`](docs/). Esta página es solo el quickstart; cada tema en profundidad está en su propio archivo: - [CLI — `php modux`](docs/cli.md) — `make:module`, `make:migration`, `migrate`, `routes`. - [Módulos, ruteo y arranque](docs/modules.md) — secuencia de boot, crear un módulo (Repository/Service/Controller/ServiceProvider), grupos de rutas. - [HTTP](docs/http.md) — Request API, Response API, validación de requests, excepciones → HTTP, middleware. - [Auth & multi-tenancy](docs/auth-and-tenancy.md) — login/refresh/logout, impersonación, API keys, firmas de webhooks, contenedor DI, aislamiento por tenant. - [Infraestructura](docs/infrastructure.md) — config, logger, paginación, migraciones, testing y quality gate. - [Plataforma](docs/platform.md) — eventos, RBAC, entitlements, metering/cuotas, transacciones, cola de jobs, health check, variables de entorno. - [Módulos opcionales](docs/optional-modules.md) — IA (LLM + RAG) y Billing (Stripe / Mercado Pago). Performance ----------- [](#performance) Measured on the production image (PHP 8.2 + Apache/mod\_php, MySQL 8.0) with ApacheBench at concurrency 50: EndpointWhat it measuresReq/sp50p95p99`GET /`Framework overhead (routing + DI + middleware pipeline)~3,52013 ms21 ms27 ms`GET /health`Framework + one `SELECT 1` round-trip~1,91025 ms38 ms45 msAbout **0.28 ms of framework overhead per request**, zero failed requests under load. Numbers are indicative (single containerized host) and vary with hardware and workload. --- License ------- [](#license) MIT --- Contact ------- [](#contact) **** · [cynchrolabs.com.ar](https://www.cynchrolabs.com.ar) Buy me a coffee? ---------------- [](#buy-me-a-coffee) If Modux saved you time, consider a donation — it helps keep the project going. [ ![Donate with PayPal](https://camo.githubusercontent.com/b87a2b5e0466bc78ff42eb9bdea05152341d203d917b0e6f1af2b225cd2d8e17/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f50617950616c2d446f6e6174652d626c75653f6c6f676f3d70617970616c)](https://www.paypal.com/donate/?hosted_button_id=YX332RT7KSJ4Q)--- ⭐ If you like this project, give it a star! [ ![GitHub stars](https://camo.githubusercontent.com/e7a3e2deefb119550bc94814d39c60451f6916764fdadae29a22d208cdf2d9c6/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f63796e6368726f2f6d6f6475783f7374796c653d736f6369616c)](https://github.com/cynchro/modux) ### Health Score 41 — FairBetter than 87% of packages Maintenance91 Actively maintained with recent releases Popularity6 Limited adoption so far Community6 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~6 days Total 9 Last Release 44d ago Major Versions v1.2.0 → v2.0.02026-06-09 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/22827205?v=4)[cynchro](/maintainers/cynchro)[@cynchro](https://github.com/cynchro) --- Top Contributors [![cynchro](https://avatars.githubusercontent.com/u/22827205?v=4)](https://github.com/cynchro "cynchro (99 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP\_CodeSniffer Type Coverage Yes ### Embed Badge ![Health badge](/badges/cynchro-modux/health.svg) ``` [![Health](https://phpackages.com/badges/cynchro-modux/health.svg)](https://phpackages.com/packages/cynchro-modux) ``` ### Alternatives [laravel/framework The Laravel Framework. 34.8k543.8M20.5k](/packages/laravel-framework)[tempest/framework The PHP framework that gets out of your way. 2.2k34.4k16](/packages/tempest-framework)[matomo/matomo Matomo is the leading Free/Libre open analytics platform 21.7k38.9k](/packages/matomo-matomo)[typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 751291.4k46](/packages/civicrm-civicrm-core)[typo3/cms-core TYPO3 CMS Core 3713.2M5.2k](/packages/typo3-cms-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)