Php X Sendfile Laravel Package

Getting Started

• Install the package via Composer and, if the package ships a config file, publish it (php artisan vendor:publish --tag=...). Check the package’s service provider first to see how the project root is resolved and whether a helper or facade is available.
• As of 1.1.0, you can set a custom or absolute path for the project root. This is the first thing to configure if your Laravel app does not live at the repository root (monorepo, Docker volume, custom public directory, etc.). Look for a config key such as project_root or an environment variable like PROJECT_ROOT.
• First use case: an Artisan command or installer that writes files to the host application’s root rather than the package’s directory. Example: project_path('some-file.php') or app(ProjectRoot::class)->path('some-file.php') (replace with the package’s actual helper/class).

Implementation Patterns

• Monorepo / subdirectory apps: Set the custom root in config/project-root.php or .env to the monorepo root, then use the package’s path helper to resolve shared assets, write generated code, or locate templates relative to that root.
• Package service providers: When your package needs to write to the consuming app, resolve paths through this package’s root resolver instead of base_path(). This lets the host app override the root without editing your package.
• Testing: Bind a temporary directory as the project root in your test suite ($this->app->instance(ProjectRoot::class, new ProjectRoot($tempDir))) to avoid polluting the real project. Reset the binding in tearDown().
• Docker / CI: Set PROJECT_ROOT=/var/www/html (or the appropriate mount point) so path resolution matches the runtime environment. Remember to clear config cache after changing env vars.
• Multi-tenant / dynamic roots: If the package exposes a resolver contract, bind a custom implementation in a service provider that returns tenant-specific absolute paths. Keep the default fallback for single-tenant contexts.
• File generation commands: Read templates from the package (__DIR__.'/stubs') but write output to project_path('app/...') so generated files land in the host app, not inside vendor/.
• Graceful fallback: Only override the root when necessary. If no custom path is set, rely on the package’s default detection (likely base_path() or Composer’s installed root) to avoid breaking standard Laravel setups.

Gotchas and Tips

• Absolute vs relative paths: The 1.1.0 feature expects an absolute path. Relative paths may be resolved from the current working directory, which varies between CLI, queue workers, and HTTP requests. Always pass an absolute path.
• Trailing slashes: Normalize with rtrim($path, DIRECTORY_SEPARATOR) before joining segments to avoid double separators (//) in generated paths.
• Windows compatibility: Use DIRECTORY_SEPARATOR or Laravel’s Illuminate\Filesystem\Filesystem helpers. Avoid hardcoding /.
• Config caching: If you set the root via env('PROJECT_ROOT'), make sure the env var is read inside a config file. After changing it, run php artisan config:cache (or config:clear during development). Cached config ignores later env changes.
• Symlinks: realpath() resolves symlinks. If you need to preserve the symlink path (e.g., for deployment scripts), store the original string and avoid realpath() unless necessary.
• Testing isolation: Always reset any custom root binding between tests. Use putenv or config overrides carefully; leaked state causes flaky path assertions.
• Debugging: Dump the resolved root early: dd(app(ProjectRoot::class)->path()) or the package’s helper. Check that the service provider runs before your command.
• Extension points: Look for a config option to swap the resolver class or a container binding. If the package uses a singleton, you can override it in AppServiceProvider::register() with $this->app->instance(...).
• Deployment: When using a custom root in production, document it in your .env.example and deployment scripts. A missing or incorrect PROJECT_ROOT often surfaces as “file not found” errors in generated code or asset paths.