Edt Paths Laravel Package

Getting Started

demos-europe/edt-paths is a small utility package (2 stars, single maintainer, MIT) for working with paths — most likely normalizing, joining, and resolving path-like strings in the context of the DEMOS/EDT data-space tooling. Treat it as a focused helper library rather than a framework-grade dependency.

Install it like any Composer package:

composer require demos-europe/edt-paths

Where to look first, in order:

1. README.md — with a package this small, the README is often the only documentation. If it is thin, read the source directly; the whole package is likely a handful of classes.
2. composer.json — check the require block to confirm the PHP and Laravel version constraints, and the autoload block to learn the namespace (probably DemosEurope\EdtPaths\...).
3. src/ — identify the primary value object or helper class. Expect something like a Path class with join(), normalize(), isAbsolute(), basename(), dirname() style methods, and possibly a PathResolver or facade.
4. tests/ — the fastest way to learn intended usage. Tests double as executable documentation for a package with no docs.

A good first use case: take a user-supplied or config-supplied path fragment, normalize it, and join it onto a configured base path before handing it to Laravel's Storage facade. That is the smallest slice that proves the package earns its place:

use DemosEurope\EdtPaths\Path; // verify exact FQCN in src/

$full = Path::from(config('edt.base'))
    ->join($request->string('subpath'))
    ->normalize()
    ->toString();

Storage::disk('local')->get($full);

If after that experiment the package only does what Illuminate\Support\Str, League\Flysystem\PathNormalizer, or a three-line helper already do, consider whether the dependency is worth the maintenance risk (see Gotchas).

Implementation Patterns

Wrap it in a thin application-level adapter. Because this is a single-purpose, low-traffic package, avoid sprinkling its classes across your codebase. Create one small service — e.g. App\Support\PathFactory or App\DataSpace\PathResolver — that owns all calls into the package. If the package is abandoned or you need to swap it out, you change one file instead of a hundred.

final class PathResolver
{
    public function __construct(private readonly string $base) {}

    public function resolve(string $relative): string
    {
        return Path::from($this->base)->join($relative)->normalize()->toString();
    }
}

Bind it in a service provider with config-driven construction:

$this->app->singleton(PathResolver::class, fn () => new PathResolver(
    config('edt.base_path')
));

Configuration-driven base paths. If the package exposes a config file (php artisan vendor:publish --tag=edt-paths-config), publish it and move the values into your own config/edt.php, then never read the package config directly in application code. This keeps environment-specific values manageable via .env and lets you override the package config in tests.

Composition over inheritance. These utility packages rarely ship interfaces or contracts. If you need polymorphism (different path strategies per tenant, per storage disk, per data-space domain), wrap the package class behind your own interface rather than extending it — it is almost certainly final or has no extension points.

Testing pattern. Since there is no Laravel service provider guarantee, test it in isolation: instantiate the path class directly and assert string outputs. Do not rely on fakes or facades unless the README documents them. Add a table-driven test for edge cases (leading slashes, .., trailing separators, Windows separators, empty segments) — this doubles as your safety net if you later replace the package.

it('normalizes joined paths', function () {
    expect((string) Path::from('/base/')->join('../etc/passwd')->normalize())
        ->toBe('/etc/passwd'); // or whatever the package intends — assert the behaviour you actually need
});

Integration points inside Laravel. The natural seams are: filesystem disk configuration (config/filesystems.php), queued jobs that carry a path as a string payload (normalize on the way in and out), and HTTP request validation (normalize subpath before it reaches the resolver). Do the normalization once, at the boundary, and pass canonical strings internally — do not let raw and normalized forms coexist.

Version pinning in CI. Given the low star count and zero dependents, pin an exact version ("demos-europe/edt-paths": "1.0.*" or the specific tag) and commit composer.lock. Treat minor bumps as review-worthy, not automatic.

Gotchas and Tips

• This is an unproven dependency. Two stars and zero dependents means essentially no production mileage. Before adopting, read every line of src/ (it is short) and decide whether the value exceeds the risk of an unmaintained dependency. For plain path joining, a local helper is often the safer call.
• Assumed, not confirmed API. The class names in this assessment (Path::from, join, normalize) follow common conventions but must be verified against the actual src/ and tests/ directories. Grep for public function before writing application code.
• Autoload / namespace mismatch. Older small packages sometimes ship a composer.json autoload map that does not match the directory layout, or rely on PSR-0. Run composer dump-autoload -o after install and confirm the class resolves with class_exists().
• No facade or service provider guarantee. Do not assume EdtPaths::... works. If no provider is auto-discovered, instantiate classes manually or add your own binding. Check composer.json for a laravel.providers block before blaming your config cache.
• Config caching. If the package does ship a provider and config, remember php artisan config:cache in production will freeze values — run config:clear after any .env change during debugging.
• Path traversal is your responsibility. A path utility that normalizes .. is doing exactly what it is told. If user input reaches the resolver, validate and constrain it (Str::startsWith, an allow-list of subdirectories, realpath() checks) after normalization, not instead of it.
• Separator and OS assumptions. Test on the platform you deploy to. Libraries written on Linux sometimes hardcode / and misbehave for Windows-style input; conversely, DIRECTORY_SEPARATOR-based logic will surprise you if you store URIs.
• Empty and null segments. Most bugs in path libraries come from empty-string segments producing doubled slashes or dropping a trailing slash. Write explicit tests for these before trusting the package in a filename-producing job.
• Extension points are likely absent. If you need custom behaviour (e.g. resolving ~ or stream wrappers), wrap rather than patch. Avoid forking: you would own maintenance forever.
• Debugging tip. Because failures here surface as "file not found" much later, log the raw input and the normalized output at the resolver boundary in non-production environments. It turns a mystery into a one-line diff.
• Escape hatch. Keep the adapter thin enough that replacing edt-paths with league/flysystem's PathNormalizer, Symfony's Filesystem, or a 20-line internal helper is a one-file change. Document that intent in the adapter's docblock so the next developer knows the dependency is deliberately quarantined.