Download the PHP package neophp-dev/neophp without Composer

NeoPHP

PHP 8.5 framework centered around:

• an application core in neo/
• an internal CLI in bin/neo
• isolated application projects in src/<Project>/

NeoPHP aims for a different balance than Symfony or Laravel. The goal is not to stack layers, bundles, or a very large ecosystem, but to provide a readable, compact PHP core that can be used directly to build a complete application without leaving the repository. The framework relies on a simple structure, an integrated CLI, auto-discovered core modules, and a multi-project workflow that stays explicit.

In practice, NeoPHP is aimed mainly at projects that want to move fast without adopting all the organizational complexity of large general-purpose frameworks. Compared to Symfony, it greatly reduces configuration ceremony and fragmentation between components. Compared to Laravel, it is more minimal, more direct in its architecture, and less dependent on a "magic" layer or a set of external tools. If what you need is a smaller, more predictable framework that's easier to follow end-to-end in the source code, that's exactly where NeoPHP fits.

Table of contents

• Overview
• Repository architecture
• Core map
• Execution cycle
• Project structure
• DI container and configuration
• HTTP layer
• Routing and controllers
• Twig views, assets, and translations
• Database and QueryBuilder
• ORM and repositories
• Data Mapper ORM (entities)
• Seeding
• Forms, upload, and validation
• Security: auth, password, middlewares, csrf
• Events
• Crons
• Cache, logs, mailer, profiler, and errors
• Markdown
• CLI and generators
• PHPUnit tests
• Deployment
• Dependencies and requirements

Overview

NeoPHP relies on two entry points:

• public/index.php for the HTTP runtime
• bin/neo for the CLI

The core goes through Neo\App, which:

• detects the current project
• initializes the container
• registers the current project's application paths
• automatically discovers *Module.php modules in neo/Core/
• orders these modules according to their dependencies, then runs register() / boot()
• activates Twig, the DB, assets, translation, auth, cache, crons, mailer, and profiler
• scans application controllers, routes, listeners, and crons
• executes the HTTP request or CLI command
• centralizes error handling

Repository architecture

The example project present in the repository is src/Test/.

Core map

The neo/Core/ core is organized by subsystem:

Notable subfolders in neo/Core/:

Execution cycle

Over HTTP

