PHP Micro-Framework
for JSON APIs
API first. OpenAPI contracts. JWT auth. MCP integration.
Designed for AI-readable, production-ready delivery.
PHP 8.4+ · MIT License · Available on Packagist
Everything you need to ship a JSON API
No magic conventions. No hidden control flow. Just the pieces you need — routing, middleware, DI, database, auth.
API First
Define behavior through clear HTTP boundaries and OpenAPI 3.1 contracts. RFC 9457 Problem Details on every error.
Auth Built In
Bearer JWT middleware with allowlist/blocklist. CompositeAuthMiddleware for three-tier access models (public / Bearer / API key).
MCP Ready
Local MCP server backed by your OpenAPI contract. Listed on Smithery. Read/write tools with authentication guard.
PSR Standards
PSR-7/15/17 HTTP runtime. PSR-11 dependency injection. PSR-3 structured logging. Swap any layer without surgery.
AI-Readable
Small classes, typed boundaries, explicit routing, no magic. llms.txt included. Every decision recorded in ADRs.
Frontend Ready
React + TypeScript + Vite starter included. Typed fetch API client. Frontend layer fully decoupled from backend runtime.
Database Layer
PDO adapters for SQLite and MySQL. Phinx migrations. Repository interfaces keep domain code DB-independent.
Production Quality
PHPStan level 8. PHP-CS-Fixer. PHPUnit contract tests. OpenAPI validation. Rate limiting. DB health checks.
Explicit by design
Routing, DI wiring, and middleware order are all readable in one place. Handler → UseCase → Repository is the only allowed data flow direction.
- ✓ PSR-7/15/17 HTTP runtime — swap any layer freely
- ✓ RFC 9457 Problem Details on every error response
- ✓ Layered validation: Middleware -> Controller -> UseCase
- ✓ Typed config objects — no raw getenv() in app code
- ✓ OpenAPI contract tests baked into CI
// Wire the PSR-15 middleware stack
$app = RuntimeApplicationFactory::create(
auth: new BearerTokenMiddleware(
new LocalBearerTokenVerifier($secret),
prefixPaths: ['/api'],
),
rateLimiter: new ThrottleMiddleware(
new InMemoryRateLimitStorage(),
limit: 60, window: 60,
),
);
// Explicit route table -- no annotation scanning
$app->get('/health', HealthHandler::class);
$app->post('/api/notes', CreateNoteHandler::class);
$app->get('/api/notes/{id}', GetNoteByIdHandler::class);
$app->run();// docs/mcp/tools.json -- tool catalog
{
"tools": [
{
"name": "list_notes",
"safety_level": "read",
"operationId": "listNotes"
},
{
"name": "create_note",
"safety_level": "write",
"requires_auth": true
}
]
}
# Start local MCP server
$ docker compose run --rm app \
php tools/local-mcp-server.phpBuilt for AI tooling
NENE2 includes a local MCP server backed by your OpenAPI contract. Read/write tools with authentication guards — listed on Smithery.
- llms.txt included — machine-readable project summary
- Tool catalog in docs/mcp/tools.json, validated in CI
- Write tools require Bearer JWT — read tools are public
- Listed on Smithery MCP registry
- OpenAPI contract -> Swagger UI -> MCP tools pipeline
Quick Start
From zero to running API in minutes.
Clone & configure
git clone https://github.com/hideyukiMORI/NENE2.git my-project
cd my-project && cp .env.example .envBuild & install
docker compose build
docker compose run --rm app composer installRun checks
docker compose run --rm app composer check
# PHPUnit · PHPStan level 8 · CS-Fixer · OpenAPI · MCPStart the server
docker compose up -d app
curl http://localhost:8080/health
curl http://localhost:8080/examples/pingOr as a Composer dependency:composer require hideyukimori/nene2
100+ Task-Focused How-to Guides
Every major API pattern documented with field-trial validated examples and reference implementations.
Auth
- ›JWT authentication
- ›API key management
- ›RBAC
- ›Multi-tenant isolation
- ›OAuth2 social login
- ›TOTP 2FA
- + more…
Security
- ›SQL injection prevention
- ›CSRF & JSON APIs
- ›Account lockout
- ›Signed URLs
- ›Data masking
- ›Webhook signature
- + more…
Database
- ›Transactions
- ›Optimistic locking
- ›Soft delete
- ›FTS5 search
- ›Prevent double booking
- ›Use PostgreSQL
- + more…
API Design
- ›Pagination
- ›Rate limiting
- ›API versioning
- ›ETag & conditional
- ›Content negotiation
- ›Idempotency
- + more…
Product Features
- ›Activity feed
- ›Comment threads
- ›Voting system
- ›Subscription plans
- ›Shopping cart
- ›User follow system
- + more…
Infrastructure
- ›Job queue
- ›Circuit breaker
- ›Event sourcing
- ›Feature flags
- ›Audit trail
- ›File upload
- + more…
73 Reference Implementations
Every how-to guide has a matching runnable app in
NENE2-examples.
Each is composer install && phpunit ready.
Design Principles
No magic
Routing, DI wiring, and middleware order are all explicit and readable in one place. No annotation scanning.
Thin controllers
Handler → UseCase → Repository is the only allowed data flow direction. Handlers stay small.
RFC 9457 errors
Every error response is structured Problem Details JSON, including validation failures and auth errors.
Swap any layer
PSR-7/15/17 interfaces mean you can replace HTTP, logging, or DI without touching business logic.
OpenAPI as contract
The OpenAPI document is the authoritative API contract. Contract tests run in CI to keep it honest.
AI-readable by design
Small files, typed boundaries, no global state, and ADRs for every non-obvious decision. llms.txt included.
Ready to build?
Clone the repository or add NENE2 as a Composer dependency. Everything you need is in one repository.