Kit Pathjoin Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require riimu/kit-pathjoin:^1.2
   

   Ensure vendor/autoload.php is included in your project (Laravel handles this automatically via composer.json).

2. First Usage:

   use Riimu\Kit\PathJoin\Path;
   
   // Normalize a path (resolves `.`, `..`, and redundant separators)
   $normalized = Path::normalize('/app/../resources/./config');
   
   // Join paths (cross-platform, handles absolute/relative paths)
   $joined = Path::join('storage', 'logs', 'app.log');
   

3. First Laravel Use Case: Use in config/filesystems.php or service providers to ensure consistent path handling across environments:

   $path = Path::join(storage_path(), 'app', 'logs', 'debug.log');
   

Implementation Patterns

Core Workflows

1. Path Normalization:

   • Use Path::normalize() for cleaning up user-provided paths (e.g., form inputs, API responses).
   • Example: Sanitize upload paths before processing:

     $cleanPath = Path::normalize($request->input('file_path'));
     

2. Path Joining:

   • Prefer Path::join() for constructing paths dynamically (e.g., config paths, asset paths).
   • Laravel Integration:

     // In a service provider or helper
     function configPath(...$segments) {
         return Path::join(config_path(), ...$segments);
     }
     

3. Cross-Platform Consistency:

   • Normalize paths before passing to Laravel’s filesystem methods (e.g., Storage::put()):

     $filePath = Path::normalize($request->file('document')->store('uploads'));
     

4. Absolute vs. Relative Handling:

   • Ensure the first argument to Path::join() is absolute if needed (e.g., for root-level paths):

     $absolutePath = Path::join('/var', 'app', 'logs');
     

Laravel-Specific Patterns

1. Service Provider Bootstrapping:

   • Normalize paths in boot() methods to ensure consistency:

     public function boot() {
         $this->app->bind('path.normalizer', function() {
             return new class {
                 public function normalize(string $path) {
                     return Path::normalize($path);
                 }
             };
         });
     }
     

2. Middleware for Path Sanitization:

   • Sanitize paths in middleware before processing (e.g., API routes):

     public function handle($request, Closure $next) {
         $request->merge([
             'sanitized_path' => Path::normalize($request->path())
         ]);
         return $next($request);
     }
     

3. Artisan Commands:

   • Use for constructing file paths in commands:

     protected function getLogPath() {
         return Path::join(storage_path(), 'logs', 'command.log');
     }
     

4. View Composers:

   • Normalize asset paths in view composers:

     public function compose(View $view) {
         $view->with('cssPath', Path::join(public_path(), 'css', 'app.css'));
     }
     

Gotchas and Tips

Pitfalls

1. Drive Letter Handling on Windows:

   • Path::normalize('/foo/bar') may prepend the current drive (e.g., C:\foo\bar). Use the second parameter to control this:

     Path::normalize('/foo/bar', false); // Returns '\foo\bar'
     

2. Empty Paths:

   • Path::join('foo', '..') returns . (current directory), not an empty string. Mimic PHP’s dirname() behavior:

     $parentDir = Path::join('foo/bar', '..'); // Returns 'foo'
     

3. Trailing Slashes:

   • The library does not automatically add/remove trailing slashes. Normalize manually if needed:

     $normalized = rtrim(Path::normalize($path), DIRECTORY_SEPARATOR);
     

4. PHP 5.6+ Requirement:

   • Avoid using this package in older Laravel versions (<5.2) due to PHP version constraints.

Debugging Tips

1. Verify Path Behavior:

   • Test edge cases like Path::join('//', 'path') (should return /path on Unix, \path on Windows).

2. Compare with realpath():

   • Cross-check results with PHP’s realpath() (where applicable) to ensure correctness:

     $normalized = Path::normalize('/app/../../var');
     $realPath = realpath($normalized); // Verify filesystem existence
     

3. Logging Normalized Paths:

   • Log normalized paths in development to catch inconsistencies:

     \Log::debug('Normalized path:', ['path' => Path::normalize($inputPath)]);
     

Extension Points

1. Custom Normalization Rules:

   • Extend the library by creating a wrapper class:

     class CustomPath {
         public static function normalize(string $path) {
             $normalized = Path::normalize($path);
             // Add custom rules (e.g., replace spaces with underscores)
             return str_replace(' ', '_', $normalized);
         }
     }
     

2. Integration with Laravel Filesystem:

   • Override Laravel’s Filesystem::path() to use Path::join():

     // In a service provider
     $this->app->extend('path', function($path) {
         return Path::join(...func_get_args());
     });
     

3. Testing:

   • Mock Path in unit tests to isolate path logic:

     $this->partialMock(Path::class, ['normalize'])
          ->shouldReceive('normalize')
          ->with('/test/path')
          ->andReturn('/normalized/path');
     

4. Performance:

   • Cache normalized paths in Laravel’s cache if used frequently (e.g., config paths):

     $cacheKey = 'path.normalized:'.$inputPath;
     $normalized = Cache::remember($cacheKey, 3600, function() use ($inputPath) {
         return Path::normalize($inputPath);
     });