Path Laravel Package

Getting Started

Minimal Setup

1. Installation Add to composer.json:

   "require": {
       "dontdrinkandroot/path": "^1.0"
   }
   

   Run composer update.

2. First Use Case Basic path creation and manipulation:

   use DontDrinkAndRoot\Path\Path;
   
   $path = Path::create('/var/www/html');
   echo $path->getAbsolutePath(); // Resolves to absolute path
   

3. Where to Look First

   • Core Class: DontDrinkAndRoot\Path\Path (immutable path handling).
   • README: Focus on Path::create(), getAbsolutePath(), and join() methods.
   • Tests: tests/ directory for edge cases (e.g., Windows paths, symlinks).

Implementation Patterns

Core Workflows

1. Path Creation & Resolution

   // Immutable path creation
   $path = Path::create('app/Config');
   $absolutePath = $path->getAbsolutePath(); // Resolves relative to current dir
   
   // Join paths safely
   $nestedPath = $path->join('services', 'cache.php');
   

2. File/Directory Operations

   // Check existence
   if ($path->exists()) {
       $path->delete(); // Delete directory (recursively)
   }
   
   // Create directories
   $path->mkdir(); // Creates parent dirs if needed
   

3. Path Normalization

   $normalized = Path::create('./app/../Config')->normalize();
   // Resolves to 'Config' (removes redundant segments)
   

4. Laravel Integration Use with Laravel’s filesystem:

   $path = Path::create(storage_path('logs'));
   Storage::put($path->getAbsolutePath(), 'log content');
   

Best Practices

• Immutability: Treat Path objects as read-only. Use ->with() for modifications:

  $newPath = $path->withBasename('newname.txt');
  

• Cross-Platform: Test Windows/Linux paths early (e.g., C:\Users\file.txt).
• Validation: Use isFile()/isDirectory() before operations.

Gotchas and Tips

Pitfalls

1. Windows Path Handling

   • Use forward slashes (/) or DIRECTORY_SEPARATOR for consistency:

     $path = Path::create('C:/Users/file.txt'); // Works, but avoid mixed slashes.
     

   • Fix: Normalize paths early:

     $path->normalize()->getAbsolutePath();
     

2. Symlink Resolution

   • getAbsolutePath() follows symlinks by default. Use getRealPath() to resolve symlinks:

     $realPath = $path->getRealPath(); // Resolves symlinks to target.
     

3. Permission Issues

   • mkdir()/delete() may fail silently. Check return values:

     if (!$path->mkdir()) {
         throw new \RuntimeException("Failed to create directory.");
     }
     

4. Edge Cases

   • Root Paths: Path::create('/') behaves differently than Path::create('').
   • Trailing Slashes: Path::create('dir/') vs. Path::create('dir') may affect isDirectory().

Debugging Tips

• Log Paths: Use getAbsolutePath() for debugging to avoid relative path confusion.
• Test Edge Cases:

  // Test with:
  Path::create('//absolute/path'); // Double slash
  Path::create('app/../Config');    // Parent dir
  Path::create('file:///dev/null'); // URL-like paths
  

Extension Points

1. Custom Path Resolvers Override getAbsolutePath() logic for custom environments:

   class CustomPath extends Path {
       public function getAbsolutePath() {
           return '/custom/base/' . parent::getAbsolutePath();
       }
   }
   

2. Event Hooks Extend with events (e.g., PathCreated, PathDeleted) using Laravel’s Events facade.

3. Integration with Laravel

   • Service Provider: Bind Path to Laravel’s container:

     $this->app->bind('path', function () {
         return new Path();
     });
     

   • Facade: Create a Path facade for cleaner syntax:

     use Illuminate\Support\Facades\Facade;
     
     class PathFacade extends Facade {
         protected static function getFacadeAccessor() { return 'path'; }
     }