Var Dumper Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require ffi/var-dumper
   

   Ensure your project uses PHP 8.1+ and has the PHP FFI extension enabled (ffi in php.ini).

2. First Use Case: Dump an FFI type directly in your Laravel app:

   use FFI;
   
   $ffiType = FFI::new('struct { int id; string name; }');
   dump($ffiType); // Inspects and displays the FFI struct
   

3. Key Files:

   • vendor/ffi/var-dumper (autoloaded via Composer).
   • No additional configuration is needed—it integrates seamlessly with Symfony’s var_dumper.

Implementation Patterns

Workflows

1. Debugging FFI Interop: Replace var_dump() with dump() or dd() for FFI types (e.g., C structs, pointers, or arrays):

   $ffiStruct = FFI::new('struct { float[3] rgb; }');
   dd($ffiStruct); // Dumps with color-coded output (if supported)
   

2. Pointer Handling: Use VAR_DUMBER_FFI_UNSAFE=1 in .env or runtime to inspect unsafe pointers (e.g., raw memory):

   putenv('VAR_DUMPER_FFI_UNSAFE=1');
   $unsafePtr = FFI::cast('int*', 0x1234);
   dump($unsafePtr); // Full memory inspection
   

3. Laravel Integration:

   • Service Providers: Register a custom dumper for FFI types in AppServiceProvider:

     use Symfony\Component\VarDumper\Cloner\Data;
     use FFI;
     
     public function boot()
     {
         Data::addTreeCustomizer(FFI::type('struct { ... }'), function ($data) {
             return (string) $data;
         });
     }
     

   • Middleware: Log FFI dumps to Laravel’s log channel:

     dump($ffiData)->log(); // Uses Laravel’s logging system
     

4. Testing: Assert FFI type outputs in PHPUnit:

   $this->expectOutputString("struct { ... }");
   dump($ffiType);
   

Tips

• Performance: Avoid dumping large FFI buffers in production (use if (app()->environment('local'))).
• Custom Casters: Extend Symfony\Component\VarDumper\Caster\CasterInterface for domain-specific FFI types.

Gotchas and Tips

Pitfalls

1. Unsafe Memory:

   • Dumping uninitialized pointers (e.g., NULL or dangling) may crash PHP. Use VAR_DUMPER_FFI_UNSAFE=1 cautiously.
   • Fix: Validate pointers before dumping:

     if ($ffiPtr !== FFI::null()) {
         dump($ffiPtr);
     }
     

2. Circular References:

   • FFI structs with self-referential pointers (e.g., linked lists) may cause infinite recursion.
   • Fix: Limit depth with Data::setMaxItems():

     Data::setMaxItems(100); // Prevents stack overflow
     

3. Type Mismatches:

   • Casting mismatches (e.g., treating a char* as int*) may produce garbled output.
   • Fix: Use FFI::type() to enforce correct types:

     $correctPtr = FFI::cast('char*', $ffiData);
     

4. Environment Variables:

   • VAR_DUMPER_FFI_UNSAFE must be set before dumping. Use:

     putenv('VAR_DUMPER_FFI_UNSAFE=1'); // Runtime override
     

     or add to .env:

     VAR_DUMPER_FFI_UNSAFE=1
     

Debugging

• Enable Verbose Output:

  php -d var_dumper.dump_server=1 artisan tinker
  

  Then dump FFI types via HTTP (e.g., curl http://localhost:9912/dump -d '{"data": [...]}').

• Check for FFI Extension:

  if (!extension_loaded('ffi')) {
      throw new RuntimeException('FFI extension required.');
  }
  

Extension Points

1. Custom Formatters: Override default rendering for specific FFI types:

   Data::addTreeCustomizer(FFI::type('my_custom_struct'), function ($data) {
       return "Custom: {$data->field}";
   });
   

2. Integration with Laravel Debugbar: Add FFI support to laravel-debugbar:

   Debugbar::extend('ffi', function ($data) {
       return dump($data, 1024, true); // Truncate large dumps
   });
   

3. Performance Profiling: Use VAR_DUMPER_FORMAT=cli to disable HTML formatting in CLI:

   VAR_DUMPER_FORMAT=cli php artisan tinker