Env Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ffi/env
   

   Ensure your project meets the PHP ≥ 7.4 requirement.

2. First Check:

   use FFI\Env\Runtime;
   
   $status = Runtime::getStatus();
   

   Verify FFI availability in your environment (CLI, web, or embedded).

3. Basic Assertion:

   Runtime::assertAvailable(); // Throws if unavailable
   

   Use this early in your application lifecycle (e.g., in a service provider or bootstrap file).

First Use Case

Dynamic FFI Feature Toggle:

// In a service provider or config loader
if (Runtime::isAvailable()) {
    $this->app->singleton(FFIService::class, fn() => new FFIService());
} else {
    $this->app->singleton(FFIService::class, fn() => new FallbackService());
}

Leverage the package to conditionally enable FFI-dependent features while gracefully falling back.

Implementation Patterns

Workflows

1. Bootstrap Validation:

   // In `bootstrap/app.php` or a service provider
   Runtime::assertAvailable();
   // Proceed with FFI-heavy logic
   

2. Environment-Specific Logic:

   if (Runtime::isCliEnabled()) {
       // CLI-only FFI optimizations
   } elseif (Runtime::isWebEnabled()) {
       // Web-safe FFI usage
   }
   

3. Dependency Injection:

   // In Laravel's `AppServiceProvider`
   public function register()
   {
       $this->app->when(FFIService::class)
           ->needs('$ffiAvailable')
           ->give(fn() => Runtime::isAvailable());
   }
   

Integration Tips

• Laravel Service Providers: Use Runtime::assertAvailable() in boot() to fail fast if FFI is unavailable.
• Middleware:

  public function handle($request, Closure $next)
  {
      if (!Runtime::isAvailable()) {
          abort(503, 'FFI unavailable');
      }
      return $next($request);
  }
  

• Testing: Mock Runtime::isAvailable() in tests to simulate FFI-unavailable environments:

  $this->partialMock(Runtime::class, ['isAvailable'])
       ->method('isAvailable')
       ->willReturn(false);
  

Gotchas and Tips

Pitfalls

1. False Positives in Web Contexts:

   • Runtime::isAvailable() may return true in web requests even if FFI is disabled in php.ini.
   • Fix: Use Runtime::getStatus() === Status::ENABLED for strict checks.

2. Embedded SAPI Misclassification:

   • Older versions (<1.0.3) misclassified embed/micro/phpdbg as non-CLI.
   • Fix: Update to ≥1.0.3 or manually check:

     if (in_array(PHP_SAPI, ['embed', 'micro', 'phpdbg'])) {
         // Handle embedded SAPI
     }
     

3. PHP 8.4+ Deprecations:

   • Methods like extension_loaded() may trigger deprecation warnings.
   • Fix: Use Runtime::isAvailable() instead of direct FFI checks.

Debugging

• Status Ambiguity: Log the full status for clarity:

  dump([
      'status' => Runtime::getStatus(),
      'sapi' => PHP_SAPI,
      'ffi_loaded' => extension_loaded('ffi'),
  ]);
  

• Preload Issues: If using FFI preloads, verify:

  if (Runtime::isCliEnabled() && !extension_loaded('ffi')) {
      // Check preload configuration
  }
  

Extension Points

1. Custom Status Handling: Extend the Status enum for project-specific states:

   namespace App\FFI;
   
   use FFI\Env\Status;
   
   final class CustomStatus extends Status {
       public const PARTIALLY_AVAILABLE = 'partially_available';
   }
   

2. Environment-Specific Factories:

   // app/Providers/FFIServiceProvider.php
   public function register()
   {
       $this->app->bind(
           FFIInterface::class,
           fn() => Runtime::isCliEnabled()
               ? new CLIFFIService()
               : new WebFFIService()
       );
   }
   

3. Event Listeners: Trigger events when FFI status changes (e.g., in a custom event dispatcher):

   event(new FFIStatusChanged(Runtime::getStatus()));