Process · v2.x

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.

Module

Manager NeoPHP\Process\Package\PackageManager (final)
Interface NeoPHP\Process\Package\PackageManagerInterface
Attribute #[Process(provider: PackageProvider::class)]
Requires nothing

Inject PackageManagerInterface in a service, a command or a controller:

use NeoPHP\Process\Package\PackageManagerInterface;

public function __construct(private PackageManagerInterface $package)
{
}

The module is enabled by default. To disable it in a project, add it to config/config.php (see the Kernel documentation):

NeoPHP\Process\Package\PackageManager::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.

Installing a package

php bin/neo neophp:package:install acme/neo-billing
  1. Composer must know the package with the type neophp-package: any other type is refused before the installation, and checked again after it (the package is then removed).
  2. composer require acme/neo-billing runs in the project, with its output and its questions.
  3. The configuration files of the package are copied into config/packages/billing/.
  4. The import of its routes is added to config/routes.yaml (resource: '@billing') when the package has routes.
  5. var/cache/ is emptied.

When the package has migrations, run php bin/neo migration:migrate.

The package is then enabled like any module: its manager is registered by the kernel, its services can be injected, its commands appear in php bin/neo list. To disable it, add its manager to config/config.php:

Acme\Billing\BillingManager::class => false,

composer require alone installs a package too: the modules are discovered the same way, but the configuration is not copied (run neophp:package:update <name> to copy it) and the routes are not imported (add the import yourself, see Routes).

Commands

Command Description
neophp:package:install <package> [--dev] requires the package with Composer (acme/neo-billing, acme/neo-billing:^1.2), copies its configuration and clears the cache; --dev adds it to require-dev
neophp:package:list the installed NeoPHP packages: Composer name, name, version, status (enabled / disabled in config/config.php) and configuration directory
neophp:package:update [package] updates one package, or every NeoPHP package, with composer update --with-dependencies, then copies the new configuration files
neophp:package:remove <package> [--purge] removes the entries of the package from config/config.php and the import of its routes from config/routes.yaml, runs composer remove, clears the cache; --purge also deletes config/packages/<name>/
neophp:package:create <package> [--path=] [--namespace=] [--description=] [--link] generates the skeleton of a package (see Creating a package)

A package is named by its Composer name (acme/neo-billing) or by its name (billing). --force overwrites the configuration files changed in the project (install, update) and the files of an existing directory (create). neophp:package:remove asks for a confirmation, except with -n.

The entries of config/config.php and config/routes.yaml are removed before composer remove, because the Composer scripts of the project boot the kernel, which refuses a key that is not a module; they are restored when Composer fails. The tables created by the migrations of a removed package are kept.

Configuration files

The files of the config/ directory of the package (extra.neophp.config) are copied into config/packages/<name>/ of the project, with the same structure. The YAML files are loaded under the key packages.<name>.<file>: config/packages/billing/billing.yaml gives packages.billing.billing (see the Config documentation).

Status Meaning
created the file did not exist
skipped the file is identical, or it was changed in the project and the package did not change it
updated the package changed the file and the project did not: the new version replaces it
changed the package and the project changed the file: the project file is kept, the new version is written next to it with the .dist extension
overwritten --force replaced the file

Merge a .dist file into the project file, then delete it; the next update removes it when both files are identical. config/packages/<name>/.package.json stores the fingerprint of the files copied by the last installation or update: commit it with the configuration.

Routes

The routes of a package are the #[Route] controllers of its src/Controller/ directory, or the routes file given in extra.neophp.routes. neophp:package:install adds their import to config/routes.yaml:

package_billing:
    resource: '@billing'

Edit the import like any other one: prefix: /billing, name_prefix: billing_, middlewares: [auth]... The import of a disabled package is ignored (see the Routing documentation).

Templates, translations and assets

Element In the package Used with Override in the project
templates templates/ render('@billing/invoice') templates/packages/billing/invoice.php
translations translations/billing.fr.yaml translate('key', {}, 'billing') translations/billing.fr.yaml (same keys)
assets assets/css/billing.css asset('@billing/css/billing.css') assets/packages/billing/css/billing.css

