Camino Laravel Package

Getting Started

Start by installing the package via Composer:

composer require sebastianfeldmann/camino

The library follows PSR-12 and is fully namespaced under SebastianFeldmann\Path. Begin with the core Path class, which encapsulates a filesystem path and exposes fluent methods for safe manipulation.

First use case: Safely join path segments while ensuring correct separator handling across Windows, macOS, and Linux:

use SebastianFeldmann\Path\Path;

$path = Path::from('app')->join('storage')->join('logs');
echo (string)$path; // 'app/storage/logs' on *nix, 'app\storage\logs' on Windows

Check the README (if available) or inspect the Path class directly via IDE navigation — it’s small and focused.

Implementation Patterns

• Composable path building: Chain join(), append(), and prepend() to construct paths declaratively instead of using . concatenation or DIRECTORY_SEPARATOR.

  $base = Path::from('/var/www');
  $config = $base->append('config')->append('.env');
  

• Normalization: Use normalize() to resolve . and .. and collapse duplicate separators.

  $path = Path::from('/foo/bar/../baz/./qux')->normalize();
  echo (string)$path; // '/foo/baz/qux'
  

• Inspection methods: Use basename(), dirname(), getExtension(), isAbsolute(), isRelative() for clarity.

  $path = Path::from('/path/to/file.txt');
  echo $path->getExtension(); // 'txt'
  echo $path->basename();     // 'file.txt'
  

• Cross-platform safety: Avoid hardcoding / or \. Camino automatically uses OS-native separators on string cast, but internally treats paths abstractly — ideal for libraries or CLI tools.

Integrate with existing code by using Path::from(string|self $path) to wrap raw strings or existing Path instances, then chain operations.

Gotchas and Tips

• No trailing separator by default: Path::from('dir') does not include a trailing separator. Use trailingSeparator() if needed (check API — may require manual cast + trim() in older versions).
• No null/empty handling: Passing empty strings or null may throw InvalidArgumentException. Always validate inputs before constructing Path objects.
• Immutable design: Path instances are immutable. Each mutation (join, normalize, etc.) returns a new instance. Avoid reassigning variables in place.
• Platform caveats: While separators are normalized on output, .. behavior in relative paths remains platform-aware — e.g., /foo/../bar normalizes to /bar on Unix, but relative paths like ../dir stay as-is unless resolved from a known base. Always normalize() when path integrity matters.
• Extension detection quirks: getExtension() returns '' for hidden files (e.g., .env) — verify logic if handling dotfiles.
• Extensibility: The class is simple and dependency-free — consider subclassing or wrapping in a domain-specific class (e.g., AssetPath, ConfigPath) for domain clarity.

🔍 Pro tip: Write tests for critical paths using both Unix and Windows-style inputs (e.g., 'C:\\foo\\bar' and '/foo/bar') to verify cross-platform normalization behavior.