Weave Code
Aliases Laravel Package
yiisoft/aliases
yiisoft/aliases stores and resolves path aliases (strings starting with @) for filesystem paths or URLs. Define aliases like @root, @vendor, @bin and expand them on demand, supporting nested aliases (e.g., @bin => @vendor/bin) without checking path existence.
yiisoft/aliases is a lightweight PHP library for managing path aliases—short, readable identifiers (prefixed with @) that expand to long file paths or URLs. It supports composing aliases from other aliases (e.g., @bin → @vendor/bin) and resolves them when you call get().
Use it to centralize and standardize paths across your app without hard-coding directories. set() simply maps an alias to a value and doesn’t validate existence—resolution happens on demand.
- Define aliases via constructor array or
set() - Resolve aliases with
get()for files, directories, or URLs - Compose nested aliases (alias values may contain aliases)
- Distinguish aliases by the required
@prefix - Normalizes trailing
/and\in paths
Frequently asked questions about Aliases
- Can I use yiisoft/aliases to replace Laravel’s storage_path() or public_path() helpers?
- No, this package is for *custom* named paths (e.g., `@logs`, `@api`). Laravel’s built-in helpers like `storage_path()` are optimized for filesystem operations and can’t be replaced directly. Use aliases for non-standard paths or URLs (e.g., API endpoints) where Laravel lacks native support.
- How do I integrate yiisoft/aliases with Laravel’s service container?
- Bind the `Aliases` instance to Laravel’s container in a service provider’s `register()` method, e.g., `app->bind('aliases', fn() => new Aliases(config('aliases')))`. Then resolve aliases via `app('aliases')->get('@storage')` or inject the bound instance into classes.
- Will this package work with Laravel’s environment-specific configurations (e.g., .env overrides)?
- Yes. Define aliases in `config/aliases.php` and use Laravel’s `.env` to override them (e.g., `ALIAS_STORAGE=/custom/path`). Merge environment variables with the config array before passing it to `Aliases`. Example: `config(['aliases' => array_merge(config('aliases'), $_ENV)])`.
- Does yiisoft/aliases support dynamic path resolution (e.g., {env}://{path})?
- No, it resolves aliases to static paths only. For dynamic paths, pre-process the alias values (e.g., replace `{env}` with `env('APP_ENV')`) before setting them. Alternatively, use Laravel’s `Str::replace()` or a custom resolver to handle placeholders.
- How do I test aliases in Laravel’s PHPUnit tests? Can I mock them?
- Mock the `Aliases` instance in tests by binding a fake implementation in `setUp()`. For example: `$this->app->instance('aliases', Mockery::mock(Aliases::class)->shouldReceive('get')->andReturn('/mocked/path')->getMock())`. This lets you isolate path logic from filesystem dependencies.
- Are there performance concerns with frequent alias resolution in high-traffic Laravel apps?
- Resolution is lightweight (~microseconds per call), but cache frequently accessed aliases using Laravel’s `Cache::remember()`. Example: `Cache::remember('alias.storage', 60, fn() => $aliases->get('@storage'))`. Benchmark in your CI if latency is critical.
- Can I use yiisoft/aliases for URL routing (e.g., @api/v1/users) instead of Laravel’s route aliases?
- Yes, but it’s not a drop-in replacement for Laravel’s `Route::alias()`. Use aliases for non-route paths (e.g., API base URLs) and combine with Laravel’s route model binding or middleware. For route-specific aliases, consider extending Laravel’s `Route` facade instead.
- What happens if I try to get an undefined alias? Does it throw an exception?
- By default, `get()` throws a `RuntimeException` if the alias is undefined. To handle missing aliases gracefully, wrap calls in a try-catch block or extend the `Aliases` class to return `null` or a fallback path for undefined keys.
- How do I publish or share aliases between multiple Laravel projects?
- Store aliases in a shared config file (e.g., `config/aliases.php`) and include it via `config(['aliases' => require __DIR__.'/shared_aliases.php'])` in your `AppServiceProvider`. For environment-specific aliases, use Laravel’s `config()` helper to merge them dynamically.
- Are there alternatives to yiisoft/aliases for Laravel path management?
- For filesystem paths, Laravel’s `storage_path()`, `public_path()`, and `config('path.storage')` are sufficient. For custom paths/URLs, consider Laravel’s `config()` helper or packages like `spatie/laravel-config-array`. This package excels for *named* paths with nested aliases (e.g., `@bin/phpunit` resolving to `/vendor/bin/phpunit`).
Weaver
How can I help you explore Laravel packages today?