Storage Common Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The package’s updated SAS generation logic (now shared across storage-common, blob, and file-share packages) reinforces its modular design. This change reduces duplication and centralizes timestamp formatting, aligning better with Laravel’s principle of single responsibility per component. The shared helper can be injected into Laravel’s service container as a singleton, ensuring consistency across all Azure Storage interactions.
• Service-Oriented Design: The centralized SAS logic simplifies Laravel’s config/services.php by allowing a single configuration point for SAS token generation (e.g., config('services.azure.sas_expiry')). This reduces boilerplate in controllers/services that generate pre-signed URLs.
• Event-Driven Potential: The shared timestamp helper could trigger Laravel events (e.g., sas.token.generated) for audit logging or analytics, though this requires custom integration.

Integration Feasibility

• PHP 8.x Compatibility: No breaking changes to PHP version requirements. The shared helper uses PHP 8.0+ features (e.g., named arguments), so Laravel 9+ remains fully compatible. Risk: Minimal, but test with PHP 8.2+ if using newer Laravel features like enums.
• PSR Standards: The shared helper adheres to PSR-3 (logging) and PSR-15 (HTTP clients), ensuring compatibility with Laravel’s Log facade and HttpClient implementations.
• Authentication: The SAS generation improvement streamlines token creation for Laravel’s Storage facade or custom filesystem adapters (e.g., AzureBlobFilesystem). Example:

  use App\Services\AzureSasGenerator;
  
  $sasToken = app(AzureSasGenerator::class)->generate(
      container: 'my-container',
      blob: 'file.txt',
      expiry: now()->addHours(1)
  );
  

Technical Risk

• Dependency Isolation: The shared helper introduces a new dependency between packages, increasing risk if the storage-common layer changes. Risk: Potential for cascading updates if the shared helper’s API evolves.
• Future-Proofing: Centralizing timestamp logic may delay adoption of Azure’s newer SAS features (e.g., IP restrictions, custom permissions). Mitigation: Monitor Azure’s SDK roadmap and extend the helper via interfaces.
• Testing Overhead: The change requires validating SAS token generation across all storage types (Blob, File Share). Action: Add Laravel-specific tests for AzureSasGenerator in your test suite.

Key Questions

1. SAS Customization: Can Laravel’s config/services.php override the shared helper’s default expiry or permissions (e.g., read-only vs. read-write)?
2. Filesystem Integration: Does the package provide a Laravel Filesystem adapter for SAS-generated URLs (e.g., storage_disk('azure')->url($path))?
3. Legacy Code: Will existing SAS generation logic (e.g., hardcoded expiry times) break if not updated to use the shared helper?
4. Performance: Does the shared helper introduce measurable overhead for SAS token generation under high load (e.g., 1000+ tokens/sec)?
5. Error Handling: Are invalid SAS inputs (e.g., malformed expiry times) handled gracefully with Laravel-compatible exceptions (e.g., InvalidArgumentException)?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Configuration: Centralize SAS settings in .env:

    AZURE_SAS_EXPIRY_MINUTES=60
    AZURE_SAS_PERMISSIONS=rwdl  # Read, write, delete, list
    

    Bind to Laravel’s config:

    'azure' => [
        'sas' => [
            'expiry' => env('AZURE_SAS_EXPIRY_MINUTES', 60),
            'permissions' => env('AZURE_SAS_PERMISSIONS', 'rwdl'),
        ],
    ],
    

  • Service Providers: Register the shared SAS helper as a singleton:

    $this->app->singleton(AzureSasGenerator::class, fn() => new AzureSasGenerator(
        config('services.azure.connection_string'),
        config('services.azure.sas')
    ));
    

  • Filesystem: Extend Laravel’s FilesystemManager to support SAS URLs:

    // app/Providers/AzureFilesystemServiceProvider.php
    public function register()
    {
        Storage::extend('azure-sas', function () {
            return new AzureSasFilesystem(
                Storage::disk('azure'),
                app(AzureSasGenerator::class)
            );
        });
    }
    

