README

PHP micro-framework: JSON APIs first, minimal server HTML, easy React starter integration, structure friendly to AI tooling.

OpenAPI contract — machine-readable API spec (OpenAPI 3.1). Live Swagger UI at http://localhost:8080/docs/ after docker compose up -d app.

NENE2 is a small, modern PHP framework foundation designed for projects that want to ship JSON APIs quickly, keep server-rendered HTML thin, and add a React frontend starter without turning the backend into frontend build glue.

The v1.x foundation covers full Note/Tag CRUD, Bearer JWT auth, pagination helpers, and a six-language VitePress documentation site, with opt-in rate limiting and database health checks as production-ready opt-in features. A maintainer can clone the repository, run a local API, share an OpenAPI contract, expose safe MCP tools through the API boundary, and verify database behavior in Docker Compose.

Theme

API first: define behavior through clear HTTP boundaries and OpenAPI contracts.
Simple HTML: keep server HTML minimal, predictable, and easy to replace with SPA shells.
Frontend ready: provide a React + TypeScript starter direction while keeping the frontend layer replaceable.
AI readable: prefer explicit directories, small classes, typed boundaries, and documented decisions.
LLM delivery ready: keep API, MCP, auth, database, and handoff docs aligned for small client-style projects.
Modern PHP: use strict types, PSR-oriented style, dependency injection, automated tests, and static analysis.

Current Capabilities

The foundation currently includes:

PSR-7 / PSR-15 / PSR-17 HTTP runtime with explicit routing and middleware.
OpenAPI contract, Swagger UI, and runtime contract tests for shipped JSON endpoints.
RFC 9457 Problem Details error responses.
Typed app and database configuration through .env loading boundaries.
PSR-11 dependency injection with explicit runtime service wiring.
PDO connection, query executor, transaction manager, SQLite tests, and opt-in MySQL verification through Docker Compose.
Bearer JWT middleware with allowlist, blocklist, and prefix path options; CompositeAuthMiddleware for three-tier access models (public / Bearer / API key).
API-key middleware with path and method filters for machine-client endpoints.
Server-rendered HTML via NativePhpViewRenderer and HtmlResponseFactory — thin HTML coexists with JSON API routes.
Local MCP server support for read/write tools aligned with OpenAPI, with an authentication guard on write operations.
React + TypeScript + Vite starter kept optional and decoupled from backend runtime behavior.

Installation

NENE2 is available on Packagist.

The recommended way to start a new project is to clone the repository directly — it ships with Docker, .env.example, and all configuration you need out of the box:

git clone https://github.com/hideyukiMORI/NENE2.git my-project
cd my-project

If you want to use NENE2 as a Composer dependency in an existing project:

composer require hideyukimori/nene2

Quick Start

Build the PHP runtime, install dependencies, and run the standard backend checks:

cp .env.example .env
docker compose build
docker compose run --rm app composer install
docker compose run --rm app composer check

Start the local web runtime:

docker compose up -d app

The web entry point is served from public_html/ at http://localhost:8080/.

Useful local URLs:

API health: http://localhost:8080/health
Example endpoint: http://localhost:8080/examples/ping
OpenAPI: http://localhost:8080/openapi.php
Swagger UI: http://localhost:8080/docs/

Run optional real MySQL verification when database adapter behavior should be checked against a service database:

docker compose up -d mysql
docker compose run --rm app composer test:database:mysql

Domain Layer Example

src/Example/Note/ and src/Example/Tag/ are reference implementations — they demonstrate how to use the framework, but are not part of the public API stability guarantee (see ADR 0009). Copy and adapt the patterns into your own application; do not import these classes as library dependencies.

src/Example/Note/ implements a full Note CRUD with:

Layer	File(s)
Route + handler	`GetNoteByIdHandler`, `CreateNoteHandler`, `UpdateNoteHandler`, `DeleteNoteHandler`, `ListNotesHandler`
Use case (domain)	`GetNoteByIdUseCase`, `CreateNoteUseCase`, `UpdateNoteUseCase`, `DeleteNoteUseCase`, `ListNotesUseCase`
Repository interface	`NoteRepositoryInterface`
PDO adapter	`PdoNoteRepository`
Exception mapping	`NoteNotFoundException` → `NoteNotFoundExceptionHandler` → 404 Problem Details
OpenAPI	`docs/openapi/openapi.yaml` — `GET/POST/PUT/DELETE /examples/notes` paths
Tests	`tests/Example/Note/` — unit, HTTP-level, PDO integration

All Note endpoints are live at http://localhost:8080/examples/notes after docker compose up -d app.

Development Principles

NENE2 optimizes for fast, calm development. The codebase should be easy for a solo developer, a team, or an AI agent to understand without hidden conventions.

Keep domain and use-case code decoupled from HTTP, database, template, and CLI details.
Use PSR-7 / PSR-15 / PSR-17 as the HTTP runtime direction.
Use PSR-11 as the DI boundary, with explicit wiring first.
Use typed config objects at runtime; keep .env at the loading boundary.
Make behavior testable before adding framework magic.
Treat OpenAPI as the public API contract and keep MCP integrations behind the same API boundary.
Keep template engines optional; server HTML should stay thin and replaceable.
Prefer small, boring primitives over clever abstractions.
Record workflow, roadmap, and implementation decisions in docs/ rather than only in chat.

