Excel Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package>; no publish step is typically required for a streaming response helper, but check for a config file with php artisan vendor:publish if the README mentions one.
• First place to look: the response class itself (it now extends Symfony's StreamedResponse) and any service provider binding. Understanding the callback signature — it receives the output stream and you write to it — is the whole API surface.
• First use case: stream a large CSV export from a controller instead of building an array in memory. Return the package response with a callback that fputcsv()s rows one at a time.
• Verify the wiring with a trivial route that writes a few lines and flushes; confirm in the browser/curl that bytes arrive incrementally rather than all at once.
• In 1.0.0 the class extends StreamedResponse, so Laravel's normal response preparation/sending path applies (no Content-Length, chunked delivery). That is the intended behavior — no code changes needed on your side.

Implementation Patterns

• Controller return value: build the response in the controller and return it directly; let the framework send it. Do not echo inside the callback and return something else.
• Chunked data sources: pair the callback with lazy(), chunkById(), or cursor() so rows are pulled as they are written. Keep the callback free of eager-loading surprises.
• CSV/export pattern: set Content-Type: text/csv and Content-Disposition: attachment in the response headers before returning, then write a header row followed by data rows inside the callback.
• Server-Sent Events: use Content-Type: text/event-stream, Cache-Control: no-cache, X-Accel-Buffering: no, and flush after every data: frame. Add a heartbeat/sleep loop for long-lived connections.
• Progress/real-time output: flush after each logical unit and disable compression for that route; useful for long-running report generation or import progress.
• Testing: a streamed response's body is produced by the callback; in feature tests you can capture it via output buffering around $response->sendContent(), or assert status/headers only and cover the callback logic in a unit test.
• Middleware order: authentication/authorization middleware runs before streaming, which is what you want; anything that must run after the stream (logging completion, cleanup) belongs in the callback's finally block.
• Composition: wrap the package response in your own response class or a response macro if you need consistent headers across many endpoints; the container binding is the natural extension point.
• Regression check for 1.0.0: because it now extends StreamedResponse, tests or clients that previously assumed a Content-Length header or a fully-buffered body may need updating.

Gotchas and Tips

• Output buffering kills streaming. Any stray whitespace after ?>, a dd()/dump(), or a debug package that echoes will corrupt the stream or delay flushing. Call ob_end_flush()/ob_flush()/flush() as appropriate and audit for BOMs and trailing newlines in included files.
• Session locking. Laravel holds the session lock for the request; a long stream blocks other requests from the same user. Call session()->save() (or use a stateless/session-less middleware group) before the long-running loop.
• Proxy and web-server buffering. Nginx proxy_buffering/gzip and some CDNs buffer chunks until the response completes. Send X-Accel-Buffering: no and disable gzip for streaming routes; otherwise "streaming" looks identical to a normal response.
• Headers are final once output starts. Set status, Content-Type, and disposition before the first byte is written; you cannot change them mid-stream.
• Memory and timeouts. Use cursors/chunks rather than get(); call set_time_limit(0) deliberately (and be aware CLI vs web limits differ). Watch for query logging and debug tooling holding references to every row.
• Debugging streams is awkward. Log to files or stderr, not to the response body. Telescope and similar tools can buffer or serialize the response; disable them for streaming routes when diagnosing.
• 1.0.0 specifics: the "unused code" removal is internal and should be inert, but clear config:cache, route caches, and OPcache after upgrading. The StreamedResponse change is the one behavioral delta — re-run any tests that assert on headers, response class type, or body buffering.
• Client behavior. Browsers may still wait for a threshold of bytes before rendering; test with curl -N to confirm true incremental delivery before blaming the package.
• Extension points: override the callback to add per-chunk transforms (compression, encryption), subclass the response for shared headers, or bind your own implementation in the container for test doubles.