Qsendgridbundle Laravel Package

Getting Started

Install the package via Composer (composer require vendor/package) and, if the package ships a config file, publish it with php artisan vendor:publish --tag=attachments-config (check the README for the exact tag). Laravel 5.5+ will auto-discover the service provider; older versions require manual registration in config/app.php.

Start by reading the package’s README and the published config file (typically config/attachments.php). The config usually defines the default storage disk, allowed MIME types, and default naming behaviour. The first practical use case is attaching a file to a Mailable and giving it a human‑friendly name:

// In a Mailable's build() method
$this->attach(storage_path('app/invoices/123.pdf'))
     ->as('Invoice-123.pdf'); // new in 1.1.1

If the package uses a fluent API, look for an as() method or a name option in the attach call. The 1.1.1 release adds the ability to define the attachment name explicitly, so verify the exact signature in the updated docs—most packages accept either attach($path, ['as' => 'name.pdf']) or a chainable ->as('name.pdf').

Implementation Patterns

• Mailables and Notifications – Use the package’s trait or facade inside build() or toMail(). The new naming feature is most useful when attaching generated documents (invoices, reports) so recipients see a meaningful filename instead of a random hash.
• Dynamic attachments – Generate a PDF, store it on a temporary disk (Storage::disk('local')->put(...)), attach it with a custom name, then delete the file after sending. For queued mail, ensure the disk persists until the job runs.
• Multiple attachments – Loop over a collection and attach each file with its own name. Keep a naming convention (e.g. {type}-{id}.pdf) to avoid collisions.
• Integration with queued mail – Prefer attachData() with a name if the package supports it, or store files on a persistent disk. The naming feature works the same in queued and synchronous mail.
• Reusable attachment logic – If the package exposes a facade or helper, wrap attachment calls in a dedicated service or trait so you can centralise naming rules and disk configuration.
• Testing – Use Mail::fake() and assert that the Mailable contains an attachment with the expected name. Check the package’s testing helpers or inspect the raw MIME if needed.

Gotchas and Tips

• Path vs. name – The first argument is usually the file path; the name is metadata. Don’t pass the desired name as the path. The 1.1.1 feature adds a separate way to set the display name.
• Naming collisions – Two attachments with the same name may confuse email clients. Ensure unique names, especially when looping over files.
• Special characters – Avoid slashes, colons, and non‑ASCII characters in attachment names unless the package explicitly sanitises them. Test with spaces and unicode if your users need them.
• Backward compatibility – 1.1.1 is a minor release; existing code that relied on auto‑generated names should continue to work. Run your mail tests after upgrading to confirm the default behaviour is unchanged.
• Config cache – After publishing or changing config, run php artisan config:clear to avoid stale settings, especially when switching storage disks.
• Debugging missing names – If the custom name doesn’t appear, confirm you’re on 1.1.1+ and using the correct method signature. Inspect the raw MIME (e.g. via Mailtrap or Laravel’s log driver) to see the Content-Disposition header.
• Extension points – Many attachment packages fire events (e.g. AttachmentCreating) or allow custom resolvers. Use these to apply naming rules globally without touching every Mailable.
• Disk persistence – For queued mail, avoid the local disk if it’s ephemeral in your environment. Use a disk that survives until the queue worker processes the job.