Csv Rfc Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require ajgl/csv-rfc
   

   Register the service provider in config/app.php under providers:

   Ajgl\CsvRfc\CsvRfcServiceProvider::class,
   

2. First Use Case Replace native fputcsv() with Ajgl\CsvRfc\fputcsv() in your controller or service:

   use Ajgl\CsvRfc\fputcsv;
   
   $file = fopen('output.csv', 'w');
   fputcsv($file, ['Name', 'Email', 'Notes']);
   fputcsv($file, ['John Doe', 'john@example.com', 'Escaped "quote" here']);
   fclose($file);
   

3. Where to Look First

   • Documentation: The README covers core functions (fgetcsv, fputcsv, str_getcsv, str_putcsv).
   • Tests: The test suite demonstrates edge cases (e.g., escaped quotes, line breaks).
   • Service Provider: Check CsvRfcServiceProvider for aliases and bindings.

Implementation Patterns

Core Workflows

1. Reading CSV Files Use Ajgl\CsvRfc\fgetcsv() or Ajgl\CsvRfc\str_getcsv() for RFC4180-compliant parsing:

   $file = fopen('input.csv', 'r');
   while (($row = fgetcsv($file)) !== false) {
       // Process $row (array of fields)
   }
   fclose($file);
   

2. Writing CSV Files Replace native functions with the package’s versions to handle escaped quotes:

   $csvData = [
       ['Name', 'Email'],
       ['Alice', 'alice@example.com'],
       ['Bob', 'bob@example.com', 'Line break\ninside']
   ];
   
   $file = fopen('output.csv', 'w');
   foreach ($csvData as $row) {
       fputcsv($file, $row);
   }
   fclose($file);
   

3. Streaming Large Files Use Ajgl\CsvRfc\CsvWriter for memory-efficient writes:

   $writer = new \Ajgl\CsvRfc\CsvWriter('output.csv');
   $writer->putRow(['Header1', 'Header2']);
   $writer->putRow(['Data1', 'Data2']);
   $writer->close();
   

4. Integration with Laravel

   • Requests: Parse CSV uploads in handle() methods:

     $csv = $request->file('csv')->getRealPath();
     $file = fopen($csv, 'r');
     while (($row = fgetcsv($file)) !== false) {
         // Validate/process $row
     }
     

   • Responses: Stream CSV downloads:

     return response()->stream(function () {
         $file = fopen('php://output', 'w');
         fputcsv($file, ['Header1', 'Header2']);
         // Write rows...
         fclose($file);
     }, 200, [
         'Content-Type' => 'text/csv',
         'Content-Disposition' => 'attachment; filename="export.csv"'
     ]);
     

5. Custom Delimiters/Enclosures Override defaults via the second parameter:

   fputcsv($file, ['Data'], ';', '"'); // Semicolon-delimited, double-quoted
   

Gotchas and Tips

Pitfalls

1. Backward Compatibility

   • The package does not auto-load native functions. Explicitly replace them (e.g., use Ajgl\CsvRfc\fputcsv).
   • Avoid mixing native and package functions in the same file (undefined behavior).

2. Escaping Quotes

   • Fields with " must be wrapped in " and escaped as "" (RFC4180). The package handles this automatically, but manual overrides may break compliance:

     // ❌ Avoid this (unless you know what you're doing)
     fputcsv($file, ['Bad "quote"'], '"', '"', '\\');
     

3. Line Endings

   • The package defaults to \n. For Windows compatibility, set the CsvRfcServiceProvider config:

     'line_ending' => "\r\n",
     

     in config/services.php (if using the provider).

4. Memory Limits

   • str_getcsv() loads the entire string into memory. For large data, prefer file-based methods (fgetcsv).

5. Deprecated PHP Functions

   • The package does not support csv_to_array() or array_to_csv(). Use fgetcsv/fputcsv instead.

Debugging Tips

1. Validate Output Use online tools (e.g., CSV Validator) to verify RFC4180 compliance.

2. Logging Edge Cases Log problematic rows before writing:

   if (strpos($field, '"') !== false) {
       Log::debug("Escaped field: " . var_export($field, true));
   }
   

3. Testing Test with these edge cases:

   // Test data
   $edgeCases = [
       ['Normal', 'Data'],
       ['"Quoted"', 'Field'],
       ['Escaped "quote"', 'Here'],
       ['Line\nBreak', 'Test'],
       ['Tab\tSeparated', 'Data'],
   ];
   

Extension Points

1. Custom Writers Extend Ajgl\CsvRfc\CsvWriter for batch processing:

   class BatchCsvWriter extends \Ajgl\CsvRfc\CsvWriter {
       public function __construct($path, $batchSize = 1000) {
           parent::__construct($path);
           $this->batchSize = $batchSize;
           $this->buffer = [];
       }
   
       public function putRow($row) {
           $this->buffer[] = $row;
           if (count($this->buffer) >= $this->batchSize) {
               $this->flush();
           }
       }
   
       protected function flush() {
           foreach ($this->buffer as $row) {
               fputcsv($this->handle, $row);
           }
           $this->buffer = [];
       }
   }
   

2. Override Defaults Globally Bind a custom CsvRfc instance in the service provider:

   $this->app->bind('csv-rfc', function () {
       return new \Ajgl\CsvRfc\CsvRfc(';', '"', '\\', "\r\n");
   });
   

3. Laravel Facades Create a facade for convenience:

   // app/Facades/Csv.php
   namespace App\Facades;
   use Illuminate\Support\Facades\Facade;
   class Csv extends Facade {
       protected static function getFacadeAccessor() { return 'csv-rfc'; }
   }
   

   Then use:

   use App\Facades\Csv;
   Csv::putcsv($file, $data);