Documentation · v2.x

Everything NeoPHP can do

Start with the guide, then dive into the documentation of each feature.

Getting started

NeoPHP is an ultra modular PHP framework with no dependency other than PHP 8.2. This guide creates a working application in a few minutes: installation, the modules, a first page, a database, a form, a login and the deployment. It covers NeoPHP 2; the guide of NeoPHP 1 is in docs/v1.x and the changes are listed in UPGRADE-2.0.md. Each feature has its own documentation in src/{components,packages,process}/Feature/Docs/v2.x/README.md.

Read the guide →

components

The building blocks of the framework: HTTP, routing, container, views, forms...

26

Api

The Api component gathers the tools of a JSON API: CORS, rate limiting, pagination, RFC 7807 problem details and OpenAPI 3.1 documentation. It plugs into the kernel events (preflight requests are answered before routing, error responses get the CORS headers) and reuses the Serializer, Validator, Cache and Routing components. No external library is used: the documentation page is a self-contained HTML file without CDN.

Asset

The Asset component compiles the files of assets/ into public/builds/ with hashed file names and a manifest.json. Templates get the compiled URL with the asset() view helper; CSS references are rewritten and CSS / JavaScript can be minified.

Cache

The Cache component stores computed values in named pools: filesystem, APCu, database or in-memory adapters, TTL, tags, and get() with a callback protected against cache stampedes. No external library is used. The HttpClient can store its responses in a pool (see HttpClient integration).

Config

The Config component loads every YAML file of config/ into one tree of dotted keys. Values can use placeholders for environment variables, kernel parameters and other configuration keys.

Container

The Container component is the dependency injection container of NeoPHP. It autowires constructors, shares services by default, reads the #[Autowire] and #[Inject] attributes and is filled by feature providers and config/services.yaml.

Controller

The Controller component resolves the controller of a route, builds its arguments and turns its return value into a response. AbstractController gathers the shortcuts of every feature through traits.

Cookie

The Cookie component reads the cookies of the request and queues new cookies, optionally signed with APP_SECRET. Queued cookies are added to the response automatically.

Csrf

The Csrf component protects requests against cross-site request forgery with tokens stored in the session. Tokens are masked differently every time they are rendered, and can be checked in forms, controllers or with the #[Csrf] attribute.

Database

The Database component gives PDO connections to MySQL / MariaDB, PostgreSQL and SQLite and runs SQL queries with typed parameters and nested transactions. It is not an ORM: entities, repositories, migrations and the query builder belong to the ORM package (see the ORM documentation).

Event

The Event component dispatches event objects to listeners by order of priority, with an API mirroring PSR-14 without dependency. Listeners are declared with #[AsListener], subscribers or YAML, and are built lazily by the container.

Exception

The Exception component is the base of every framework exception: messages with placeholders, context, HTTP status and headers. It also renders uncaught exceptions as an HTML page or a JSON document.

Flash

The Flash component stores messages in the session until they are read, to display them after a redirect. It requires the Session component.

Form

The Form component builds, submits, validates and renders HTML forms mapped to an entity, an object or an array. It converts the submitted values, reports the violations on their fields and renders them with themes and view helpers.

Http

The Http component models the HTTP request and response: parameter bags, uploaded files, HTML, JSON, redirect, streamed and file responses, and HTTP exceptions. It has no dependency and is used by the kernel, the routing and the controllers.

HttpClient

The HttpClient component calls external APIs: JSON and form requests, multipart uploads, redirects, retries, parallel requests, streamed downloads and named clients configured in YAML. No external library is used: requests go through ext-curl when it is loaded (parallel requests with curl_multi), and through PHP streams otherwise.

Kernel

The Kernel component boots the application: it loads the environment, discovers the modules of the framework and of the installed packages, builds the container and turns a Request into a Response. It also dispatches the kernel events and ships shared tools used by other modules: the module attributes, class discovery, a file-based resource cache and the cache:clear command.

Logger

PSR-3 compatible logger (same methods and signatures), without dependency. Messages are written in one file per channel, with a minimum level, rotation by size or period, and optional zip / gz archives of the rotated files.

Mailer

