{"id":45476678,"url":"https://github.com/k2gl/pragmatic-franken","last_synced_at":"2026-02-22T15:30:38.968Z","repository":{"id":336364436,"uuid":"1149131280","full_name":"k2gl/pragmatic-franken","owner":"k2gl","description":"🧑‍💻 Pragmatic Franken is a no-compromise skeleton template for building high-performance PHP applications with Symfony and FrankenPHP","archived":false,"fork":false,"pushed_at":"2026-02-13T17:15:55.000Z","size":16369,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-14T00:42:42.124Z","etag":null,"topics":["clean-architecture","ddd-architecture","frankenphp","modular-monolith","php85","symfony-skeleton","vibe-coding"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k2gl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-03T18:55:40.000Z","updated_at":"2026-02-13T17:15:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/k2gl/pragmatic-franken","commit_stats":null,"previous_names":["k2gl/v2","k2gl/pragmatic-franken"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/k2gl/pragmatic-franken","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k2gl%2Fpragmatic-franken","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k2gl%2Fpragmatic-franken/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k2gl%2Fpragmatic-franken/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k2gl%2Fpragmatic-franken/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k2gl","download_url":"https://codeload.github.com/k2gl/pragmatic-franken/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k2gl%2Fpragmatic-franken/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29717220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T15:10:41.462Z","status":"ssl_error","status_checked_at":"2026-02-22T15:10:04.636Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clean-architecture","ddd-architecture","frankenphp","modular-monolith","php85","symfony-skeleton","vibe-coding"],"created_at":"2026-02-22T15:30:38.240Z","updated_at":"2026-02-22T15:30:38.961Z","avatar_url":"https://github.com/k2gl.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧑‍💻 Pragmatic Franken 🧟\n\n[![License MIT](https://img.shields.io/badge/License-MIT-yellowgreen)](https://opensource.org/licenses/MIT)\n[![PHP 8.5](https://img.shields.io/badge/PHP-8.5-777bb4?logo=php\u0026logoColor=white)](https://www.php.net/releases/8.5/)\n[![FrankenPHP 1.x](https://img.shields.io/badge/FrankenPHP-1.x-006b5b?logo=docker\u0026logoColor=white)](https://frankenphp.dev/)\n[![Symfony 8.0](https://img.shields.io/badge/Symfony-8.0-000000?logo=symfony\u0026logoColor=white)](https://symfony.com/)\n[![PHPStan Level 9](https://img.shields.io/badge/PHPStan-Level%209-cyan)](https://phpstan.org)\n[![CI Pipeline](https://img.shields.io/github/actions/workflow/status/k2gl/pragmatic-franken/ci.yml?branch=main\u0026label=CI)](https://github.com/k2gl/pragmatic-franken/actions)\n[![AI-Ready](https://img.shields.io/badge/AI--Ready-gold)](#)\n\n---\n\n## 🛸 Why Pragmatic Franken?\nBuild robust, high-performance Modular Monoliths while your AI Agent does the heavy lifting.\n\n| Problem | Solution |\n|---------|----------|\n| Complex layered architecture | **Vertical Slices** — code grouped by business value |\n| Nginx + FPM configuration hell | **FrankenPHP Worker Mode** — one binary, HTTP/3, 2ms latency |\n| AI generates spaghetti code | **AI-Native structure** — agents understand context instantly |\n| Code review debates | **Pint + PHPStan Level 9** — tools decide, humans review logic |\n| Fear of deletion | **Rule of Deletion** — optimized for removal, not reuse |\n\n---\n\n## 🥰 Quick Start\n```bash\n# Here the PHP Cheat Code for 2026\n\n# 1. Clone and ignite\ngit clone https://github.com/k2gl/pragmatic-franken.git \u0026\u0026 cd pragmatic-franken\n\n# 2. The Magic Command\nmake install\n```\n\n**Boom!** Your app is live at https://localhost with automatic HTTPS.\n\n---\n\n## 🦸 AI-First DX (Killer Feature!)\n\nThis repo is **Agent-Native**. OpenCode, Cursor, Windsurf, and Copilot understand your architecture better than you do.\n\n```bash\n@AGENTS.md Implement a new 'Subscription' module following our architecture.\n```\n\nThe AI Agent will:\n1. **Analyze ADRs** — Reads architecture decisions for consistency\n2. **Scaffold \u0026 Code** — Creates folders per Vertical Slice patterns\n3. **Verify** — Runs `make check` to ensure nothing is broken\n4. **Deliver** — Prepares a PR, ready for your review\n\n**First Feature:** Try implementing real business logic (**Telegram auth**, **Stripe integration**) using `@AGENTS.md`. **You'll be amazed how simple it became.**\n\n---\n\n## 🛡 Bulletproof Quality\n\n| Check | Tool | Command |\n|-------|------|---------|\n| Code Style | **Pint** | `make lint` |\n| Static Analysis | **PHPStan Level 9** | `make analyze` |\n| Tests | **PHPUnit** | `make test` |\n| All Checks | **CI Pipeline** | `make check` |\n\n---\n\n## 🐘 Zero Infrastructure Pain\n\n| Feature | Traditional | Pragmatic Franken |\n|---------|------------|-------------------|\n| Web Server | Nginx + FPM | **FrankenPHP** (single binary) |\n| Latency | ~50-100ms | **~2ms** (Kernel stays in memory) |\n| HTTP Protocol | HTTP/1.1 | **HTTP/3** (built-in) |\n| Configuration | 5 config files | **One Caddyfile** |\n\n---\n\n## ⚖️ Legacy vs Pragmatic\n\n| Layer | Legacy | Pragmatic |\n|-------|--------|-----------|\n| Web Server | Nginx + FPM | **FrankenPHP** |\n| Process Manager | Supervisord | **Worker Mode** |\n| Scheduler | Crontab | **Symfony Scheduler** |\n| Graceful Shutdown | Manual config | **Out of the box** |\n\n**4 configs = 4 failure points. 1 Caddyfile = 1 source of truth.**\n\n---\n\n## 📊 Performance\n\nFrankenPHP Worker Mode vs PHP-FPM benchmarks:\n\n| Metric | PHP-FPM | FrankenPHP Worker | Source |\n|--------|----------|-------------------|---------|\n| Cold Boot | ~150ms | ~10ms | [FrankenPHP](https://frankenphp.dev/docs/benchmarks/) |\n| Requests/sec | ~500 | ~8,000 | [TechEmpower](https://www.techempower.com/benchmarks/) |\n\n*[Full benchmarks →](docs/PERFORMANCE.md)*\n\n---\n\n## 𓂃✍︎ Architecture Decision Records\nWe don't do \"because I said so\". Every decision is documented:\n\n| ADR | Topic | Priority |\n|-----|-------|----------|\n| [0001](docs/adr/0001-vertical-slices.md) | Vertical Slices Architecture | P0 |\n| [0002](docs/adr/0002-messenger-transport.md) | Messenger Transport (CQRS) | P0 |\n| [0003](docs/adr/0003-pragmatic-symfony-architecture.md) | Pragmatic Symfony | P0 |\n| [0004](docs/adr/0004-frankenphp-runtime.md) | FrankenPHP Runtime | P1 |\n| [0005](docs/adr/0005-health-checks.md) | Health Checks | P1 |\n| [0006](docs/adr/0006-memory-management.md) | Memory Management | P2 |\n| [0007](docs/adr/0007-asset-mapper.md) | AssetMapper | P2 |\n| [0008](docs/adr/0008-testing-strategy.md) | Testing Strategy (PHPUnit) | P1 |\n| [0009](docs/adr/0009-shared-architecture.md) | Shared Architecture | P1 |\n\n---\n\n## 📁 Architecture: Vertical Slices \u0026 Modular Monolith v2.0\nWe don't do \"folders by type\" (all controllers in one place, all models in another). That's 2010. We group by Business Value.\n\n```\nsrc/\n├── Kernel.php              # System core (Symfony MicroKernel)\n├── Shared/                 # Global Shared (infrastructure only)\n│   ├── Infrastructure/\n│   │   ├── Bus/           # Messenger configuration\n│   │   ├── Persistence/   # Doctrine extensions\n│   │   └── Logging/       # Sentry, monitoring\n│   └── Domain/\n│       ├── ValueObject/    # Global value objects\n│       └── Exception/      # Base exceptions\n│\n├── User/                   # Module (Bounded Context)\n│   ├── Entity/            # User.php\n│   ├── Enum/              # UserRole.php\n│   ├── Service/           # PasswordHasher.php\n│   ├── Events/            # UserRegisteredEvent.php\n│   ├── Repositories/\n│   └── Features/           # Vertical Slices (Business logic here 👇)\n│       └── {FeatureName}/\n│           ├── {FeatureName}Action.php     # Entry point (HTTP/CLI)\n│           ├── {FeatureName}Handler.php    # Business logic\n│           ├── {FeatureName}Dto.php        # Data transfer\n│           └── {FeatureName}Test.php       # Local feature test\n│\n├── Task/                   # Module (same pattern)\n├── Board/                  # Module (same pattern)\n└── Health/                 # Technical feature (same pattern)\n```\n\n\u003e **See [ADR-0009](docs/adr/0009-shared-architecture.md) for Shared architecture rules.**\n\n### 🍑 Why this kicks ass:\n1. **Locality of Change:** Want to change \"User Registration\"? Everything is in one folder. No jumping around 10 directories.\n2. **Zero Side Effects:** Delete a folder — the entire feature is gone. No ghost code left behind.\n3. **AI-Friendly:** Your AI Agent finds context instantly. It doesn't have to scan the whole src/Controllers folder to find one specific action.\n4. **Low Cognitive Load:** You focus on the feature, not the framework.\n\n### 🛣️ The Pragmatic Way\n\nHow we write code:\n\n1. Create a Feature Slice\n2. Define a Command or Query\n3. Handle it\n\n**No over-engineering.**\n\n### ⚡️ DX \u0026 Scaffolding\nStop wasting time on boilerplate. Use our generators to keep the architecture clean and consistent:\n\n```bash\n# Create a new Vertical Slice (Action + Handler + DTO + Test)\nmake slice module=Billing feature=Subscribe\n```\n\n---\n\n## 🔄 Deep Dive\n\n```mermaid\nflowchart TD\n    A[HTTP Request] --\u003e B[Controller / EntryPoint]\n    B --\u003e C[Command / Query]\n    C --\u003e D[Handler]\n    D --\u003e E[Entity / Domain]\n    D --\u003e F[Repository]\n    E --\u003e G[Domain Event]\n    G --\u003e H[Event Bus]\n    H --\u003e I[Async Handlers]\n    H --\u003e J[Mercure / Real-time]\n\n    subgraph Persistence\n        F --\u003e K[(PostgreSQL)]\n    end\n\n    subgraph Cache\n        D --\u003e L[(Redis)]\n    end\n```\n\n**See [ADR 0002](docs/adr/0002-messenger-transport.md) for Message Bus implementation details.**\n\n---\n\n## 📚 Guides\n\n- [Development Guide](docs/guides/development.md)\n- [Testing Guide](docs/guides/testing.md)\n- [Worker Mode Guide](docs/guides/worker-mode.md)\n- [AI Agent Setup](docs/guides/agent-setup.md)\n\n---\n\n## 🗓️ Roadmap 2026\n\n| Quarter | Focus | What's Coming |\n|---------|-------|---------------|\n| **Q1** | Real-time \u0026 Connectivity | Mercure Hub, Event Sourcing Lite, TypeScript SDK Generator |\n| **Q2** | AI \u0026 Agentic Autonomy | Self-Healing CI, Interactive Scaffolding, Context Injection |\n| **Q3** | Edge \u0026 Performance | Static Binary Builds, Memory Management, SQLite + Litestream |\n| **Q4** | Frontend \u0026 Ecosystem | HTMX/LiveWire Presets, Public Templates Marketplace |\n\n[See full Roadmap →](docs/ROADMAP.md)\n\n---\n\n## 🫵 Contributing\n\nSee [Contributing Guidelines](.github/CONTRIBUTING.md) for details.\n\n---\n\n**Build for 2026, not 2015. FrankenPHP is the engine, Symfony is the brain, AI is the hands.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk2gl%2Fpragmatic-franken","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk2gl%2Fpragmatic-franken","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk2gl%2Fpragmatic-franken/lists"}