Documentation menu
On this page
Guide · v2.x
NeoPHP
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.
Requirements
- PHP 8.2 or higher with the
ctype,json,mbstringandtokenizerextensions (required by Composer) - Composer
- The PHP extensions of the features you use:
pdo_mysql,pdo_pgsqlorpdo_sqlite(database),openssl(SMTP over TLS, Tailwind download, push notifications),fileinfo(uploads),curl(recommended for the HTTP client, parallel requests),apcu(optional,apcucache adapter),dom(XML format of the Serializer),gd(Image package: thumbnails, WebP) andexif(recommended, orientation of the photos) - Optional:
twig/twig^3.0 for Twig templates
Create the project
Create the application from the neophp/skeleton project:
composer create-project neophp/skeleton my-app
cd my-app
php bin/neo serve
The skeleton composer.json:
{
"name": "neophp/skeleton",
"description": "NeoPHP application skeleton.",
"type": "project",
"license": "MIT",
"keywords": ["neophp", "skeleton", "framework"],
"require": {
"php": ">=8.2",
"neophp/framework": "^2.0"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
},
"scripts": {
"neo:install": "@php vendor/bin/neo install",
"post-create-project-cmd": "@neo:install"
},
"config": {
"sort-packages": true
},
"minimum-stability": "stable",
"prefer-stable": true
}
composer create-project runs neo install, which generates the project files, a random APP_SECRET and APP_URL in .env. Existing files are never overwritten (php bin/neo install --force to regenerate them). Open http://127.0.0.1:8000.
For Twig templates, add Twig to the project:
composer require twig/twig
Project structure
assets/ CSS, JS and images compiled into public/builds/
bin/neo command line
config/
config.php modules enabled or disabled in this project, per environment
framework/ configuration of the components (api.yaml, app.yaml, cache.yaml, database.yaml, http_client.yaml, mailer.yaml, serializer.yaml, view.yaml...)
packages/ configuration of the packages (orm.yaml, security.yaml, debug.yaml, translation.yaml, web_profiler.yaml, neo_ai.yaml, mercure.yaml, image.yaml, notifier.yaml, qr_code.yaml; tailwind.yaml is created by tailwind:install)
routes.yaml routes
services.yaml services
migrations/ database migrations
public/index.php front controller
src/
Controller/ controllers
Entity/ ORM entities
Repository/ repositories
Form/ forms
Command/ console commands
Kernel.php application kernel (extends AbstractKernel)
templates/ PHP (.php) and Twig (.html.twig) templates
translations/ translation files ({domain}.{locale}.yaml|xlf)
var/ cache, logs, sessions
.env environment variables (APP_ENV, APP_DEBUG, APP_SECRET, APP_URL, TRUSTED_PROXIES, TRUSTED_HOSTS, DATABASE_URL, MAILER_DSN, NEO_AI_*, MERCURE_*)
.env.local local values and secrets, never committed
Modules
NeoPHP is made of modules: the components (src/components/), the packages (src/packages/) and the processes (src/process/). Each module has a single entry point at its root, a final manager declared with an attribute, and its interface:
#[Component(provider: SessionProvider::class)]
final class SessionManager implements SessionManagerInterface
{
}
| Attribute | Module |
|---|---|
#[Component] |
component of the framework (src/components/) |
#[Package] |
package, of the framework (src/packages/) or installed with Composer |
#[Process] |
process (src/process/): Console, Doctor, Installer, Package |
The kernel discovers the modules by itself (nothing to register) and loads them in the order of their requires. Every module is enabled; config/config.php only lists what the project changes:
<?php
declare(strict_types=1);
return [
NeoPHP\Package\WebProfiler\WebProfilerManager::class => ['dev' => true],
NeoPHP\Package\NeoAI\NeoAiManager::class => ['dev' => true],
NeoPHP\Component\Mailer\MailerManager::class => false,
NeoPHP\Package\Queue\QueueManager::class => ['all' => true, 'test' => false],
];
false disables a module, an array enables it only in the listed environments (all for the others). The modules required by the kernel cannot be disabled, and a module required by an enabled module cannot be disabled: the kernel stops with a clear error naming both modules. Run php bin/neo cache:clear after a change in production.
To use a module, inject its interface, never its internal classes:
use NeoPHP\Component\Routing\RoutingManagerInterface;
use NeoPHP\Package\Orm\Contract\EntityManagerInterface;
use NeoPHP\Package\Translation\TranslationManagerInterface;
public function __construct(
private RoutingManagerInterface $routing,
private EntityManagerInterface $entityManager,
private TranslationManagerInterface $translator,
) {
}
The public API of a module is its manager and its interface, its Contract\ folder (interfaces and base classes to extend), its attributes, its exceptions and its events. The classes marked @internal (providers, discoveries, traces, helpers of other modules) can change in any version.
The integration of a module with another one lives in Helper/<Module>/ of the module, for example src/components/Flash/Helper/WebProfiler/FlashProfiler.php (the Flash panel of the profiler): it is loaded only when both modules are enabled and uses only the public API of the other module. See the Kernel documentation.
NeoPHP packages
A NeoPHP package is a Composer package of type neophp-package that adds modules to the project: its manager declared with #[Package], its configuration, templates, commands, listeners and view helpers.
php bin/neo neophp:package:install acme/neo-billing
php bin/neo neophp:package:list
php bin/neo neophp:package:update
php bin/neo neophp:package:remove acme/neo-billing
php bin/neo neophp:package:create acme/neo-billing --link
The configuration of a package is copied into config/packages/<name>/, its routes are imported in config/routes.yaml (resource: '@<name>'), its templates are rendered with @<name>/, its assets with asset('@<name>/...'), and its translations, commands, listeners, entities and migrations are loaded with the ones of the project. The page /_profiler/packages of the profiler lists the packages and modules with their status per environment. See the Package documentation.
First page
src/Controller/HelloController.php
<?php
declare(strict_types=1);
namespace App\Controller;
use NeoPHP\Component\Controller\Contract\AbstractController;
use NeoPHP\Component\Http\Response\Response;
use NeoPHP\Component\Routing\Attribute\Route;
class HelloController extends AbstractController
{
#[Route('/hello/{name}', name: 'hello', methods: ['GET'], defaults: ['name' => 'world'])]
public function index(string $name): Response
{
return $this->render('hello/index.html.twig', ['name' => $name]);
}
}
templates/hello/index.html.twig
{% extends 'base.html.twig' %}
{% block body %}
<h1>Hello {{ name }}!</h1>
<a href="{{ path('hello', {name: 'NeoPHP'}) }}">Say hello to NeoPHP</a>
{% endblock %}
The same page with a PHP template, templates/hello/index.php:
<?php $this->extend('base') ?>
<?php $this->start('content') ?>
<h1>Hello <?= $this->e($name) ?>!</h1>
<?php $this->stop() ?>
Controllers are discovered in src/Controller/ (#[Route]), or declared in config/routes.yaml. See the Routing, Controller and View documentation.
Database and entities
.env
DATABASE_URL="mysql://user:password@127.0.0.1:3306/app?charset=utf8mb4"
php bin/neo db:create --if-not-exists
php bin/neo make:entity
make:entity is a wizard: it asks the entity name, then the fields one by one (type ? to list the types), the relations and their inverse side. Then:
php bin/neo make:migration
php bin/neo migration:migrate
In a controller:
#[Route('/posts', name: 'post_index')]
public function index(PostRepository $posts): Response
{
return $this->render('post/index.html.twig', ['posts' => $posts->findBy([], ['id' => 'DESC'])]);
}
#[Route('/posts/{id}', name: 'post_show')]
public function show(Post $post): Response
{
return $this->render('post/show.html.twig', ['post' => $post]);
}
Post $post is loaded from {id} (or {slug}...), a 404 error is returned when it does not exist. See the Database and ORM documentation.
Forms
php bin/neo make:form Post Post
#[Route('/posts/new', name: 'post_new', methods: ['GET', 'POST'])]
public function new(Request $request): Response
{
$post = new Post();
$form = $this->createForm(PostForm::class, $post);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
$this->getOrm()->persist($post);
$this->getOrm()->flush();
$this->addFlash('success', 'Post created.');
return $this->redirectToRoute('post_index');
}
return $this->render('post/new.html.twig', ['form' => $form]);
}
{{ form(form) }}
The CSRF token is added automatically. Set theme: bootstrap5 in config/framework/form.yaml for Bootstrap 5. See the Form, Validator and Csrf documentation.
APIs
#[Route('/api/posts', name: 'api_post_create', methods: ['POST'])]
public function create(#[MapRequestPayload] PostInput $input): JsonResponse
{
$post = (new Post())->setTitle($input->title)->setContent($input->content);
$this->getOrm()->persist($post);
$this->getOrm()->flush();
return $this->json($post, 201, [], ['groups' => ['read']]);
}
The JSON (or XML, form) body is decoded, mapped to the PostInput DTO and validated: invalid data returns a 422 JSON response with the violations, a malformed body a 400 and an unsupported Content-Type a 415. json() normalizes objects with the Serializer (#[Groups], #[SerializedName], #[Ignore]...). See the Serializer documentation.
The Api component adds the rest of an API toolkit, configured in config/framework/api.yaml:
#[Route('/api/posts', name: 'api_post_index', methods: ['GET'])]
#[RateLimit('api')]
#[OA\Response(200, type: Post::class, groups: ['read'], paginated: true)]
public function index(PostRepository $posts, #[MapPagination] PageRequest $pageRequest): JsonResponse
{
$page = $this->paginate($posts->createQueryBuilder('p')->orderBy('p.id', 'DESC'), $pageRequest);
return $this->jsonPage($page, ['groups' => ['read']]);
}
- CORS: preflight
OPTIONSrequests answered before routing, headers added to every response of the configured paths (also errors),#[Cors]per controller; - rate limiting: named limiters (fixed window, sliding window, token bucket) stored in a cache pool,
#[RateLimit('api')]or$this->rateLimit('login', $email), 429 withRetry-AfterandX-RateLimit-*headers; - pagination:
?page=&limit=for arrays, iterables and ORM query builders,{"items", "pagination", "links"}withLinkandX-Total-Countheaders; - RFC 7807 problem details: errors of
/apiroutes rendered asapplication/problem+json(validation violations included); - OpenAPI 3.1:
php bin/neo openapi:dumpor/api/docgenerated from the routes, DTOs, serializer groups and validation constraints.
See the Api documentation.
Login
php bin/neo make:user
php bin/neo make:migration && php bin/neo migration:migrate
php bin/neo make:auth --twig
config/packages/security.yaml
providers:
users:
entity:
class: App\Entity\User
property: email
firewalls:
main:
pattern: ^/
provider: users
form_login:
login_path: app_login
enable_csrf: true
logout:
path: app_logout
enable_csrf: true
methods: [POST]
access_control:
- { path: ^/admin, roles: ROLE_ADMIN }
In controllers: $this->getUser(), $this->denyAccessUnlessGranted('ROLE_ADMIN'), #[IsGranted('ROLE_ADMIN')]. In templates: app_user(), is_granted('ROLE_ADMIN'), logout_path(), logout_form('Logout') (the logout is a POST form protected by a CSRF token). See the Security documentation.
Styles with Tailwind
php bin/neo tailwind:install
php bin/neo tailwind:run --watch
<link rel="stylesheet" href="{{ asset('css/app.css') }}">
Without Tailwind, the files of assets/ are served with asset() as well. See the Asset and Tailwind documentation.
Translations
Enable the locales in config/packages/translation.yaml (locales: [en, fr]) and write translations/messages.fr.yaml:
home:
title: Bienvenue
posts: "{count, plural, =0 {Aucun article} one {# article} other {# articles}}"
<h1>{{ 'home.title'|trans }}</h1>
<p>{{ translate('home.posts', {count: posts|length}) }}</p>
The locale is detected from the route {_locale}, ?lang=, the session, a cookie or Accept-Language; $this->switchLocale('fr') in a controller remembers it. Validation and login errors are written in English and translated through translations/validators.fr.yaml and translations/security.fr.yaml. php bin/neo translation:generate adds the missing keys to the files. See the Translation documentation.
Useful commands
| Command | Description |
|---|---|
php bin/neo serve |
development server |
php bin/neo list |
every command |
php bin/neo doctor |
checks the project (PHP, extensions, directories, secrets, database, migrations, services) and tells what to fix |
php bin/neo down / php bin/neo up |
enables or disables the maintenance mode |
php bin/neo route:list |
routes |
php bin/neo make:entity (also make:form, make:command, make:user, make:auth, make:voter, make:email) |
code generators (they ask the missing values) |
php bin/neo make:migration / migration:migrate |
database migrations |
php bin/neo cache:clear |
clears var/cache/ |
php bin/neo neophp:package:install vendor/name (also neophp:package:list, update, remove, create) |
NeoPHP packages |
php bin/neo cache:pool:clear --all |
clears the cache pools (also cache:pool:list, cache:pool:prune) |
php bin/neo serializer:debug "App\Entity\Post" |
serialization metadata of a class |
php bin/neo asset:reload --minify |
compiles assets/ into public/builds/ |
php bin/neo openapi:dump --format=yaml |
OpenAPI document of the API routes |
php bin/neo debug:container |
services of the container |
php bin/neo translation:generate / translation:debug / translation:lint |
translation files |
php bin/neo help <command> shows the options and examples of a command. See the Console documentation.
Deployment
.env.local(or real environment variables):APP_ENV=prod,APP_DEBUG=0, a newAPP_SECRET,APP_URL=https://example.com,TRUSTED_HOSTS=example.com,TRUSTED_PROXIESwhen a reverse proxy / load balancer is in front of PHP,DATABASE_URL,MAILER_DSN; inconfig/framework/app.yaml, keepsecurity_headers.enabled: trueand sethsts: 31536000once HTTPS workscomposer install --no-dev --optimize-autoloaderphp bin/neo migration:migrate -nphp bin/neo tailwind:run --minify(if Tailwind is used), thenphp bin/neo asset:reload --minifyphp bin/neo cache:clearphp bin/neo doctor --env=prod --strict: checks the extensions, the directories, the secrets, the database and the services, and fails when something must be fixed (see the Doctor documentation)- Point the web server document root to
public/. In a sub-directory of the domain (https://example.com/app/), make/app/servepublic/(ApacheAlias /app /var/www/app/publicandRewriteBase /app/inpublic/.htaccess) and setAPP_URL=https://example.com/app: the routes stay the same, the generated URLs contain/app(public/.htaccessis provided for Apache: onlyindex.phpis executed, hidden files are never served; with Nginx, send every request toindex.phpand refuse the other.phpfiles)
Features
| Group | Features |
|---|---|
| components | Api, Asset, Cache, Config, Container, Controller, Cookie, Csrf, Database, Event, Exception, Flash, Form, Http, HttpClient, Kernel, Logger, Mailer, Middleware, Routing, Serializer, Service, Session, Upload, Validator, View |
| packages | Debug, Dotenv, Image, Markdown, Mercure, NeoAI, Notifier, Orm, QrCode, Queue, Scheduler, Security, Tailwind, Translation, WebProfiler, Yaml |
| process | Console, Doctor, Installer, Package |
The documentation of a feature is in src/<group>/<Feature>/Docs/v2.x/README.md, for example src/components/Routing/Docs/v2.x/README.md. The documentation of NeoPHP 1 stays next to it, in Docs/v1.x/.
Versions and support
NeoPHP follows semantic versioning inside a major version:
| Version | Contains | Upgrade |
|---|---|---|
patch (v2.0.1) |
bug and security fixes | always safe: composer update |
minor (v2.1.0) |
new features, new options; a changed default only in the generated files of new projects | safe; read the changelog for the new options |
major (v3.0.0) |
incompatible changes | follow the upgrade notes |
v2.xis the maintained branch of NeoPHP 2: releases are tagged automatically from its merged pull requests (featgives a minor version,fix/perf/refactora patch).- In
v2.x, the public API (managers, their interfaces,Contract\, attributes, exceptions, events, options and configuration keys) is not removed nor renamed. When it has to change, the old one keeps working and is marked deprecated in the documentation until the next major version. The classes marked@internalare not covered. - Security fixes are released on the latest
v2.xversion. Report a vulnerability privately, see SECURITY.md. - Require NeoPHP with
^2.0incomposer.jsonto receive the fixes and features of v2 without breaking changes. To upgrade from 1.x, follow UPGRADE-2.0.md.
Changelog
The history of the versions is in CHANGELOG.md; each feature documentation has its own Changelog section.