Neo\App looks for a project by reading src/*/Config/app.config.php and compares the access key to HTTP_HOST / SERVER_NAME.

If only one project exists in src/, it is selected automatically.

In the CLI

Commands that operate on an existing project generally expect --project=ProjectName.

Notable exceptions:

• project:create
• project:sync
• app:serve

Example:

Project structure

A project generated by app:make:project first contains:

Without the --skeleton option, the generator also adds:

Some folders are created later, when the feature is enabled:

• App/Crons/ via make:cron
• App/Event/Listener/ via make:event and make:event:listener
• Database/Entity/ via make:entity
• Database/Migrations/ on the first database:orm:diff or database:migration:migrate
• Tests/ via make:test or make:test:auto

The sensitive configs database.config.php, deploy.config.php, api.config.php, and mailer.config.php are meant to be ignored by Git in the generated .gitignore. The generator also ignores Storage/.

DI container and configuration

The Neo\Core\DI\Container container provides:

• set() to register a service or a factory
• get() to resolve a service
• bind() to map an abstraction to an implementation
• make() to instantiate a class with runtime parameters
• reflection-based autowiring
• support for controller and service constructors

Example:

Configuration

The Config service loads every *.config.php file in the project and can merge *.config.test.php files during tests.

Example:

Example app.config.php:

HTTP layer

The HTTP layer is made up mainly of:

• Request — incoming request
• Response / JsonResponse / RedirectResponse — HTTP responses
• HttpClient — cURL HTTP client for outgoing requests
• Session / Cookie / Flash — client state

Request

Request notably exposes:

• getMethod()
• getPath()
• query()
• body()
• header()
• file()
• getIp()
• getUserAgent()
• getPreviousUrl()

Example:

Response

Response is used to build basic HTTP responses.

Example:

Shortcut examples via AbstractController:

HttpClient

HttpClientManager lets you make outgoing HTTP requests via cURL. It returns a standard Response object.

Common options: base_uri, query, headers, bearer, json, body, auth_basic, timeout, max_redirects.

Session, cookie, and flash

The framework automatically configures the session from session.config.php.

Example in a controller:

Twig exposes flash messages via flashes():

Routing and controllers

Routing is based on PHP attributes scanned in src/<Project>/App/Controllers.

Confirmed features:

• route prefix via #[MainRoute(...)]
• multi-method routes via methods: [...]
• dynamic parameters {id}
• optional parameters {slug?}
• regex constraints via requirements
• route caching outside the dev environment
• typed argument injection via the container

Simple example:

More complete example:

Helpers exposed by AbstractController:

• render()
• template()
• redirectToRoute()
• redirectToPath()
• redirectBack()
• json()
• jsonSuccess()
• jsonError()
• auth()
• dispatch()
• upload()
• getSession()
• getFlash()
• getCookie()
• access to Logger, Cache, Config

Twig also exposes:

• path()
• currentRoute()

Twig views, assets, and translations

Twig views

Views are loaded from src/<Project>/App/Views.

Twig is initialized with:

• optional cache
• optional debug
• twig/intl-extra
• app global
• functions added by the framework

Example:

Assets

Source assets live in src/<Project>/Assets/.

The AssetHandler component:

• exposes asset()
• compiles css, js, and less
• minifies CSS and JS
• generates hashed file names
• writes public/builds/<Project>/manifest.json
• serves compiled files from public/builds/<Project>/assets/

Twig example:

Source tree:

Translations

Translations are loaded from src/<Project>/Translations/<locale>.php.

Available Twig functions:

• translate()
• trans()
• getLocales()
• getLocale()
• isEnabledTranslation()

Notable behavior:

• the locale is resolved from the config and cookies
• setLocale() persists the language in a lang cookie
• in the dev environment, a missing key is automatically registered in the current locale's file
• translation:sync lets you sync the keys across all locale files

Example src/Blog/Translations/fr.php file:

Twig example:

Example in a controller:

Utility extensions

The neo/Core/Extension/ folder exposes reusable helpers at two levels:

• in controllers via getString(), getDate(), getFile(), getHtml(), getJson(), getNumber(), getPath(), getUrl(), and getArray()
• in Twig via automatically registered functions and filters

Available families:

• StringExtension slugify(), camelCase(), snakeCase(), pascalCase(), truncate(), excerpt()
• DateExtension date_now(), date_format(), human_diff(), date_age(), is_past(), is_future(), is_today()
• NumberExtension currency(), percent(), human_size(), ordinal(), to_roman()
• FileExtension file_extension(), file_size(), file_mime(), is_image()
• HtmlExtension html_escape(), html_strip(), html_truncate(), html_tag()
• JsonExtension json_encode_ext(), json_decode_ext(), json_is_valid()
• UrlExtension url_is_valid(), url_host(), url_params(), url_add_params()
• PathExtension path_join(), path_normalize(), path_extension(), path_filename()
• ArrayExtension array_flatten(), array_pluck(), array_only(), array_except(), array_group_by()

Examples:

Database and QueryBuilder

The PDO connection is driven by Config/database.config.php via DatabaseConnection.

Minimal example:

Schema tools

The framework ships a dedicated database CLI:

• database:create creates the database declared in database.config.php
• make:entity generates a Data Mapper entity (POPO) and its repository in Database/Entity/ and Database/Repository/
• database:orm:diff compares entities against the current database and generates a migration file in Database/Migrations/
• database:migration:migrate applies all pending migrations
• database:migration:rollback rolls back the last applied batch
• database:migration:status displays migration status and flags a drift between the current schema and the latest snapshot

Notable behaviors:

• make:entity is interactive: it asks for the entity name, its properties, and their types
• make:entity --no-repository skips repository generation
• database:orm:diff --dry-run shows the diff without writing a file
• database:orm:diff --connection=<name> targets a specific connection for multi-database projects
• the internal neo_migrations and neo_schema_snapshots tables are excluded from introspection
• generated migrations are written to src/<Project>/Database/Migrations/

Examples:

QueryBuilder

QueryBuilder notably covers:

• table()
• select()
• where(), orWhere()
• whereLike(), whereIn(), whereNull(), whereNotNull()
• between()
• join(), leftJoin()
• orderBy(), groupBy()
• limit(), offset()
• get(), first(), count()
• insert(), insertGetId(), update(), delete()
• paginate()
• transactions via transaction()

Example:

Example with a transaction:

Migrations

Migrations live in src/<Project>/Database/Migrations/.

Each migration exposes:

• up(DatabaseManager $db): void
• down(DatabaseManager $db): void

The runner maintains two technical tables:

• neo_migrations for the history of applied migrations
• neo_schema_snapshots to store a schema hash after execution

The snapshot lets database:migration:status warn when the current schema has changed since the last generated or applied migration.

Example workflow:

Minimal migration example:

ORM and repositories

NeoPHP's ORM is a Data Mapper. Entities are POPOs annotated with mapping attributes. No parent class is required. Persistence goes through the EntityManager.

EntityManager

EntityManager is the entry point for all persistence operations.

Main API:

• persist(object $entity) — registers an entity for insert or update
• remove(object $entity) — marks an entity for deletion
• flush() — writes all changes to the database
• find(string $class, mixed $id) — lookup by primary key
• getRepository(string $class) — returns the entity's repository
• wrapInTransaction(callable $callback) — runs a callback within a transaction
• contains(object $entity) — checks whether an entity is managed by the UnitOfWork
• clear() — clears the identity map

In a controller, EntityManager is accessible via $this->entityManager (registered by DatabaseControllerExtension).

Example:

EntityRepository

EntityRepository is the base class generated by make:entity.

Available API:

• find($id) — lookup by primary key
• findAll() — returns all entities
• findBy(array $criteria, array $orderBy, ?int $limit, ?int $offset) — search by criteria
• findOneBy(array $criteria, array $orderBy) — returns a single result
• count(array $criteria) — counts entities matching criteria

Repository example:

Usage in a controller:

Relations

Relations available via attributes:

• #[OneToOne(targetEntity: ..., inversedBy: ...)] with #[JoinColumn]
• #[ManyToOne(targetEntity: ..., inversedBy: ...)] with #[JoinColumn]
• #[OneToMany(targetEntity: ..., mappedBy: ...)]
• #[ManyToMany(targetEntity: ..., inversedBy: ...)] with #[JoinTable]

Collections (OneToMany, ManyToMany) use the Collection class. Loading is lazy by default, handled through transparent proxies.

Example entity with relations:

See the Data Mapper ORM (entities) section for creating entities via the CLI and the migration workflow.

Data Mapper ORM (entities)

NeoPHP's ORM is built on the Data Mapper pattern. make:entity creates an entity and its repository. database:orm:diff generates the migration from the difference between the entities and the database.

Creating an entity

The generator is interactive: it asks for the name, then the properties and their types.

Example entity generated in Database/Entity/Post.php:

Available scalar types:

• string, text
• integer, bigint, smallint
• boolean, float, decimal
• datetime, date, time
• json

Available relations:

• #[OneToOne(...)] with #[JoinColumn(...)]
• #[ManyToOne(...)] with #[JoinColumn(...)]
• #[OneToMany(...)]
• #[ManyToMany(...)] with #[JoinTable(...)]

OneToMany and ManyToMany sides use Collection to manage collections of related objects.

ManyToMany note — automatic persistence on flush: ManyToMany collections are now persisted automatically on flush(). A snapshot of the collection is taken when the entity is loaded; at flush time, the UoW computes the diff (additions/removals) and syncs the join table without manual action.

Data Mapper repository

The generated repository extends EntityRepository:

--no-repository option available to skip repository generation.

Generating the migration from entities

On a multi-database project, the --connection=<name> option targets a specific connection.

Migrations generated by database:orm:diff follow the same up() / down() format as manual migrations and are stored in Database/Migrations/.

Forms, upload, and validation

Forms

NeoPHP ships:

• FormFactory — entry point for creating forms
• FormBuilder — fluent building API
• Form — form object
• FieldType — enum of available field types
• Twig rendering
• built-in CSRF
• constraint-based validation

Field types available via FieldType:

• text, textarea
• email, password
• number
• hidden
• checkbox
• select
• date, datetime-local

Available Twig helpers:

• form_start()
• form_end()
• form_row()
• form_widget()
• form_label()
• form_error()
• form_errors()
• form_csrf()

Example built via FormFactory:

Twig example:

Upload in a controller

The application entry point is AbstractController::upload().

Signature:

This helper:

• retrieves the file via Request::file()
• checks the PHP upload
• reads the original extension
• rejects php, phtml, exe, sh, js
• checks the provided whitelist
• creates the target folder in src/<Project>/Assets/<directory>
• moves the file
• returns the final file name

Example:

Then display it:

Validation

The validator relies on constraint attributes placed on the properties of any class (entity, DTO, etc.).

Since the refactor, each constraint is split into two files: a PHP attribute in Assert/ (which declares the parameters) and a validator in Validator/ (which contains the logic). ValidatorManager resolves the validator via the DI container using the constraint's validatedBy() method.

Constraints present in the framework:

• NotBlank
• Length
• Email
• Date
• Choice
• Range
• Regex
• Url
• Unique
• Exists — checks that a value exists in the database (useful for validating a foreign key)
• EqualToField

Example on a DTO:

Seeding

The Seeder module lets you populate the database with reference or demo data.

A seeder is a class annotated #[Seeder] that implements SeedInterface::run(EntityManager $em):

The #[Seeder] attribute configures two parameters:

Available commands:

Security: auth, password, middlewares, csrf

Authentication

Auth is driven from app.config.php.

The framework supports two guards:

• session
• token

The token guard relies on JwtManager.

Typical configuration:

AuthManager API:

• attempt()
• login()
• logout()
• check()
• user()
• hasRole()
• generateToken()

Session login example:

Token login example:

Twig exposes:

• auth_check()
• auth_user()
• auth_has_role()
• csrf_token()

PasswordManager

The PasswordManager service provides:

• hash()
• verify()
• needsRehash()
• generate()
• getInfo()

Example:

Middlewares

Supported attributes:

• #[Middleware(...)] — attaches a middleware to a class or method
• #[RateLimit(...)] — rate limit on a route
• #[Maintenance(...)] — maintenance mode
• #[IsGranted(roles: [...])] — role-based access, shortcut for RoleMiddleware

Core middlewares:

• AuthMiddleware — checks that the user is authenticated
• GuestMiddleware — checks that the user is not logged in
• RoleMiddleware — checks a specific role
• IsGrantedMiddleware — checks one or more roles via #[IsGranted]
• RateLimitMiddleware — general rate limiting
• AuthRateLimitMiddleware — rate limiting on authentication
• CsrfMiddleware — CSRF validation on POST/PUT/PATCH/DELETE requests

Application middleware example:

Usage example with #[Middleware]:

Example with #[IsGranted]:

CSRF

The CSRF manager stores tokens in the session under _csrf_tokens.

Behavior:

• generation via generateToken()
• default expiration of 3600 seconds
• validation via validateToken()
• integration in forms via form_csrf() and csrf_token()

Events

NeoPHP ships an event dispatcher and several core events:

• RequestEvent
• ResponseEvent
• ExceptionEvent

Application listeners are expected in src/<Project>/App/Event/Listener.

They can be declared:

• via #[AsListener(event: ..., priority: ...)]
• via EventSubscriberInterface

Full example:

Example in a controller:

Crons

NeoPHP ships a scheduled task system runnable via the CLI.

Application crons are expected in the current project and can be run manually or automatically via the operating system.

Creating a cron

To generate a new cron:

Example:

The generator automatically creates the cron file in the target project.

Listing crons

To display all crons available in a project:

This command notably shows:

• the cron name
• its description
• its frequency
• its status

Running crons

To run all of a project's crons:

This is the command that should be scheduled automatically by the operating system.

Automatic cron execution

Linux

On Linux, crons are usually driven via crontab.

Open the cron configuration:

Run NeoPHP crons every minute:

Concrete example:

Check cron logs:

macOS

macOS also supports crontab.

Open the configuration:

Add:

Example:

Check scheduled tasks:

Windows

On Windows, use Task Scheduler.

Command to run:

Example:

Recommended configuration:

• trigger: every minute
• program: php.exe
• arguments:

Task Scheduler can be opened with:

Docker

Example with a simple loop:

Example via docker-compose:

Recommendations

In production, it is recommended to:

• run cron:run every minute
• log errors via the Logger
• avoid overly long blocking operations
• use queues for heavy processing
• monitor executions via application or system logs

Cache, logs, mailer, profiler, and errors

Cache

The Cache service is driven by cache.config.php.

Available drivers:

• files storage in src/<Project>/Storage/<path>
• redis via predis/predis
• array in-memory storage for short-lived use or tests

API:

• set()
• get()
• delete()
• clear()
• has()
• remember()

Example:

Logger

The Logger service reads logger.config.php and handles:

• log levels
• channels
• rotation
• zip archiving

Supported levels:

• debug
• info
• notice
• warning
• error
• critical
• alert
• emergency

Example:

Mailer

The neo/Core/Utils/Mailer/ folder registers a Mailer service based on PHPMailer.

Configuration:

• src/<Project>/Config/mailer.config.php
• current driver via default
• sender via from
• SMTP via drivers.smtp

Main API:

• to()
• subject()
• body()
• template()
• cc()
• bcc()
• attach()
• send()
• getSentMails()

In a controller, getMailer() is available via the controller extension.

Example:

If the mailer is disabled, sending is skipped and a warning is logged.

Profiler

The neo/Core/Profiler/ folder activates a debug bar only over HTTP and only when app.config.php sets environment = dev.

Exposed collectors:

• HTTP request
• resolved route and parameters
• SQL queries
• dispatched events
• logs
• authenticated user
• resolved translations and missing keys
• sent emails

The toolbar is injected into HTML responses. It is skipped for JsonResponse, RedirectResponse, and non-HTML content.

Error handling

ErrorHandler:

• intercepts exceptions and PHP errors
• logs errors
• dispatches an ExceptionEvent
• renders errors/<code>.html.twig if present
• otherwise provides an HTML fallback
• shows more detail in dev

Example error views:

Example 404.html.twig:

Markdown

The Tools/Markdown module provides a dependency-free Markdown parser. It converts Markdown text or a .md file into an array of structured blocks, rendered via Twig.

Usage from a template

The markdown_blocks() function is available in every Twig template:

The md_inline filter applies inline formatting (bold, italic, code, links):

Usage from PHP

Block types returned: heading, paragraph, code, list, table, quote, hr.

CLI and generators

Display global help:

Display help for a command:

The console automatically loads:

• the framework's native commands in neo/**/Commands/
• application commands in src/<Project>/App/Commands/

