Io Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require php-standard-library/io
   

   Add to composer.json under require-dev if using only for testing:

   "require-dev": {
       "php-standard-library/io": "^1.0"
   }
   

2. First Use Case: File Reading

   use PhpStandardLibrary\IO\FileHandle;
   use PhpStandardLibrary\IO\FileReader;
   
   $handle = new FileHandle('/path/to/file.txt');
   $reader = new FileReader($handle);
   
   $content = $reader->read();
   

3. Where to Look First

   • Documentation: Check the README.md for basic examples.
   • Source Code: Browse src/ for core classes (FileHandle, StreamHandle, Reader, Writer).
   • Tests: tests/ directory for usage patterns and edge cases.

Implementation Patterns

Core Workflows

1. Composable I/O Operations Chain readers/writers for complex pipelines:

   $handle = new FileHandle('input.txt');
   $reader = new FileReader($handle);
   $writer = new FileWriter(new MemoryHandle());
   
   $writer->write($reader->read());
   

2. Async-Ready Design Use AsyncFileReader for non-blocking operations:

   $asyncReader = new AsyncFileReader($handle);
   $content = yield $asyncReader->read(); // In a coroutine
   

3. Testing Abstractions Mock Handle interfaces for unit tests:

   $mockHandle = $this->createMock(HandleInterface::class);
   $mockHandle->method('read')->willReturn('test data');
   
   $reader = new FileReader($mockHandle);
   $this->assertEquals('test data', $reader->read());
   

Integration Tips

• Laravel Filesystem: Wrap Laravel’s Storage facade in a custom Handle:

  class LaravelFileHandle implements HandleInterface {
      public function __construct(private Filesystem $filesystem, private string $path) {}
  
      public function read(): string {
          return $this->filesystem->get($this->path);
      }
  }
  

• Event-Driven Apps: Use EventHandle for pub/sub I/O (e.g., Kafka, Redis Streams).
• CLI Tools: Combine with Symfony’s Console for interactive I/O:

  $handle = new ConsoleInputHandle();
  $reader = new FileReader($handle); // Reuse logic for CLI/stdin
  

Gotchas and Tips

Pitfalls

1. Resource Leaks Always close handles explicitly or use __destruct():

   $handle = new FileHandle('file.txt');
   try {
       $reader = new FileReader($handle);
       // ...
   } finally {
       $handle->close();
   }
   

   Tip: Implement HandleInterface::close() in custom handles.

2. Async Caveats

   • Coroutines require PHP 8.1+ (yield support).
   • Async handles may block if underlying streams are synchronous.

3. Line Endings FileReader preserves OS line endings (\n, \r\n). Use trim() or str_replace() for normalization.

Debugging

• Handle Errors: Wrap reads/writes in try-catch:

  try {
      $reader->read();
  } catch (IOException $e) {
      Log::error("I/O failed: {$e->getMessage()}");
  }
  

• Logging: Extend HandleInterface to log operations:

  class LoggingHandle implements HandleInterface {
      public function read(): string {
          Log::debug("Reading from handle");
          return $this->delegate->read();
      }
  }
  

Extension Points

1. Custom Protocols Implement HandleInterface for HTTP, databases, or queues:

   class HttpHandle implements HandleInterface {
       public function read(): string {
           return file_get_contents($this->url);
       }
   }
   

2. Compression Decorate handles for gzip/brotli:

   class GzipHandle implements HandleInterface {
       public function __construct(private HandleInterface $handle) {}
   
       public function read(): string {
           return gzdecode($this->handle->read());
       }
   }
   

3. Laravel Service Providers Bind interfaces to implementations:

   $this->app->bind(HandleInterface::class, function ($app) {
       return new FileHandle(config('app.storage_path').'/file.txt');
   });