Exporter Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev sebastian/exporter
   

   Add --dev if only needed for development/testing.

2. Basic Usage:

   use SebastianBergmann\Exporter\Exporter;
   
   $exporter = new Exporter();
   $output = $exporter->export($yourVariable);
   

3. First Use Case: Replace dd() or var_dump() in Laravel debug statements:

   // In a controller or service
   $user = User::with('roles')->find(1);
   $exporter = new Exporter();
   dd($exporter->export($user)); // Clean, structured output
   

Where to Look First

• README.md: Covers core usage (scalars, arrays, objects, exceptions).
• Exporter class: Methods like export(), shortenedExport(), and toArray().
• Release notes: Check for PHP version compatibility (e.g., PHP 8.3+ limitations).

Implementation Patterns

Core Workflows

1. Debugging Complex Data:

   // Eloquent relationships with circular references
   $exporter = new Exporter();
   $output = $exporter->export($user->with('posts', 'roles')->get());
   

2. API Response Inspection:

   $response = $this->getJson('/api/users');
   $exporter = new Exporter();
   $this->assertStringContainsString('"data":', $exporter->export($response->json()));
   

3. Test Assertions:

   $this->assertEquals(
       'Array &0 ( ... )',
       $exporter->export($this->getMockArray())
   );
   

4. Custom Debug Helper:

   // In `app/Helpers/DebugHelper.php`
   if (app()->environment('local')) {
       $exporter = new Exporter();
       $exporter->export(request()->all());
   }
   

Integration Tips

• Laravel Debugbar: Extend the Data panel to use Exporter for structured variable display.

  Debugbar::info($exporter->export($model));
  

• Tinker: Override Tinker\Console::handle() to auto-export variables:

  Tinker::extend('e', function ($value) {
      return (new Exporter())->export($value);
  });
  

• Artisan Commands: Use for CLI debugging:

  $exporter = new Exporter();
  $this->line($exporter->export($this->getLargeDataset()));
  

• Logging: Replace Log::debug() for complex objects:

  Log::debug('Complex data', [
      'data' => $exporter->shortenedExport($complexObject)
  ]);
  

Performance Optimizations

• Shortened Output:

  // For large arrays/objects
  $exporter->shortenedExport($largeArray, 100); // Limit to 100 chars
  

• Array Size Limits:

  $exporter->setArrayLimit(50); // Truncate arrays >50 items
  

• Caching Exports: Cache repeated exports (e.g., in tests):

  static $cache = [];
  $key = spl_object_hash($object);
  if (!isset($cache[$key])) {
      $cache[$key] = $exporter->export($object);
  }
  

Gotchas and Tips

Pitfalls

1. PHP Version Limits:

   • PHP 8.3+: Not supported in ^8.0. Use ^7.0 for newer PHP.
   • PHP 8.5+: Suppresses NAN/INF warnings automatically (no action needed).

2. Circular References:

   • Self-referential objects/arrays are handled gracefully but may produce verbose output.
   • Tip: Use shortenedExport() for cleaner output:

     $exporter->shortenedExport($selfReferentialObject);
     

3. Large Arrays:

   • Default behavior may truncate large arrays (since v6.1.0). Explicitly set limits:

     $exporter->setArrayLimit(null); // Disable truncation
     

4. Binary Strings:

   • Non-printable binary data defaults to hex output (e.g., 0x000102).
   • Tip: For mostly-printable strings, use:

     $exporter->exportString($binaryString, true); // Force readable output
     

5. Private Properties:

   • toArray() drops private properties redeclared in child classes (fixed in v7.0.3+).
   • Workaround: Use reflection manually if needed.

6. Lazy Objects:

   • Avoid initializing lazy-loaded properties (e.g., Doctrine proxies) during export.
   • Tip: Export early or use shortenedExport() to skip lazy properties.

7. SplObjectStorage:

   • Iterator position is preserved (since v8.1.0), but may affect output order.

Debugging Tips

1. Unexpected Output:

   • Check for hidden characters (e.g., \0) in strings:

     $exporter->exportString($string, false); // Force hex for debugging
     

2. Performance Issues:

   • Profile with Xdebug to identify slow exports (e.g., deep recursion).
   • Tip: Use shortenedExport() for quick checks.

3. CI/CD Warnings:

   • Suppress E_WARNING for NAN/INF by updating to ^8.0 or later.

4. Custom Types:

   • Extend Exporter to handle custom classes:

     class CustomExporter extends Exporter {
         protected function exportCustomObject($obj) {
             return "Custom: " . $obj->getId();
         }
     }
     

Configuration Quirks

1. String Length Limits:

   • Default max string length: 1000 chars (configurable via constructor).
   • Tip: Override in tests:

     $exporter = new Exporter(500); // Shorter strings
     

2. Array Export:

   • Default: No limit (since v6.1.2).
   • Legacy: Older versions truncated by default.

3. Resource Handling:

   • Resources (e.g., file handles) are exported as resource(#) of type(stream).
   • Tip: Close resources before exporting to avoid leaks.

Extension Points

1. Custom Exporters:

   • Extend Exporter to add support for domain-specific types:

     class LaravelExporter extends Exporter {
         protected function exportCarbon($carbon) {
             return $carbon->toIso8601String();
         }
     }
     

2. Formatters:

   • Override exportFloat(), exportString(), etc., for custom formatting.

3. Output Filters:

   • Use shortenedExport() or setArrayLimit() to control verbosity.

4. Integration with Laravel:

   • Bind Exporter to the container:

     $this->app->singleton(Exporter::class, function () {
         return new Exporter(app()->environment('local') ? 2000 : 500);
     });
     

   • Use in service providers or middleware for consistent debugging.