Documentation menu
On this page
Process · v2.x
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.
Module
| Manager | NeoPHP\Process\Installer\InstallerManager (final) |
| Interface | NeoPHP\Process\Installer\InstallerManagerInterface |
| Attribute | #[Process(provider: InstallerProvider::class)] |
| Requires | nothing |
Inject InstallerManagerInterface in a service, a command or a controller:
use NeoPHP\Process\Installer\InstallerManagerInterface;
public function __construct(private InstallerManagerInterface $installer)
{
}
The module is enabled by default. To disable it in a project, add it to config/config.php (see the Kernel documentation):
NeoPHP\Process\Installer\InstallerManager::class => false,
The public API of the module is its manager and its interface, Contract\, the attributes, the exceptions, the events and the classes documented below. The classes marked @internal are used by the framework only.
Project setup
Until the framework is published on Packagist, require it through a Composer path repository (symlink). Create a folder next to the framework with this composer.json:
{
"name": "neophp/test",
"type": "project",
"repositories": [
{ "type": "path", "url": "../neophp", "options": { "symlink": true } }
],
"require": {
"php": ">=8.2",
"neophp/framework": "*@dev"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
},
"scripts": {
"neo:install": "@php vendor/bin/neo install",
"post-create-project-cmd": "@neo:install",
"post-install-cmd": "@neo:install",
"post-update-cmd": "@neo:install"
},
"minimum-stability": "dev",
"prefer-stable": true
}
Then:
composer install
php bin/neo serve
composer install runs neo install automatically. A generated file that was deleted is created again on the next composer install or composer update.
Install command
php bin/neo install
php bin/neo install --force
| Behavior | Description |
|---|---|
| missing file | created |
| existing file | kept (skipped, shown with -v) |
existing file with --force |
overwritten |
existing .env |
the missing variables are appended (updated), even without --force |
| missing directory | created with a .gitkeep |
composer.json without App\ |
the App\ → src/ PSR-4 autoload is added (updated); run composer dump-autoload |
Each line of the report shows a status: created, overwritten, updated or skipped.
Generated files
.env
.gitignore
assets/css/app.css
bin/neo
config/config.php
config/routes.yaml
config/services.yaml
config/framework/api.yaml
config/framework/app.yaml
config/framework/asset.yaml
config/framework/cache.yaml
config/framework/csrf.yaml
config/framework/database.yaml
config/framework/event.yaml
config/framework/form.yaml
config/framework/http_client.yaml
config/framework/logger.yaml
config/framework/mailer.yaml
config/framework/middleware.yaml
config/framework/serializer.yaml
config/framework/upload.yaml
config/framework/view.yaml
config/packages/debug.yaml
config/packages/image.yaml
config/packages/mercure.yaml
config/packages/neo_ai.yaml
config/packages/notifier.yaml
config/packages/orm.yaml
config/packages/qr_code.yaml
config/packages/queue.yaml
config/packages/scheduler.yaml
config/packages/security.yaml
config/packages/translation.yaml
config/packages/web_profiler.yaml
public/.htaccess
public/index.php
src/Controller/HomeController.php
src/Kernel.php
templates/base.php
templates/home/index.php
Directories: assets/, config/packages/, migrations/, public/builds/, src/Command/, src/Entity/, src/Event/, src/Form/, src/Listener/, src/Message/, src/MessageHandler/, src/Middleware/, src/Repository/, src/Security/, src/Service/, src/Task/, tests/, translations/, var/cache/, var/log/, var/sessions/.
bin/neo is made executable. It boots the kernel with the environment given by --env and runs the console (see the Console documentation). It stops with an error when the Console module is disabled in config/config.php.
config/config.php enables or disables the modules per environment (see the Kernel documentation). The generated file enables WebProfilerManager and NeoAiManager in the dev environment only.
Environment file
The generated .env contains a random APP_SECRET (64 hexadecimal characters), APP_URL, the base URL of the absolute URLs generated in the console, APP_TIMEZONE, the default timezone (UTC), and a random MERCURE_JWT_SECRET shared with the Mercure hub (see the Mercure documentation). VAPID_PUBLIC_KEY and VAPID_PRIVATE_KEY are empty: generate them with php bin/neo notifier:vapid to enable the push notifications (see the Notifier documentation).
APP_NAME=NeoPHP
APP_ENV=dev
APP_DEBUG=1
APP_SECRET=...
APP_URL=http://127.0.0.1:8000
APP_TIMEZONE=UTC
DATABASE_URL="sqlite:///%kernel.root_path%/var/data.db"
MAILER_DSN="null://null"
MAILER_RECIPIENTS=
###> neo_ai ###
# NeoAI development assistant (active only when APP_DEBUG=1)
# Provider of the "default" connection: ollama, openai, anthropic, gemini, mistral, groq, openrouter, lmstudio, vllm, openai_compatible
NEO_AI_PROVIDER=ollama
NEO_AI_MODEL=qwen2.5-coder:7b
# Key and base URL of the "default" connection (empty = none / provider default), e.g. NEO_AI_API_KEY=${OPENAI_API_KEY}
NEO_AI_API_KEY=
NEO_AI_BASE_URL=
# Real keys go in .env.local (never commit them)
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GEMINI_API_KEY=
MISTRAL_API_KEY=
OLLAMA_URL=http://localhost:11434
###< neo_ai ###
###> queue ###
QUEUE_DSN="database://default"
###< queue ###
The neo_ai block configures the NeoAI development assistant (see the NeoAI documentation). Every variable must exist, even empty, because config/packages/neo_ai.yaml references them with %env(...)%. Put the real API keys in .env.local, never in .env. By default the assistant uses a local Ollama server, so no data leaves the machine.
When .env already exists, only the variables it does not define (even commented out) are appended, with their comments. See the Dotenv documentation for the file format.
API
InstallerManagerInterface
NeoPHP\Process\Installer\InstallerManagerInterface, implemented by InstallerManager(?string $skeletonDir = null) (default skeleton Resources/skeleton):
| Method | Description |
|---|---|
install(string $projectDir, bool $force = false): array |
installs the skeleton; returns path => status |
getSkeletonDir(): string |
skeleton directory |
getFiles(): array |
files to generate (relative path => stub file) |
getDirectories(): array |
directories to create |
| Constant | Value |
|---|---|
STATUS_CREATED |
created |
STATUS_OVERWRITTEN |
overwritten |
STATUS_UPDATED |
updated |
STATUS_SKIPPED |
skipped |
InstallerManager constants: STUB_EXTENSION (.stub), EXECUTABLES, MERGEABLE (.env), DIRECTORIES. Stubs can use the {{ app_secret }} variable.
<?php
declare(strict_types=1);
use NeoPHP\Process\Installer\InstallerManager;
$report = (new InstallerManager())->install(__DIR__, false);
foreach ($report as $path => $status) {
echo $status . ' ' . $path . PHP_EOL;
}
Exceptions
NeoPHP\Process\Installer\Exception\InstallerException: the project directory does not exist or is not writable, a file cannot be written, or composer.json is not valid JSON.
Changelog
- v2.14.0 —
config/packages/security.yamlshows the optionaljwt,two_factorandoauthoptions. - v2.13.0 — The
healthoptions are written inconfig/framework/app.yaml, disabled by default. - v2.12.0 — New projects get
strict_associations: trueinconfig/framework/serializer.yaml,http_method_override_header: falseinconfig/framework/app.yamlandmax_account_attempts: 25inconfig/packages/security.yaml. - v2.9.0 —
config/packages/qr_code.yamlis generated. - v2.7.0 —
config/packages/notifier.yamlis generated;VAPID_PUBLIC_KEY,VAPID_PRIVATE_KEYandVAPID_SUBJECTare added to.env. - v2.6.0 —
config/packages/image.yamlis generated (presetsthumbnailandmedium),/public/media/cache/is added to.gitignore. - v2.3.0 —
config/packages/mercure.yamlis generated;MERCURE_URL,MERCURE_PUBLIC_URLand a randomMERCURE_JWT_SECRET(64 hexadecimal characters) are added to.env. - v2.2.0 —
APP_TIMEZONEwritten in.envandtimezoneinconfig/framework/app.yaml. - v2.0.0 —
InstallerManageris thefinalentry point of the module, declared with#[Process];InstallerManagerInterfacereplacesContract\InstallerInterface;Contract\AbstractInstalleris merged into the manager; the internal classes are marked@internal;config/config.phpis generated,src/Kernel.phpextendsKernel\Contract\AbstractKernel,bin/neochecks that the Console module is enabled, the NeoAI documentation path points toDocs/v2.x. - v1.40.0 —
config/framework/upload.yamlis generated,/public/uploads/is added to.gitignore. - v1.37.0 —
config/packages/queue.yamlandconfig/packages/scheduler.yamlare generated,QUEUE_DSNis added to.env, directoriessrc/Message/,src/MessageHandler/andsrc/Task/. - v1.26.0 —
config/packages/neo_ai.yamlis generated (NeoAI connections, context, scan and web options) and theNEO_AI_*,OPENAI_API_KEY,ANTHROPIC_API_KEY,GEMINI_API_KEY,MISTRAL_API_KEYandOLLAMA_URLvariables are added to.env. - v1.24.0 —
config/framework/api.yamlis generated (CORS, rate limiter, pagination, problem details, OpenAPI). - v1.23.0 —
config/framework/serializer.yamlis generated. - v1.20.0 —
config/packages/translation.yamland thetranslations/directory are generated. - Bugfix after v1.17.0 —
APP_URLwritten in.env. - v1.11.0 — The missing variables are added to an existing
.env. - v1.0.0 —
neo installgenerates the project files,bin/neoand theApp\autoload; existing files kept unless--force.