Documentation · v1.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, a first page, a database, a form, a login and the deployment. Each feature has its own documentation in src/{components,packages,process}/Feature/Docs/v1.x/README.md.

Read the guide →

components

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

25

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 and redirect 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, builds the container, registers the providers and turns a Request into a Response. It also dispatches the kernel events and ships shared tools used by other features: 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 SessionInterface service. The session starts only when it is needed, is stored in var/sessions/ and is saved at the end of the request.

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...

10

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.

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.

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.

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 (OrmInterface, 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.

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 any dependency (no intl needed). It supports parameters, ICU-lite plurals and selects, fallback locales, locale detection (route, query, session, cookie, Accept-Language), 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.

2

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/ and in every framework feature, and their constructor is autowired.

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.