Redlink Api Php Client Laravel Package

Getting Started

This package wraps an external, Application-Key-authenticated delivery API behind a familiar Laravel surface (config + a notifiable/channel or facade call). 1.0.1 is a patch release: no breaking changes, but two things are worth knowing on day one — the Application-Key is now validated for format before a request is made, and attachments can finally be passed through as a supported parameter.

1. Install and publish the config:

   composer require <vendor>/<package>:^1.0
   php artisan vendor:publish --tag=<package>-config
   

2. Put the credential in .env (never in the config file), and mirror it in config/<package>.php:

   <PACKAGE>_APPLICATION_KEY=your-key-here
   

3. First use case: send a single notification with one attachment and confirm it round-trips in the provider's dashboard before wiring it into a domain event. That smoke test exercises the key, the transport, and the new attachment path in one shot.

Where to look first:

• config/<package>.php — key name, base URL/sandbox toggle, default sender, timeout.
• The package's channel/transport class — this is what you'll extend or decorate if you need custom payload shaping.
• README "Attachments" section — 1.0.1 changed what is accepted here, so read it rather than relying on pre-1.0.1 blog posts.

Implementation Patterns

Keep the key in config, not in code. Resolve it via config('<package>.application_key') so php artisan config:cache and per-environment .env files behave. If you rotate keys, rotate through the environment, not by editing PHP.

Attachments — prefer paths and streams over raw contents. The 1.0.1 fix exposes attachments as a first-class allowed param; the safe shape in day-to-day use is:

$message->attach($pathOnDisk, ['as' => 'invoice.pdf', 'mime' => 'application/pdf']);

When the file lives on a non-local disk, stream it (Storage::disk('s3')->readStream($path)) rather than get(), which loads the whole file into memory and is the usual cause of memory-limit failures on large exports.

Attach conditionally, not in loops. Build the attachment list from a small array or collection and pass it once. This keeps payloads predictable and makes it trivial to assert on them in tests.

Queue the send, not the file read. Implement ShouldQueue on the notification and read/attach inside the queued job so the file is resolved at send time. If you must attach before dispatch, ensure the attachment serializes cleanly (see Gotchas).

Testing. Fake the underlying HTTP client (Http::fake()) and assert on the outgoing multipart body: the Application-Key header, the recipient, and the presence of the attachment filename. Because 1.0.1 validates key format client-side, a malformed key in a test now fails loudly with a package exception instead of a 401 from the API — assert on the exception message so key misconfiguration is caught in CI.

Integration tip. If your app already sends mail via Laravel's Mail facade, keep transactional email there and use this package for the notifications it uniquely supports; mixing both for the same message type creates two sources of truth for templates and attachments.

Gotchas and Tips

• The key format check is new. 1.0.1 validates the Application-Key before dispatch. If your key was previously accepted (or silently failed with a provider 401), a trailing newline, surrounding quotes, or a copy-paste artifact from a secrets manager will now throw immediately. Trim in .env or read the value through trim() in a config accessor.
• Attachments and queued payloads. Attachment objects holding open resources or UploadedFile instances from a request do not survive serialization. Convert to a path or a persisted file before dispatching, or read them inside the job.
• Size and count limits are the provider's, not the package's. There's no client-side cap, so oversized payloads surface as opaque provider errors. Validate total attachment size in a form request or a Notification guard clause where the failure is legible to you.
• Config caching masks .env edits. After changing the key locally, run php artisan config:clear; a stale cached config is the most common "the key is definitely right" bug report.
• Extension point: if you need to alter payload shape (custom metadata, per-tenant sender), decorate the transport/channel rather than forking the package — the config-driven design means most needs are a subclass plus a container binding.
• Version pinning. 1.0.1 is additive and safe to adopt, but pin to ^1.0.1 since the attachment param and key validation are the behaviour you're now testing against.