Aliases Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require yiisoft/aliases
   

   Add to composer.json under autoload:

   "yiisoft/aliases": "src/"
   

2. Basic Usage: Define aliases in config/aliases.php:

   return [
       'app' => [
           'paths' => [
               'logs' => __DIR__ . '/../../storage/logs',
               'cache' => __DIR__ . '/../../storage/cache',
           ],
           'urls' => [
               'api' => 'https://api.example.com',
               'dashboard' => '/admin',
           ],
       ],
   ];
   

3. First Use Case: Access paths/URLs via the Aliases service:

   use Yiisoft\Aliases\Aliases;
   
   $aliases = new Aliases(require __DIR__ . '/config/aliases.php');
   echo $aliases->get('app.paths.logs'); // Outputs: /path/to/storage/logs
   echo $aliases->get('app.urls.api');  // Outputs: https://api.example.com
   

Implementation Patterns

Core Workflows

1. Dynamic Configuration: Load aliases dynamically (e.g., from environment variables or database):

   $aliases = new Aliases([
       'app.paths.uploads' => getenv('UPLOADS_DIR'),
       'app.urls.cdn' => getenv('CDN_URL'),
   ]);
   

2. Dependency Injection: Bind Aliases to Laravel’s container in AppServiceProvider:

   $this->app->singleton(Aliases::class, fn() => new Aliases(config('aliases')));
   

   Inject into controllers/services:

   public function __construct(private Aliases $aliases) {}
   

3. Path/URL Resolution:

   • Paths: Use for filesystem operations (e.g., Storage::put($aliases->get('app.paths.logs').'/file.log', $content)).
   • URLs: Use for HTTP clients (e.g., Http::get($aliases->get('app.urls.api').'/endpoint')).

4. Namespacing: Group aliases hierarchically (e.g., app.paths, app.urls, thirdparty.aws):

   $aliases->get('thirdparty.aws.s3.bucket'); // Returns: 'my-bucket-name'
   

Integration Tips

• Laravel Filesystem: Extend Filesystem to resolve aliases:

  $path = $this->aliases->get('app.paths.cache');
  Storage::disk('local')->put($path.'/file', $content);
  

• Routing: Use URL aliases in route definitions:

  Route::get($aliases->get('app.urls.dashboard'), [DashboardController::class, 'index']);
  

• Environment-Specific Overrides: Merge environment-specific aliases in bootstrap/app.php:

  $aliases = new Aliases(array_merge(
      require __DIR__.'/../config/aliases.php',
      config('aliases.'.config('app.env'))
  ));
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity: Aliases are case-sensitive (e.g., 'App.Paths.Logs' ≠ 'app.paths.logs'). Use consistent dot notation.

2. Circular Dependencies: Avoid defining aliases that reference each other (e.g., alias1 → alias2 → alias1). The package does not detect cycles.

3. Filesystem Permissions: When resolving paths, ensure the target directories exist and are writable:

   if (!file_exists($path = $aliases->get('app.paths.logs'))) {
       mkdir($path, 0755, true);
   }
   

4. URL Validation: URLs must be absolute (e.g., https://example.com). Relative URLs (e.g., /api) may cause issues in some HTTP clients.

Debugging

• Missing Aliases: Use has() to check existence before accessing:

  if ($aliases->has('app.paths.nonexistent')) {
      // Handle gracefully
  }
  

• Configuration Overrides: Clear cached config if aliases aren’t updating:

  php artisan config:clear
  

Extension Points

1. Custom Resolvers: Extend Aliases to support dynamic resolution (e.g., database-backed aliases):

   class DatabaseAliases extends Aliases {
       public function get(string $alias): string {
           if (str_starts_with($alias, 'db.')) {
               return $this->resolveFromDatabase($alias);
           }
           return parent::get($alias);
       }
   }
   

2. Validation: Add validation rules for paths/URLs:

   $aliases->validate('app.paths.logs', fn(string $path) => is_dir($path));
   $aliases->validate('app.urls.api', fn(string $url) => filter_var($url, FILTER_VALIDATE_URL));
   

3. Environment-Specific Logic: Use Laravel’s config() helper to merge environment-specific aliases:

   $aliases = new Aliases(array_merge(
       config('aliases.base'),
       config('aliases.'.app()->environment())
   ));
   

Performance

• Caching: Cache resolved aliases in production to avoid repeated lookups:

  $cachedAliases = Cache::remember('aliases', now()->addHours(1), fn() => new Aliases(config('aliases')));