Transfer Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — establish that up front. It plugs into Symfony's bundle system (config/bundles.php, config/packages/*.yaml), not Laravel's service container or providers. A Laravel developer will realistically meet it in one of three situations:

• A Symfony service/monorepo owns data, entity, or file transfers and emits results your Laravel app consumes.
• You're porting transfer/import-export logic from Symfony into Laravel and need to understand the source implementation.
• A cross-system pipeline where both frameworks must agree on transfer payloads and storage conventions.

First steps for the 2.0.0 release:

1. Pin philipphermes/transfer-bundle:^2.0 and install on the Symfony side.
2. Read CHANGELOG.md and UPGRADE-2.0.md in the repo before touching anything. The 2.0.0 release notes are effectively empty (just a version bump plus a compare link), so the upgrade guide and the 1.4.0...2.0.0 diff are your only source of truth for breaking changes.
3. Register the bundle and copy its config skeleton into config/packages/.
4. Prove the smallest transfer end-to-end before wiring anything else.

First use case to validate: one source→destination transfer (CSV/DB/storage adapter) run as a Symfony command, with the output picked up by the Laravel app.

Implementation Patterns

• Inject the bundle's transfer/manager service behind your own interface rather than calling static helpers — that keeps it stubbable and swappable when the major version changes again.
• Use the bundle's pre/post-transfer event hooks for side effects; if bridging to Laravel, mirror them with Laravel events at the boundary rather than reaching back into Symfony's dispatcher.
• Drive adapters from config (YAML, with secrets in .env) so environment differences never leak into code.
• Process in chunks via the bundle's iterators/paginators; never load a full dataset into memory for a transfer.
• Treat the bundle as an external job runner: execute via Symfony Messenger or console commands, then have Laravel consume the artifacts (files, rows, queue messages).
• In tests, use in-memory/array adapters and assert on transfer outcomes, not internal calls.
• For a Laravel port, extract the framework-agnostic core rather than pulling the whole bundle in — the Symfony wiring won't be reusable.

Gotchas and Tips

• 2.0.0 is a major bump — assume breaking changes. With no release notes details, diff 1.4.0...2.0.0, look for renamed/removed services and classes, and run the full suite before upgrading. Budget real migration time.
• Major versions frequently raise php and symfony/* constraints in composer.json. Confirm the supported Symfony version matrix before committing to the upgrade.
• Service IDs often change across majors — after upgrading, verify with bin/console debug:container and confirm config with bin/console config:dump.
• Config schema keys can be silently renamed; rely on the bundle's config validation instead of eyeballing YAML.
• Do not try to boot a Symfony bundle inside Laravel — it will fail. Use the underlying library or reimplement the logic at the boundary.
• Debugging transfer failures: raise logging and inspect the transfer/audit log; the cause is almost always an adapter, credential, or config mismatch rather than logic.
• Custom adapters/exporters are typically registered as tagged services — read the service definitions in Resources/config before concluding a feature is missing.
• When bridging, prefer queueing (Symfony Messenger → Laravel's queue driver) over rewriting the orchestration layer.
• Keep the bundle version pinned and re-read the upgrade guide on every major — sparse release notes mean the changelog/diff is your only reliable signal.