Available native commands:

• project:create
• project:delete
• project:sync
• app:serve
• app:make:command
• app:make:service
• app:composer:require
• asset:reload
• cache:clear
• cron:list
• cron:run
• database:create
• database:orm:diff
• database:migration:migrate
• database:migration:rollback
• database:migration:status
• debug:router
• generate:default:config
• make:config
• make:controller
• make:cron
• make:entity
• make:middleware
• make:event
• make:event:listener
• make:test
• make:test:auto
• run:test
• run:test:all
• translation:sync

Main generators

Examples:

Example interactive config command:

You could then enter, for example:

• smtp.host
• smtp.port
• smtp.user
• smtp.pass

The generator will write a nested PHP array.

Application commands

app:make:command lets you generate a command in the target project. Once created in src/<Project>/App/Commands/, it is automatically detected by the console alongside native commands.

Example:

Project maintenance

Examples:

PHPUnit tests

The framework ships a per-project test layer with PHPUnit 13.2.

Available commands:

• make:test
• make:test:auto
• run:test
• run:test:all

On the first make:test or make:test:auto, NeoPHP generates:

• src/<Project>/Tests/bootstrap.php
• src/<Project>/Tests/phpunit.xml
• src/<Project>/Tests/Config/database.config.test.php
• the Unit, Feature, Database, Middleware folders