The Mailer component builds MIME emails (UTF-8, HTML and text, attachments, embedded images) and sends them through SMTP, or writes them to files or to the log in development. No external library is used: the SMTP client is native, and ext-openssl is needed for TLS.

Middleware

A middleware runs before and after the controller. It can modify the request, return a response without calling the controller, or modify the response. Middlewares are global (every request) or attached to routes, and are referenced by class, alias or group.

Routing

The Routing component maps URLs to controllers. Routes are declared in config/routes.yaml, with the #[Route] attribute on the controllers, or both. It matches the incoming requests, generates paths and absolute URLs, and compiles the routes into a cache.

Serializer

The Serializer component turns objects into JSON, XML, CSV or YAML and back: DTOs, dates, enums and ORM entities (lazy relations, proxies, circular references). It maps request bodies and query strings to typed controller arguments (#[MapRequestPayload], #[MapQueryString]) with validation, and powers json() in controllers. No external library is used; the XML format requires ext-dom.

Service

The Service component registers application services in the container from config/services.yaml: whole directories, explicit arguments, method calls, factories and aliases. Interfaces implemented by a single registered class are bound automatically, and the whole file is compiled into a cache.

Session

The Session component wraps the native PHP session with a lazy SessionManagerInterface service. The session starts only when it is needed, is stored in var/sessions/ and is saved at the end of the request.

Upload

The Upload component (src/components/Upload) stores the files sent by the users in a public directory (public/uploads/ by default) and builds their URLs.

Validator

The Validator component checks objects, values and arrays against constraints. A constraint is a class used either as a PHP attribute or as an object; its validator is built by the container, so custom validators can use services.

View

The View component renders templates with a built-in PHP engine or with Twig when it is installed. View helpers written once work in both engines and are discovered automatically in every Helper/View/ directory.

packages

Optional features plugged into the kernel: ORM, security, translation, Markdown...

16

Debug

The Debug package (src/packages/Debug) dumps variables while developing: dump() and dd() global functions, collapsible HTML dumps, colored console dumps and a dump() view helper. Dumps are active only when APP_DEBUG is true, so a forgotten dump never leaks data in production.

Dotenv

The Dotenv package reads .env files and populates $_ENV and $_SERVER, without any dependency. The kernel uses it to load .env, .env.local, .env.{APP_ENV} and .env.{APP_ENV}.local; real environment variables always win.

Image

The Image package (src/packages/Image) processes the images of the application with the GD extension of PHP, without any other dependency: thumbnails and resized copies generated on demand and cached, conversion to WebP or AVIF, photos turned upright from their EXIF orientation, metadata (GPS position, camera) removed.

Markdown

The Markdown package (src/packages/Markdown) parses Markdown (CommonMark + GitHub Flavored Markdown) into HTML without any dependency. It exposes a document API (title, description, summary, sections, links, images, code blocks) and converts HTML files and templates into Markdown.

Mercure

The Mercure package (src/packages/Mercure) pushes real-time updates to the browsers with a Mercure hub: new messages of a chat, notifications, a live feed, a progress bar. It publishes the updates to the hub, signs the JSON Web Tokens (JWT) of the publishers and the subscribers, and sets the cookie that gives access to the private updates, without any dependency.

NeoAI

NeoAI is an AI development assistant for NeoPHP applications. It reads the project (code, routes, configuration, WebProfiler profiles), answers questions, audits the code and proposes patches as unified diffs, from the console (ai:start, ai:scan) and from the web debug toolbar and the profiler. It is a development tool: it is enabled only when kernel.debug is true, it can never write files from HTTP, and every patch is reviewed and confirmed by the developer in the console. It works with OpenAI and OpenAI-compatible APIs (Mistral, Groq, OpenRouter, LM Studio, vLLM), Anthropic, Google Gemini and a local Ollama, through the HttpClient component. No external library, no CDN.

Notifier

The Notifier package (src/packages/Notifier) sends the notifications of the application to its users: a new message, an order shipped, a comment on a post. One notification goes through several channels, chosen from its importance:

Orm

The ORM package (src/packages/Orm) is a data mapper built on the Database component: entities are plain PHP classes mapped with attributes, and the ORM (OrmManagerInterface, the entity manager) tracks them and writes the changes on flush(). It ships repositories, query builders, lifecycle events, code generators and migrations, and works with MySQL / MariaDB, PostgreSQL and SQLite.

QrCode

The QrCode package (src/packages/QrCode) generates QR codes and reads them, without any dependency: encoder written in PHP (ISO/IEC 18004, versions 1 to 40), SVG images (PNG with the gd extension), contents signed with APP_SECRET that can expire, rotate or be used once, and a short code for every QR code that must be read: when the camera cannot scan it, the code printed under it (e.g. 7Q2K-4MXA) is typed instead and gives the same result.

Queue

The Queue package (src/packages/Queue) runs work asynchronously: the application dispatches messages (any serializable PHP object), a transport stores them, and a worker (php bin/neo queue:work) handles them in the background with retries, exponential backoff and a failed storage. It ships the sync, database, filesystem and redis transports, handler discovery with #[AsMessageHandler], self-handling jobs, console commands and a WebProfiler panel. No external dependency is required (ext-redis only for the redis transport).

Scheduler

The Scheduler package (src/packages/Scheduler) runs recurring tasks: console commands, invokable classes, closures and queue messages, each with a cron expression. A single system cron entry calls php bin/neo schedule:run every minute; the package selects the due tasks, prevents overlaps, records a run history and shows it in the console and in a WebProfiler panel. No external dependency is required.

Security

The Security package (src/packages/Security) authenticates users (login form, HTTP Basic, access tokens, custom authenticators, remember-me) and checks their permissions (roles, role hierarchy, voters, #[IsGranted], access_control). It is enabled when config/packages/security.yaml defines at least one firewall or one access_control rule; otherwise it does nothing.

Tailwind

The Tailwind package (src/packages/Tailwind) runs the official Tailwind CSS v4 standalone CLI: no Node.js, no npm. It downloads the CLI, prepares the CSS file and compiles it into the assets published by the Assets component.

Translation

The Translation package (src/packages/Translation) translates the application messages from YAML and XLIFF 1.2 files without requiring the intl extension. It supports parameters, ICU-lite plurals and selects, fallback locales, locale detection (route, query, session, cookie, Accept-Language), localized language names (with intl), view helpers, a controller trait, and translates the validation and security messages.

WebProfiler

The WebProfiler package collects information about every HTTP request in development and shows it in a web debug toolbar injected at the bottom of HTML pages and in a profiler interface (/_profiler). It is a structure: the package only renders, stores and routes. Each feature (component, package, process or application code) adds its own element by creating one class that returns plain data and value objects; the package does all the HTML. No external library is used: the pages and the toolbar are self-contained (inline CSS and JS, no CDN, light and dark themes).

Yaml

The Yaml package is a dependency-free YAML parser used for the configuration, routes.yaml and services.yaml. It supports the YAML subset needed by configuration files and reports errors with the line, the file and a snippet.

process

Tools running around your application: the console and the installer.

4

Console

The Console process (src/process/Console) runs the php bin/neo command line: commands declared with #[AsCommand], typed arguments and options, interactive questions, styled output and progress bars. Commands are discovered in src/, in every framework feature and in the NeoPHP packages installed with Composer, and their constructor is autowired.

Doctor

The Doctor process (src/process/Doctor) checks a project in one command and tells what to fix: the version and the extensions of PHP, the writable directories, the environment variables, the database, the migrations, the SMTP server, the Mercure hub, the queue...

Installer

The Installer process generates the files of a NeoPHP project from a skeleton: bin/neo, public/, src/Kernel.php, config/, templates/, .env... It never overwrites an existing file unless forced, completes .env with the missing variables and adds the App\ autoload to composer.json.

Package

The Package process installs, lists, updates and removes the NeoPHP packages with Composer, and generates the skeleton of a new package. A NeoPHP package is a Composer package of type neophp-package that adds modules to a project: its configuration is copied into config/packages/<name>/, its routes are imported in config/routes.yaml, its templates, translations, assets, entities and migrations are used with the ones of the project, and its commands, listeners and other classes are discovered.