Drop Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require donatj/drop
   

   Add to composer.json if needed (e.g., for dev-only dependencies):

   "require-dev": {
       "donatj/drop": "^1.1.1"
   }
   

2. First Use Case: Replace var_dump() or dd() in quick debugging scenarios:

   use function drop;
   
   $user = User::find(1);
   drop($user->toArray(), $user->roles); // Halts execution
   

3. Where to Look First:

   • drop(): For halting execution and inspecting variables (like dd()).
   • see(): For non-blocking inspection (like dump()).
   • CLI/Web Compatibility: Works seamlessly in both environments with formatted output.

Implementation Patterns

Core Workflows

1. Replacing dd()/var_dump():

   // Before:
   dd($request->all());
   
   // After:
   drop($request->all()); // Halts execution, cleaner output
   

2. Non-Blocking Debugging:

   see($this->model->fresh()->load('relations')); // Logs to output, continues execution
   

3. CLI-Specific Debugging:

   php artisan tinker
   >>> drop(app()->make('someService')->getData());
   

   • Useful for Artisan commands or scripts where dd() would break the flow.

4. Integration with Laravel Facades:

   drop(
       Auth::user(),
       Cache::get('key'),
       Route::current()->parameters()
   );
   

5. Conditional Debugging:

   if (app()->environment('local')) {
       see('Debug data:', $someVariable);
   }
   

Advanced Patterns

• Logging to Files: Redirect output to a file in CLI:

  php script.php 2> debug.log
  

  Then use see() to log critical data.

• Custom Formatting: Extend the package by overriding the output logic (see Gotchas for hooks).

• Testing: Mock drop()/see() in tests to avoid halting execution:

  $this->expectOutputString('Expected output');
  drop('test'); // Won't halt in tests if output is captured
  

Gotchas and Tips

Pitfalls

1. Execution Halt:

   • drop() always exits with status 1. Avoid in production or use see() instead.
   • Fix: Wrap in environment checks:

     if (!app()->runningInConsole() && !app()->environment('local')) {
         return;
     }
     drop($data);
     

2. Output Buffering:

   • In web requests, ensure no output is sent before calling drop()/see().
   • Fix: Clear buffers manually if needed:

     while (ob_get_level()) {
         ob_end_clean();
     }
     drop($data);
     

3. Complex Objects:

   • Deeply nested objects/collections may produce unwieldy output.
   • Tip: Use ->toArray() or ->jsonSerialize() first:

     drop($model->toArray()['specific_key']);
     

4. CLI vs. Web Formatting:

   • Output differs slightly between CLI and web (e.g., colors, line breaks).
   • Tip: Test in both environments early.

Debugging Tips

• Silent Failures: If drop()/see() doesn’t output, check for:

  • Output buffering issues (ob_start() calls).
  • Early exit() or die() in your code.
  • Debug: Add error_log('Drop called') before the call.

• Performance: Avoid drop() in loops or performance-critical paths. Use see() sparingly.

Extension Points

1. Custom Output Format: Override the output logic by extending the package (not officially supported but possible):

   // vendor/donatj/drop/src/functions.php
   function drop(...$args) {
       // Custom logic here
       exit(1);
   }
   

2. Integration with Monolog: Redirect see() output to a logger:

   see('Log message'); // Outputs to CLI *and* logs via Monolog
   

3. Configuration: No config file exists, but you can create a helper:

   if (config('app.debug')) {
       see('Debug data:', $variable);
   }
   

Pro Tips

• Alias for Convenience: Add to composer.json aliases:

  "autoload": {
      "files": ["app/helpers.php"]
  }
  

  Then in app/helpers.php:

  if (!function_exists('dd')) {
      function dd(...$args) {
          drop(...$args);
      }
  }
  

• Artisan Commands: Use see() to log command progress:

  public function handle() {
      see('Starting task...');
      // ...
  }
  

• IDE Support: Add @mixin in PHPDoc to hint at the functions:

  /**
   * @mixin \drop(...$args)
   * @mixin \see(...$args)
   */