The assets are compiled into public/builds/packages/billing/ (also by asset:reload). php bin/neo translation:generate --package=billing extracts the keys of the templates and the code of the package into its translations/ directory. See the View, Translation and Asset documentation.

Database

The entities of src/Entity/ of the package (extra.neophp.entities) are mapped by the ORM, and the migrations of its migrations/ directory (extra.neophp.migrations, namespace extra.neophp.migrations_namespace, <namespace of the module>\Migrations by default) run with the ones of the project:

php bin/neo migration:migrate
php bin/neo migration:status

The tables of the package entities belong to the package: make:migration of the project never touches them. While developing a package, generate its migrations from its entities:

php bin/neo make:migration --package=billing

See the ORM documentation.

Profiler

In debug, /_profiler/packages (link Packages of the profiler) lists the NeoPHP packages with their version, their status (Active / Inactive in the current environment), the environments set in config/config.php (all, dev, test, all except prod, none) and what they provide, then every module of the project (see the WebProfiler documentation).

Creating a package

php bin/neo neophp:package:create acme/neo-billing
Option Default Description
--path packages/<name> directory of the package, relative to the project or absolute
--namespace Vendor\Name (Acme\Billing) PHP namespace of the package
--description <Name> package for NeoPHP. description of composer.json
--link adds the directory as a Composer path repository of the project and installs the package (neophp:package:install acme/neo-billing:*@dev)

The name of the package is acme/neo-billing without vendor and neo- / neophp- prefix, in snake_case: billing. The generated package:

packages/neo-billing/
├── .gitignore
├── composer.json
├── README.md
├── assets/
│   └── css/billing.css
├── config/
│   └── billing.yaml
├── src/
│   ├── BillingManager.php
│   ├── BillingManagerInterface.php
│   ├── Command/HelloCommand.php
│   ├── Controller/BillingController.php
│   └── Provider/BillingProvider.php
├── templates/
│   └── hello.php
└── translations/
    └── billing.en.yaml

With --link, the package works right away:

php bin/neo neophp:package:create acme/neo-billing --link
php bin/neo billing:hello Neo

and the page /billing/hello/Neo renders @billing/hello with its stylesheet and its translated message.

composer.json

{
    "name": "acme/neo-billing",
    "type": "neophp-package",
    "require": {
        "php": ">=8.2",
        "neophp/framework": "^2.1"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Billing\\": "src/"
        }
    },
    "extra": {
        "neophp": {
            "name": "billing",
            "modules": ["Acme\\Billing\\BillingManager"]
        }
    }
}
Key Default Description
type neophp-package: required by neophp:package:install
extra.neophp.modules [] the managers of the package, discovered by the kernel
extra.neophp.name from the Composer name name of the package (snake_case): config/packages/<name>/, @<name>/
extra.neophp.config config directory of the configuration files to copy
extra.neophp.templates templates directory of the templates
extra.neophp.translations translations directory of the translation files
extra.neophp.assets assets directory of the assets
extra.neophp.routes src/Controller controllers directory or routes file imported with @<name>
extra.neophp.entities src/Entity directory of the entities
extra.neophp.migrations migrations directory of the migrations
extra.neophp.migrations_namespace <namespace>\Migrations namespace of the migrations

Manager and provider

The manager is the entry point of the module: a final class declared with #[Package], at the root of src/, implementing its interface. Its provider registers the services in the container (see the Container and Kernel documentation):

<?php

declare(strict_types=1);

namespace Acme\Billing;

use Acme\Billing\Provider\BillingProvider;
use NeoPHP\Component\Kernel\Attribute\Package;
use NeoPHP\Component\Session\SessionManager;

#[Package(provider: BillingProvider::class, requires: [SessionManager::class])]
final class BillingManager implements BillingManagerInterface
{
}
<?php

declare(strict_types=1);

namespace Acme\Billing\Provider;

use Acme\Billing\BillingManager;
use Acme\Billing\BillingManagerInterface;
use NeoPHP\Component\Config\ConfigManagerInterface;
use NeoPHP\Component\Container\ContainerManagerInterface;
use NeoPHP\Component\Container\Contract\AbstractProvider;

/**
 * @internal
 */
