Exporter Laravel Package

Getting Started

Minimal Steps

1. Installation: Update to the latest version (now 8.1.0) in composer.json:

   composer require --dev sebastian/exporter:^8.1
   

   For production debugging (rare), omit --dev.

2. First Use Case: Replace var_dump() or dd() in a Laravel controller or Artisan command:

   use SebastianBergmann\Exporter\Exporter;
   
   $exporter = new Exporter();
   $data = User::with('posts')->find(1);
   echo $exporter->export($data); // Clean, recursive-safe output with improved `SplObjectStorage` handling
   

3. Where to Look First:

   • README.md: Updated examples for SplObjectStorage and binary string improvements.
   • Exporter class: Core methods now handle iterator positions better (see #57).
   • Release notes (8.1.0): Focus on SplObjectStorage and binary string readability.

Implementation Patterns

Core Workflows

1. Debugging Eloquent Models with SplObjectStorage

// Circular reference-safe dump (now preserves iterator position)
$exporter = new Exporter();
$user = User::with('roles')->find(1);
$user->customData = new SplObjectStorage(); // Now won't reset iterator
echo $exporter->export($user);

2. Binary Data Inspection

// Improved readability for mostly-printable binary strings
$binaryData = file_get_contents('/path/to/file');
echo $exporter->export($binaryData); // More human-readable output

3. API Response Inspection

$response = Http::get('https://api.example.com/data');
$data = $response->json();
echo $exporter->export($data, 100); // Limit string length (unchanged)

4. Custom Artisan Command

use SebastianBergmann\Exporter\Exporter;

class DebugCommand extends Command {
    protected $signature = 'debug:model {model}';
    public function handle() {
        $model = app($this->argument('model'))::first();
        $this->line((new Exporter())->export($model));
    }
}

5. Middleware for Debug Headers

public function handle($request, Closure $next) {
    if ($request->header('X-Debug')) {
        $response = $next($request);
        $response->headers->set('X-Debug-Data', (new Exporter())->export($request->all()));
        return $response;
    }
    return $next($request);
}

Integration Tips

• Laravel Debugbar: Extend Debugbar::extend() to add an "Exporter" tab (unchanged).
• Tinker: Override dd() in AppServiceProvider (unchanged).
• Logging: Use shortenedExport() for production logs (unchanged).
• SplObjectStorage in Collections: If using SplObjectStorage in custom collections, ensure iterator positions are preserved:

  $collection = new CustomCollection();
  $collection->storage = new SplObjectStorage(); // Iterator position now preserved
  

Gotchas and Tips

Pitfalls

1. SplObjectStorage Iterator Reset:

   • Fixed: No longer resets to the first element (see #57).
   • Action: Update any code relying on iterator behavior post-export.

2. Binary Strings:

   • Improved: Mostly-printable binary data now displays more readably (see #91).
   • Action: No changes needed—just enjoy better output.

3. Performance with Large Arrays:

   • Unchanged: Still use shortenedExport() or limit depth:

     $exporter->export($array, 10); // Max depth
     

4. Private Properties:

   • Unchanged: toArray() still drops private properties. Use reflection if needed.

5. PHP 8.5+ Warnings:

   • Unchanged: Update to ^8.1 to avoid warnings:

     composer require sebastian/exporter:^8.1
     

Debugging Tips

• Check Export Limits:

  $exporter = new Exporter(100, 5); // Max string length, depth
  

• Inspect SplObjectStorage:

  $storage = new SplObjectStorage();
  $storage->attach(new StdClass());
  echo $exporter->export($storage); // Iterator position preserved
  

• Log Compact Outputs: Use shortenedExport() in production logs (unchanged).

Extension Points

1. Custom Exporters: Extend Exporter to handle Laravel-specific types (e.g., Carbon, Collection):

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

2. Formatters: Override format() for custom output (e.g., JSON):

   $exporter = new Exporter();
   $data = $exporter->toArray($object);
   return response()->json($data);
   

3. Hooks for SplObjectStorage: Customize SplObjectStorage export behavior:

   $exporter->exportVariable($variable) {
       if ($variable instanceof SplObjectStorage) {
           return "SplObjectStorage (size: " . $variable->count() . ")";
       }
       return parent::exportVariable($variable);
   }
   

Laravel-Specific Quirks

• Eloquent Circular References: Use with() to avoid N+1 queries before exporting (unchanged).
• Carbon Precision: Export microseconds explicitly (unchanged).
• Debugbar Integration: Add to app/Providers/DebugbarServiceProvider (unchanged).
• SplObjectStorage in Eloquent: If using SplObjectStorage in accessors/mutators, iterator positions are now preserved:

  public function getCustomDataAttribute() {
      $storage = new SplObjectStorage();
      // ... populate storage ...
      return $storage; // Iterator position preserved on export
  }