Repository Layout

NENE2 uses a single repository with Composer at the root, PHP framework code in src/, tests in tests/, a web document root in public_html/, and optional React + TypeScript frontend source in frontend/.

.
├── composer.json
├── src/                 # NENE2 framework core
│   ├── Auth/
│   ├── Config/
│   ├── Database/
│   ├── DependencyInjection/
│   ├── Error/
│   ├── Http/
│   ├── Log/
│   ├── Mcp/
│   ├── Middleware/
│   ├── Routing/
│   ├── Validation/
│   ├── View/
│   ├── Example/Note/    # canonical domain layer example (full CRUD)
│   └── Example/Tag/     # second entity example
├── tests/               # PHPUnit / architecture / contract tests
├── config/              # framework default config or examples
├── database/            # migrations, seeds, and schema docs
├── templates/           # native PHP templates and thin server HTML source
├── public_html/         # web document root
│   └── assets/          # built frontend assets
├── frontend/            # React/TypeScript/Vite source
│   └── src/
├── docs/
├── LICENSE
└── README.md

See docs/development/project-layout.md for the design details and placement rules.

Development Commands

For a full step-by-step walkthrough from clone to running API, see docs/development/setup.md.

NENE2 targets PHP >=8.4.1 <9.0. Docker is the standard development runtime, so the host OS does not need to provide that PHP version.

docker compose run --rm app composer check

Composer lives at the repository root and provides the first backend verification commands:

composer validate
composer test
composer analyse
composer check
composer test:database
composer test:database:mysql

See docs/development/php-runtime.md and docs/development/docker.md for runtime and tooling details.

NENE2's quality baseline includes PHP-CS-Fixer for backend style checks and npm, ESLint, TypeScript, and Prettier for the React frontend starter. The frontend starter targets active Node.js LTS, commits package-lock.json, and keeps dependencies modern through update automation. Framework public APIs should use PHPDoc or TSDoc where comments explain contracts or extension rules. See docs/development/quality-tools.md, docs/development/frontend-integration.md, and docs/development/documentation-comments.md.

How-to guides

256 task-focused guides covering authentication, security, database patterns, API design, background jobs, and 100+ product feature recipes.

Full guide index →

Common entry points:

Reference Implementations

hideyukiMORI/NENE2-examples — 93 field-trial applications built with hideyukimori/nene2 as a Composer dependency. Each directory is a self-contained, runnable JSON API corresponding to one howto guide.

git clone https://github.com/hideyukiMORI/NENE2-examples.git
cd NENE2-examples/deduplog   # or any other example
composer install
vendor/bin/phpunit

Delivery Starter Docs

Start with these docs when adapting NENE2 for a small client-style API:

Direction: docs/integrations/llm-delivery-starter.md
Client project start guide: docs/development/client-project-start.md
Endpoint workflow: docs/development/endpoint-scaffold.md
Local MCP server: docs/integrations/local-mcp-server.md
Local MCP client configuration: docs/integrations/local-mcp-client-configuration.md
MCP tool policy: docs/integrations/mcp-tools.md
Authentication boundary: docs/development/authentication-boundary.md
Machine-client smoke workflow: docs/development/machine-client-smoke.md
Database test strategy: docs/development/test-database-strategy.md
Patch release policy: docs/development/release-v0.1.x-policy.md

Public field trial reference (optional): hideyukiMORI/sakura-exhibition-nene2-field-trial — client-style demo forked from v0.1.1 with exhibition-shaped read-only APIs, OpenAPI, tests, local MCP, and field-trial reports. Not affiliated with any real event; see that repository’s README.md.

Project Workflow

NENE2 uses GitHub Issues as the source of work and local Markdown files as the project memory.

Create or reuse a focused GitHub Issue.
Create an Issue-numbered branch from main, such as docs/1-initial-governance.
Update code and docs together, keeping the change small.
Commit with Conventional Commits and include the Issue number.
Push, open a PR, merge after checks, and return local main to a clean state.

See docs/CONTRIBUTING.md, docs/workflow.md, and AGENTS.md before changing the project.

AI / LLM Integration

NENE2 is designed to be AI-readable and usable as a tool by AI agents.

llms.txt — machine-readable project summary for LLM crawlers (llmstxt.org standard).
Smithery — NENE2 MCP server listed in the Smithery registry (smithery.yaml).
AGENTS.md — entry point for AI agents working in this repository.
OpenAPI contract — GET /openapi.php or docs/openapi/openapi.yaml — the authoritative API contract for LLM tool use.
Local MCP server — composer mcp validates the MCP tool catalog; docker compose run --rm -e NENE2_LOCAL_API_BASE_URL=http://app app php tools/local-mcp-server.php starts the local server.
Reference implementations — hideyukiMORI/NENE2-examples: 93 runnable field-trial apps covering every major howto pattern (auth, security, queues, social features, and more). Each app is composer install && phpunit-ready.

License

NENE2 is released under the MIT License.

hideyukimori / nene2

Maintainers

Package info

Statistics

Security