PHPackages hideyukimori/nene2 - 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. [API Development](/categories/api) 4. / 5. hideyukimori/nene2 ActiveLibrary[API Development](/categories/api) hideyukimori/nene2 ================== PHP micro-framework: JSON APIs first, minimal server HTML, easy React/SPA integration, structure friendly to AI tooling. v1.5.329(1w ago)0217↑65.9%[1 issues](https://github.com/hideyukiMORI/NENE2/issues)[6 PRs](https://github.com/hideyukiMORI/NENE2/pulls)MITPHPPHP >=8.4.1 <9.0CI passing Since May 7Pushed 1w agoCompare [ Source](https://github.com/hideyukiMORI/NENE2)[ Packagist](https://packagist.org/packages/hideyukimori/nene2)[ RSS](/packages/hideyukimori-nene2/feed)WikiDiscussions main Synced 1w ago READMEChangelog (10)Dependencies (13)Versions (414)Used By (0) NENE2 ===== [](#nene2) [![PHP](https://camo.githubusercontent.com/bcfcc7281b9c3db243d093e8e18390ff4cb819681e0bd3b814da0e989fbd13d7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e342532422d383839324246)](https://www.php.net/)[![Packagist](https://camo.githubusercontent.com/6dc5fba01510bb8c3791b5fe50ec6d14912b967bde7728d7ea52ee60e520b3dc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6869646579756b696d6f72692f6e656e6532)](https://packagist.org/packages/hideyukimori/nene2)[![OpenAPI](https://camo.githubusercontent.com/d075cce4f3da0e25c719c3972e3651c750acf2e6c6079c50493d0bb7c1e11c69/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4f70656e4150492d332e312d383545413244)](https://raw.githubusercontent.com/hideyukiMORI/NENE2/main/docs/openapi/openapi.yaml)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](./LICENSE) PHP micro-framework: JSON APIs first, minimal server HTML, easy React starter integration, structure friendly to AI tooling. **[OpenAPI contract](https://raw.githubusercontent.com/hideyukiMORI/NENE2/main/docs/openapi/openapi.yaml)** — 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 ----- [](#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 -------------------- [](#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 ------------ [](#installation) NENE2 is available on [Packagist](https://packagist.org/packages/hideyukimori/nene2). 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 ----------- [](#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 -------------------- [](#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](docs/adr/0009-v1.0-public-api-scope.md)). 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: LayerFile(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 DetailsOpenAPI`docs/openapi/openapi.yaml` — `GET/POST/PUT/DELETE /examples/notes` pathsTests`tests/Example/Note/` — unit, HTTP-level, PDO integrationAll Note endpoints are live at `http://localhost:8080/examples/notes` after `docker compose up -d app`. --- Development Principles ---------------------- [](#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 ----------------- [](#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 -------------------- [](#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