Path Composer Plugin Lib Laravel Package

Getting Started

This is a library, not a Laravel package — you almost never install it directly. It exists so that hostnet/path-composer-plugin (and any plugin you build yourself) can define VENDOR_DIR and BASE_DIR as constants during composer install/dump-autoload, without re-implementing Composer internals.

Minimal steps for a Laravel developer:

1. If you just want the constants, require the plugin, not the lib:

   composer require hostnet/path-composer-plugin
   

   Pulling hostnet/path-composer-plugin-lib in directly only makes sense when you are authoring your own Composer plugin that needs the path-resolution helpers.

2. After the first composer install, a generated file (typically vendor/hostnet/path-composer-plugin/src/constants.php or similar) will define('BASE_DIR', ...) and define('VENDOR_DIR', ...). Open that file first — it is the entry point to understanding what the lib produces.

3. First real use case in a Laravel app: a bootstrap script, CI helper, or custom autoloader that runs before Laravel boots, so base_path() and vendor_path() helpers are unavailable. That is precisely the gap this fills — you get BASE_DIR / VENDOR_DIR without bootstrapping the framework.

Implementation Patterns

1. Pre-bootstrap path resolution (public/index.php / artisan)

If you have bootstrap logic that needs the vendor directory before vendor/autoload.php is fully wired, require the generated constants file first:

require __DIR__.'/../vendor/hostnet/path-composer-plugin/src/constants.php';
// BASE_DIR and VENDOR_DIR are now defined
require VENDOR_DIR.'/autoload.php';

Useful when you have a public/index.php that must branch before Laravel can even autoload — e.g. a multi-tenant router that decides which bootstrap/app.php to load.

2. Fallback pattern — don't couple to the constant

Laravel helpers are the idiomatic choice inside app code. Reserve the constants for edge cases (CLI, composer scripts, PHP files outside the framework). When sharing a file between both contexts, guard:

$base = defined('BASE_DIR') ? BASE_DIR : base_path();

3. Composer-script / CI helpers

Scripts invoked from composer.json (post-install-cmd, post-autoload-dump) run with constants already defined by the plugin. Use BASE_DIR in custom PHP scripts:

"scripts": {
  "post-install-cmd": ["php tools/patch-config.php"]
}

tools/patch-config.php can require BASE_DIR.'/vendor/autoload.php' without knowing where it sits relative to the project root.

4. Building your own plugin

This is the primary reason the lib exists. Extend its base classes instead of re-implementing Composer\Plugin\PluginInterface and event hooks. The lib gives you path normalization and the composer event integration so your generateConstants()-style logic is boilerplate-free:

use Hostnet\PathComposerPlugin\...; // base classes the lib exposes

class MyPathPlugin extends AbstractPathPlugin
{
    // just implement the path rewriting you care about
}

5. Custom autoloaders / legacy bridges

When you include legacy code that hardcodes __DIR__.'/../../vendor' patterns, replace with VENDOR_DIR. This survives project relocation because the constant is regenerated on each composer install.

Gotchas and Tips

• This lib has essentially zero adoption (1 star, 0 dependents). Pin the exact version in composer.json and assume you may need to fork it. There is no community to bail you out on a breaking change.
• The constants go stale. They are written at install time. Move the project, deploy an image built elsewhere, or rename the directory and BASE_DIR still points at the old path until you run composer dump-autoload. In a Docker multi-stage build, run composer install in the final stage, not just the build stage.
• You may not need it in Laravel app code. base_path(), vendor_path() (Laravel 10+), app_path(), etc. all work once the app is booted. Fighting to use BASE_DIR inside a controller is a code smell — reserve the constants for the pre-app layer.
• VENDOR_DIR is not the same as storage_path(). Do not put generated/cached content under vendor; the constant only tells you where Composer installed dependencies. Write to storage/framework via Laravel helpers.
• Debugging: run composer install -vvv and watch for the post-autoload-dump event — the plugin fires there. If constants are missing, check event order and whether the plugin is actually enabled (composer plugins lists loaded plugins).
• Extension points: subclass the lib's base plugin class and override the constant-generation logic if you need extra constants (e.g. APP_ENV_DIR, PUBLIC_DIR). Hook additional Composer events via the plugin rather than editing the generated file — it will be overwritten.
• Commit the generated file? Generally no. Keep it gitignored to avoid merge conflicts between developers whose machine paths differ. Rely on composer install to regenerate.
• Namespace vs. constants: this library publishes constants, not autoloaded classes. Any code depending on them must require the generated file explicitly, or the plugin must register its autoload/files entry — confirm with composer show hostnet/path-composer-plugin-lib and inspect its extra block.
• Don't build tooling on the constants across environments you don't control (e.g. a package you distribute). Consumers may not have the plugin enabled, and defined() guards get brittle. Prefer passing paths in explicitly at your package boundary.