• Testing: Mock the AzureSasGenerator in Laravel’s Mockery tests:

  $mockSas = Mockery::mock(AzureSasGenerator::class);
  $mockSas->shouldReceive('generate')->andReturn('shared-sas-token');
  $this->app->instance(AzureSasGenerator::class, $mockSas);
  

Migration Path

1. Phase 1: SAS Refactor
   • Replace all custom SAS generation logic with the shared helper.
   • Update config/services.php to use centralized SAS settings.
2. Phase 2: Filesystem Integration
   • Implement azure-sas disk driver for temporary shared URLs.
   • Example usage:

     $url = Storage::disk('azure-sas')->url('file.txt');
     

3. Phase 3: Deprecation
   • Deprecate old SAS generation methods via Laravel’s deprecated() helper.
   • Example:

     if (method_exists($this, 'legacyGenerateSas')) {
         deprecated('legacyGenerateSas()', '2024-12-01');
     }
     

Compatibility

• Laravel Versions: Tested with Laravel 10+ (PHP 8.2+). For Laravel 9, ensure no PHP 8.1+ features (e.g., union types) are used in the helper.
• Package Dependencies: No breaking changes to existing dependencies. Action: Update composer.json to require the new package versions:

  "require": {
      "vendor/azure-storage-common": "^2.1.1",
      "vendor/azure-storage-blob": "^2.1.0"
  }
  

• Caching: Leverage Laravel’s cache to store frequently generated SAS tokens (e.g., for public assets):

  $sasToken = Cache::remember("sas:{$container}:{$blob}", now()->addHours(1), fn() =>
      app(AzureSasGenerator::class)->generate($container, $blob)
  );
  

Sequencing

1. Prerequisites:
   • Audit all SAS generation code for custom logic that may conflict with the shared helper.
   • Update Laravel’s PHP version if using PHP 8.2+ features in the helper.
2. Core Integration:
   • Implement the AzureSasGenerator singleton and configure it via config/services.php.
   • Replace direct SAS calls with the helper (e.g., use app(AzureSasGenerator::class)->generate()).
3. Validation:
   • Test SAS token generation for all storage types (Blob, File Share).
   • Verify Laravel’s Storage facade works with the new azure-sas disk driver.
   • Run php artisan optimize:clear and check for deprecation warnings.

Operational Impact

Maintenance

• Proactive Updates: Monitor the storage-common package for changes to the shared helper. Action: Subscribe to its GitHub releases and test updates in a staging environment.
• Backward Compatibility: The change is backward-compatible, but existing SAS logic must be updated to use the helper. Mitigation: Use Laravel’s deprecated() helper to phase out old methods.
• Documentation: Update internal docs to reflect:
  • New SAS generation workflow (e.g., "Use app(AzureSasGenerator::class)").
  • Configuration options for AZURE_SAS_EXPIRY_MINUTES and AZURE_SAS_PERMISSIONS.

Support

• Debugging: Use Laravel’s tap() to inspect SAS tokens:

  $token = app(AzureSasGenerator::class)->generate(...)->tap(fn($token) => Log::debug('Generated SAS:', ['token' => substr($token, 0, 20)]));
  

• Community: No direct impact on support, but the shared helper may reduce fragmentation in issues. Action: Tag upstream issues with laravel for better tracking.
• Vendor Lock-in: The shared helper reduces lock-in by standardizing SAS logic, but Azure-specific features (e.g., IP restrictions) may still require custom code. Mitigation: Abstract the helper behind an interface for future swaps.

Scaling

• Performance:
  • The shared helper reduces duplication but may introduce minor overhead for timestamp formatting. Test: Benchmark SAS generation with phpbench in a Laravel context.
  • Caching: Cache SAS tokens in Laravel’s Redis driver to offload Azure API calls for static assets.
• **Horizontal Sc