Collections Laravel Package

Getting Started

v1.1.1 is a patch-level release (Additional converters, Various fixes) — additive, no documented breaking changes. If you are already on v1.1.x, upgrade with composer update and run your converter-related test suite; there is no migration path to follow because there is no prior assessment to reconcile against.

First steps for a Laravel developer:

1. Install and publish config — composer require the package, then php artisan vendor:publish --provider="...ConverterServiceProvider" (or the tagged config). The published config file is your map: it lists the registered converter keys, their driver classes, and any default options. Read this file before reading the source.
2. Check what v1.1.1 added — diff the package's config/converters.php (or the README's converter table) against the copy you published previously. The new converters are the main reason to take this release; the "various fixes" are unlisted, so treat them as unverified and let your own tests be the arbiter.
3. First use case: a single synchronous conversion. Resolve the converter through the container or facade, pass a source value/file plus target options, and assert on the returned result object rather than on raw strings. This is the smallest loop that proves config, autoloading, and any native/CLI dependency are all wired correctly.

If your app only ever needs the converter set you already use, v1.1.1 is optional — but pin the version you validate against, since the default converter resolution may shift as more are registered.

Implementation Patterns

Registry-driven selection. Treat converters as a registry, not as hardcoded classes. Resolve by key from config so that the converters added in v1.1.1 become available without touching call sites:

// config/converters.php
'converters' => [
    'pdf'  => App\Converters\PdfConverter::class,
    'docx' => App\Converters\DocxConverter::class,
],
'default' => 'pdf',

$result = Converter::driver(config('converters.default'))
    ->convert($source, ['quality' => 'high']);

Inject the manager, not the driver. Type-hint the package's manager/factory in constructors and resolve the driver inside the method. This keeps your services testable and lets you swap drivers per feature flag.

Push heavy conversions to the queue. Anything shelling out to a binary or doing filesystem I/O should be a job with an explicit $timeout and $tries. Pass file paths (or a temporary-disk key) into the job, never stream handles — serialization will fail.

Chain converters for multi-step pipelines. Model source → intermediate → target as discrete steps so a failure names the step. With more converters now available, chaining (e.g. extract → normalise → render) is more viable than writing bespoke glue.

Wrap in an application-level service. Expose a single ConversionService::handle(Upload $file, string $target): ConversionResult that your controllers, console commands, and Livewire components all call. When the package's converter set grows, only this class needs review.

Test with real fixtures and a fake driver. Keep a small tests/Fixtures/ set per converter. Add one test per converter key you actually enable; use the manager's swap/bind hook to stub a converter for the fast path and reserve real conversions for a slow, tagged test group.

Validate inputs before dispatch. Determine type by MIME sniffing and extension, then check the registry supports the pair. Failing at validation gives a clear 422; failing inside a converter gives an opaque exception.

Gotchas and Tips

• Don't blind-force-publish config. vendor:publish --force will overwrite the config you have customised. Diff it first to learn which converters v1.1.1 introduced, then merge by hand.
• Run php artisan config:clear after editing converter config. Cached config is the number one cause of "the new converter isn't there" — the registry is read from config, not scanned at runtime.
• "Various fixes" is not a changelog. With no itemised list, regression risk is unknown. Pin the exact version ("pkg": "1.1.1") and check converted output against fixtures before deploying; if a fix touched a converter you rely on, output may legitimately differ.
• New converters can change ambiguous resolution. Where a source could map to more than one converter (extension vs MIME, default vs explicit key), always pass the key explicitly. Never rely on ordering in the config array.
• Verify native/binary dependencies. Additional converters often mean additional exec() targets (ImageMagick, LibreOffice, Ghostscript). Check they exist in your container and in CI; a missing binary throws at conversion time, not install time.
• Watch memory and timeouts. max_execution_time and memory_limit in PHP-FPM are usually the real failure boundary, not the package. Log converter duration per step so you can see where a chain stalls.
• Custom converters: implement the full interface. If you wrote your own converter against an earlier version, re-read the interface after upgrading — patches can add methods with defaults or tighten type hints. Run php -l plus your converter tests immediately post-upgrade.
• Extension points worth knowing: the manager's driver-resolution hook (for per-tenant overrides), the config's options/defaults block (pass-through per converter), and the result object (extend or decorate it if you need provenance metadata such as converter name and duration for audit logs).
• Debugging tip: log get_class($converter) and the effective options array at resolution time. Nine out of ten "wrong output" reports are a mis-resolved driver or an options array silently merged with defaults.
• Clean up intermediates. Chained conversions leave temp files; use a dedicated storage/app/conversions disk with a scheduled prune so disk exhaustion doesn't become your next incident.