README

Project-root discovery and named path resolution for PHPdot.

One absolute answer to "where is X on disk?" for the whole framework — configured in a single file, with no __DIR__ sprawl and no runtime guesswork. Paths are declared once via phpdot/config and auto-scaffolded via phpdot/package.

Install

composer require phpdot/path

Requires PHP 8.4+. No per-package wiring: as long as your project runs phpdot/package's post-autoload-dump hook, installing phpdot/path scaffolds config/path.php (once, never overwritten) and its #[InstallHook] writes the absolute project root into base — automatically.

Quick Start

PathRegistry is a container singleton bound to PathRegistryInterface — inject the contract:

use PHPdot\Path\Contract\PathRegistryInterface;

$path = $container->get(PathRegistryInterface::class);

$path->base();          // /var/www/app
$path->config();        // /var/www/app/config
$path->vendor();        // /var/www/app/vendor
$path->public();        // /var/www/app/public
$path->protected();     // /var/www/app/protected
$path->get('uploads');  // /var/www/app/storage/uploads
$path->has('uploads');  // true

Every returned path is absolute. An unmapped name throws PathNotMapped — paths are explicit, never guessed.

Architecture

graph TD
    REQUIRE["composer require phpdot/path"]

    subgraph Install ["Install (CLI only)"]
        direction TB
        SCAFFOLD["phpdot/package<br/><br/>scaffolds config/path.php —<br/>base empty, {path.base}/… values"]
        FILL["PathInstaller #[InstallHook]<br/><br/>writes the absolute project<br/>root into base"]
        SCAFFOLD --> FILL
    end

    CONFIG["config/path.php<br/><br/>base + named paths,<br/>yours to edit"]

    subgraph Runtime
        direction TB
        ROOT["ProjectRoot<br/><br/>base, or auto-detected<br/>from Composer when empty"]
        REGISTRY["PathRegistry<br/><br/>resolves paths absolute;<br/>config + vendor from composer.json"]
        ROOT --> REGISTRY
    end

    REQUIRE --> Install --> CONFIG --> Runtime

Configuration

config/path.php is one section: base plus any number of named paths. Every string entry is a path — there is no fixed list, so add names freely.

// config/path.php — generated once, yours to edit
return [
    'base'      => '',                          // empty = auto-detect the root
    'public'    => '{path.base}/public',
    'protected' => '{path.base}/protected',
    'uploads'   => '{path.protected}/uploads',  // any custom name
    'logs'      => '{path.base}/var/log',
];

Two placeholders are available:

config and vendor are not listed here — they are read from composer.json (extra.phpdot.config-dir and config.vendor-dir), the single source of truth, so they can never drift. Non-string entries (such as environment-override sub-arrays) are ignored.

The base directory

base is a normal, editable config key. Its value decides how the root is found — the resolved paths are absolute either way:

If the install hook doesn't run, base simply stays empty and auto-detects at runtime.

API

PathRegistryInterface:

config() and vendor() are derived from composer.json; the others come from config/path.php. All are accessible via get('<name>') too.

Standalone

Outside a container, build it directly — base comes from config/path.php (set it, or leave it empty to auto-detect the root from Composer):

use PHPdot\Config\Configuration;
use PHPdot\Path\PathRegistry;

$path = new PathRegistry(new Configuration('/abs/project/config'));

Development

composer test        # PHPUnit (15 tests)
composer analyse     # PHPStan level 10
composer cs-fix      # PHP-CS-Fixer
composer check       # All three

License

MIT