Project Root Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Synergy: Directly addresses Laravel’s dependency-aware path resolution gaps, where base_path()/storage_path() are project-root-centric but packages need to reference the host project’s root (e.g., for CLI tools, config generators, or asset pipelines). Ideal for:
  • Laravel Packages: Resolve host project paths (e.g., public_path()) from within vendored code.
  • Artisan Plugins: Reference project-specific directories (e.g., storage/framework/cache) without hardcoding.
  • Monorepos: Distinguish between package roots and project roots in complex dependency trees.
• Abstraction Layer: Provides a clean API (forPackage()->resolve()) over Composer’s autoloader, reducing cognitive load compared to manual path logic (e.g., dirname(__DIR__, 4)).
• Isolation: Operates independently of Laravel’s service container or Facades, avoiding namespace collisions.

Integration Feasibility

• Composer Ecosystem: Leverage Composer’s autoloader to infer package roots, ensuring compatibility with any PHP 7.4+ project (Laravel 8+ or standalone). No Laravel-specific dependencies.
• Zero Configuration: No .env keys, service provider bindings, or Laravel-specific setup required. Plug-and-play for path resolution.
• Namespace Safety: Uses \Konsulting\ProjectRoot, avoiding conflicts with Laravel’s Path facade or app() helper.

Technical Risk

Key Questions for TPM

1. When should ProjectRoot be used vs. Laravel’s base_path()?
   • Answer: Use ProjectRoot only for dependency-aware paths (e.g., vendor/package/storage). Reserve base_path() for project-wide paths.
2. How will this interact with Laravel’s APP_BASE_PATH or bootstrap/app.php?
   • Answer: Test with overridden APP_BASE_PATH; ensure ProjectRoot respects Composer’s autoloader hierarchy.
3. What’s the fallback if path resolution fails?
   • Answer: Return __DIR__ with a deprecation warning; log the failure for debugging.
4. Does this work with Laravel’s optimize or dump-autoload?
   • Answer: Yes, but verify path resolution stability post-optimization (Composer’s autoloader is preserved).
5. How will this scale in a large Laravel codebase with 50+ packages?
   • Answer: Profile method call overhead (negligible); cache results if resolving paths repeatedly.

Integration Approach

Stack Fit

• Service Providers: Resolve package-specific config/migration paths (e.g., ProjectRoot::forPackage('my-package')->resolve(__DIR__ . '/config')).
• Artisan Commands: Reference project roots from vendored commands (e.g., php artisan my:package-command).
• Packages: Avoid hardcoding base_path() when the package is a dependency. | | Symfony Components | Compatible (uses PSR-4 autoloading). |

Migration Path

1. Assessment Phase:
   • Audit all hardcoded path resolutions in the codebase, especially:
     • base_path('vendor/package/...')
     • __DIR__ or getcwd() hacks in dependency contexts.
   • Identify pain points where path logic fails in CI/CD or local dev.
2. Pilot Integration:
   • Replace one critical path (e.g., a package’s log directory) with ProjectRoot.
   • Test in CI/CD (Linux/Windows/macOS) and local dev with:

     composer install --prefer-dist
     composer install --prefer-source
     

3. Rollout Strategy:
   • Phase 1: Core packages (e.g., auth, payments) using ProjectRoot for dependency-aware paths.
   • Phase 2: Legacy codebases with custom path logic (refactor to use the package).
   • Phase 3: Document best practices (e.g., "use ProjectRoot for vendored packages; reserve base_path() for project-wide paths").

Compatibility

• Backward Compatibility: None. This is a new feature, not a replacement for existing path helpers.
• Dependency Conflicts: Low risk. Package has no dependencies beyond PHP.
• Laravel-Specific: Works alongside Illuminate\Support\Facades\Path but does not override it.

Sequencing

1. Pre-requisite: Ensure Composer’s autoload is up-to-date:

   composer dump-autoload --optimize
   

2. Installation: Add to composer.json:

   "require": {
       "konsulting/project-root": "^1.1"
   }
   

   Run:

   composer require konsulting/project-root
   

3. Usage:
   • Replace:

     $path = base_path('vendor/my-package/storage/logs');
     

   • With:

     $path = \Konsulting\ProjectRoot::forPackage('my-package')->resolve(__DIR__ . '/storage/logs');
     

4. Testing:
   • Add unit tests for path resolution in dependency and standalone modes.
   • Test in CI with:

     composer test
     

Operational Impact

Maintenance

• Proactive Tasks:
  • Monitor for Composer autoloader changes (e.g., PHP 8.3+ optimizations).
  • Update tests if new path resolution edge cases emerge (e.g., custom Composer repos or nested dependencies).
  • Fork the package if upstream maintenance stalls (low effort due to simplicity).
• Reactive Tasks:
  • Fallback logic: Implement a gracefully degrading fallback (e.g., __DIR__ with warning) if path resolution fails.
  • Deprecation: If Laravel adds native support (unlikely), document a migration path.

Support

• Common Issues:
  • "Package root not found": Debug with:

    composer show -v my-package
    

    Verify autoloader paths match expectations.
  • Windows path separators: Normalize paths early:

    $path = str_replace('\\', '/', $resolvedPath);
    

  • Symlinked vendors: Document workaround (e.g., use realpath() or disable symlinks in Composer).
• Documentation:
  • Add a troubleshooting guide covering:
    • Symlinked vendor directories.
    • Custom Composer install paths (--prefer-source).
    • Multi-level dependencies.
• SLAs:
  • L1 Support: "Use ProjectRoot for dependency-aware paths; escalate if resolution fails."
  • L2 Support: Investigate autoloader misconfigurations or package name mismatches.

Scaling

• Performance:
  • No overhead in typical use (path resolution is O(1) via Composer’s autoloader).
  • Caching: Optimize for repeated calls:

    static private $resolvedPaths = [];
    public function resolve($path) {
        $cacheKey = $this->packageName . '|' . $path;