Base classes:

• TestCase
• FeatureTestCase
• DatabaseTestCase
• MiddlewareTestCase

Confirmed features:

• HTTP request simulation for feature tests
• transactions and automatic rollback for database tests
• config overrides via *.config.test.php
• dev-to-test schema sync
• junit.xml reports and HTML coverage

Manual tests

Examples:

Automatic generation with #[Test]

The automatic system relies on the Neo\Core\Testing\Attribute\Test attribute.

It can be placed:

• on a class
• on a public method

Current signature:

What make:test:auto does:

• prepares the PHPUnit scaffold if needed
• scans all PHP files in the project
• loads classes that contain #[Test]
• reads the attribute at the class and method level
• infers a test type
• picks a template
• generates the file in Tests/<Type>/

Type inference when type = auto:

• Repository => database
• Controller => feature
• Middleware => middleware
• otherwise => unit

Example on a service class:

Example on a repository:

Example on a controller method:

Useful options:

Deployment

The app:make:deployment command prepares an FTP deployment from src/<Project>/Config/deploy.config.php.

The flow implements:

• temporary patch of app.config.php to prod
• temporary patch of public/index.php
• merge of the root composer.json and the project composer.json
• dependency installation with --no-dev
• compression of vendor/
• FTP upload of the framework, the project, and the public folder
• upload of vendor.zip
• execution of a temporary unzip script on the server side

