Distribution Module Laravel Package

Getting Started

ppi/distribution-module is not a standalone library — it is the base module for the PPI distribution, meaning it provides the baseline module class and default configuration that the distribution skeleton boots around. Requiring it on its own gives you nothing runnable; it only makes sense in the context of a PPI application skeleton that registers modules and lets this one supply the core wiring.

Minimal steps:

1. composer require ppi/distribution-module inside an existing PPI distribution checkout (not in an empty project).
2. Confirm the package is registered as a module in the application's module list/config — PPI's convention is a Module.php (or module.php) at the package root plus a config/ directory of YAML/service definitions.
3. Verify PSR-4 autoloading maps the distribution namespace to src/, then dump the autoloader (composer dump-autoload) before your first boot.
4. Boot the app and check the container builds; a clean container build is the real "it works" signal for this package.

Where to look first:

• composer.json — its require block tells you which framework/core versions it expects, and its extra/module metadata tells you how it self-registers.
• src/Module.php (or equivalent) — the register/boot entry point; this is the file that defines what the module actually contributes.
• config/ — routing, service definitions, and module defaults. This is also where you learn what you are allowed to override.

First use case: getting the distribution to boot in your environment, then layering your own application module next to it. Treat this package as the floor, not the building — your first real task is adding a module of your own that sits alongside it.

Implementation Patterns

Treat it as infrastructure you configure, not code you edit. The distribution module exists so that application code does not have to repeat core bootstrap concerns. Vendor-patch it only as a last resort; everything below is a supported way to change behaviour without forking.

Mirror its structure for your own modules. The fastest path to a working custom module is to copy the distribution module's shape: a Module class extending the framework's abstract module, a config/ directory with the same YAML conventions, and a PSR-4 autoload entry. Register it in the same module list the distribution module uses, and keep the distribution module first so its defaults are in place before your config layers on top.

Override via configuration, not by editing defaults. Module config in PPI is layered; application-level config loaded after the module's own config wins. Use that for routes, container parameters, and service definitions. If you need to swap an implementation, redefine the service or alias in your application config rather than touching config/ inside vendor/.

Hook behaviour through the event manager. Rather than subclassing or patching, attach listeners in your own module's register step to the framework's dispatch/routing events. This keeps your customisations isolated and survives a composer update that rewrites the vendor tree.

Pin and vendor. Given the release history (last tagged 2015, near-zero dependents), commit composer.lock and consider committing vendor/ppi/distribution-module into your repo. There is no realistic expectation that a missing Packagist entry or a yanked tag will be restored.

Integration tips: keep a bin/console-style entry point for cache-clearing and container inspection; run it after every config change rather than debugging a stale compiled config. Wire environment-specific values (debug flags, paths) through the app config layer, not the module defaults, so multiple environments share one vendor tree.

Gotchas and Tips

It is old, and that is the main risk. A 2015 last release means PHP 5.x-era code and Symfony/Zend components from that generation. Expect friction on PHP 7.4+ and near-certain breakage on PHP 8. If you are inheriting a project, pin your PHP version deliberately; if this is a greenfield evaluation, this package is a reason to look at a modern Symfony or Laminas skeleton instead.

"Base module for the distribution" is literal. The most common first mistake is composer require-ing it into a normal Laravel/Symfony app and wondering why nothing happens. It contributes configuration and a module class; without the distribution skeleton and module registration, it is inert.

Load order changes behaviour. Module defaults versus application config precedence, and listener priority in the event manager, both depend on registration order. If a route 404s or a service resolves to the wrong class, check the module array order before you check the code.

Compiled config will lie to you. PPI caches compiled container/config artifacts. After editing YAML, clear the cache; otherwise you will spend an hour debugging a change that was never loaded. Make cache-clearing part of your edit loop.

Autoload and namespace drift. If a class "cannot be found" from inside the module, it is almost always a PSR-4 mapping or a stale classmap rather than a missing file. composer dump-autoload and a check of the namespace-to-path mapping resolves most of it.

Debugging levers: dump the built container and the registered event listeners; that surfaces both service wiring problems and duplicate/absent listeners in one shot. For routing issues, dump the compiled route collection rather than reading YAML by hand.

Extension points, in order of preference: application config overrides → your own module's listeners → container service redefinition/aliasing → subclassing the module class → forking. Anything past the third option should come with a comment explaining why, because it is the layer most likely to be broken by a future update — and given this package's release cadence, updates are rare, which cuts both ways: stable, but also unpatchable.

Plan an exit. Budget migration effort rather than upgrade effort. The realistic path off this dependency is replacing the distribution bootstrap with a current framework skeleton and porting your modules' config and listeners across.