class BillingProvider extends AbstractProvider
{
    public function register(ContainerManagerInterface $container): void
    {
        $container->singleton(BillingManagerInterface::class, static function (ContainerManagerInterface $container): BillingManagerInterface {
            return new BillingManager((array) $container->get(ConfigManagerInterface::class)->get('packages.billing.billing', []));
        });

        $container->alias(BillingManager::class, BillingManagerInterface::class);
    }
}

requires lists the modules the package needs: they are loaded before it, and cannot be disabled while the package is enabled.

What is discovered

Element Where in the package
console commands any #[AsCommand] class of src/
listeners and subscribers any #[AsListener] class or EventSubscriberInterface of src/
middlewares #[AsMiddleware] classes of src/
queue handlers #[AsMessageHandler] classes of src/
scheduled tasks #[AsScheduledTask] classes and ScheduleProviderInterface of src/
voters #[AsVoter] classes of src/
normalizers #[AsNormalizer] classes of src/
profiler elements #[AsProfiler] classes of src/
view helpers src/**/Helper/View/
routes src/Controller/ or extra.neophp.routes (imported with @<name>)
templates templates/ (@<name>/)
translations translations/
assets assets/ (asset('@<name>/...'))
entities and migrations src/Entity/, migrations/
configuration config/ (copied into config/packages/<name>/)

The elements of a disabled package are ignored. In debug, the caches of the discoveries are rebuilt when a package is installed or removed.

Developing a package in a project

The package can live in the project (packages/neo-billing/, the default of neophp:package:create) and be installed with a Composer path repository: --link adds it to composer.json:

"repositories": [
    { 
        "type": "path", 
        "url": "packages/neo-billing", 
        "options": { 
            "symlink": true
        }
    }
]
php bin/neo neophp:package:install acme/neo-billing:*@dev

The symlink makes every change of the package visible in the project. In debug, the caches of the modules and listeners are rebuilt when a package is installed or removed; after a change of composer.json of the package, run composer update acme/neo-billing.

Publishing a package

Push the directory of the package to its own Git repository, tag a version (v1.0.0) and submit it on Packagist: php bin/neo neophp:package:install acme/neo-billing then works in any NeoPHP project.

Composer

The commands run Composer in the project with the first binary found:

  1. the COMPOSER_BINARY environment variable (/usr/local/bin/composer, composer.phar...);
  2. composer.phar at the root of the project;
  3. composer from the PATH.

A .phar file is run with the PHP binary of the console. proc_open() must be enabled.

API

PackageManagerInterface

NeoPHP\Process\Package\PackageManagerInterface (implemented by PackageManager(string $rootPath)):

Method Description
all(): array the installed NeoPHP packages by Composer name (see InstalledPackages in the Kernel documentation)
find(string $package): ?array a package by its Composer name or its name
install(string $package, bool $dev = false, bool $force = false): array ['package' => [...], 'files' => [path => status]]
update(?string $package = null, bool $force = false): array [name => ['package' => [...], 'files' => [...]]]
remove(string $package, bool $purge = false): array ['package' => [...], 'files' => [...]]
publishConfig(string $package, bool $force = false): array copies the configuration of an installed package: [path => status]
addPathRepository(string $path): bool adds a Composer path repository to composer.json; false when it already exists
getConfigDirectory(string $package): string config/packages/<name>
clearCache(): int empties var/cache/, returns the number of removed files

Status constants: STATUS_CREATED, STATUS_UPDATED, STATUS_OVERWRITTEN, STATUS_CHANGED, STATUS_SKIPPED, STATUS_REMOVED.

$result = $this->package->install('acme/neo-billing:^1.2');
$configDirectory = $this->package->getConfigDirectory('billing');

Exceptions

NeoPHP\Process\Package\Exception\PackageException extends FrameworkException. It is thrown for an invalid package name or namespace, a package that is not a NeoPHP package or is not installed, a failed Composer command, a non-empty directory given to neophp:package:create, an invalid composer.json, or a file that cannot be written.

Changelog

  • v2.1.0 — Package process: neophp:package:install, neophp:package:list, neophp:package:update, neophp:package:remove and neophp:package:create, configuration copied into config/packages/<name>/ with .dist files for the files changed in the project, import of the routes in config/routes.yaml, skeleton with a controller, translations and assets, PackageManagerInterface.