Expected keys in deploy.config.php:

• ftp.host
• ftp.user
• ftp.pass
• remote.domain
• remote.framework_dir
• remote.public_dir

Example:

Dependencies and requirements

PHP

• PHP >= 8.5

Required PHP extensions

• ext-pdo
• ext-zip
• ext-libxml
• ext-dom
• ext-ftp
• ext-iconv
• ext-curl
• ext-simplexml
• ext-fileinfo

Main dependencies

• twig/twig
• twig/intl-extra
• psr/container
• matthiasmullie/minify
• wikimedia/less.php
• phpmailer/phpmailer
• predis/predis

Development dependencies

• phpunit/phpunit
• phpstan/phpstan

Summary

NeoPHP currently covers:

• multi-project application core
• DI container with autowiring
• configuration via PHP files
• HTTP layer, responses, sessions, cookies, and flash
• attribute-based routing
• controllers and Twig views
• CSS, JS, and Less asset pipeline
• string-based translation, one file per locale, CLI sync
• Data Mapper ORM: annotated POPO entities (#[Entity], #[Column], relations), EntityManager, EntityRepository
• entity-driven migrations via database:orm:diff
• database migrations and schema snapshot tracking
• forms via FormFactory / FormBuilder, validation, upload, and CSRF
• session / token auth, password, middlewares, and #[IsGranted]
• events and crons
• cache, logs, mailer, profiler, and error handling
• generation and admin CLI (project:create, make:entity, database:orm:diff, etc.)
• manual testing and automatic generation via #[Test]
• built-in FTP deployment

The key point of the repository stays the same:

• neo/ holds the engine
• src/ holds the applications
• php bin/neo ... drives most of the workflow