Csv Bundle Laravel Package

Getting Started

Reality check first. Despite the composer name misatotremor/csv-bundle, the upstream repository is MisatoTremor/AvroCsvBundle — it is a Symfony bundle that handles Avro as well as CSV, and it is not a Laravel package. There is no service provider, no facade, no config/csv-bundle.php. It is built around Symfony's DI container and, at least for Avro, a schema/record model. That shapes everything below: you can use it in Laravel, but only as a standalone library you wire up yourself, or by borrowing its pattern rather than its code.

Minimal path if you still want to try it:

1. composer require misatotremor/csv-bundle — check the resolved version and that it doesn't drag in a full Symfony framework you don't want. v1.2.2 is the current tag.
2. Read src/ before the README. With a single star and zero dependents, the source is the documentation. Look for the importer/exporter service classes, the attribute (or annotation) used to mark fields as CSV columns / Avro fields, and any DependencyInjection/Configuration.php for the config tree.
3. If you are in a real Symfony app: enable the bundle in config/bundles.php, then look at config/packages/ for the expected config key.
4. If you are in Laravel: skip bundle registration entirely. Instantiate the importer/exporter classes manually in a small adapter service and feed them plain PHP objects.

First use case: export a handful of models to CSV for a client download, or — if the Avro side is what you actually need — write a stream of records to an .avro container file for a downstream consumer (Kafka/Data Lake style ingestion). Do a CSV export first: it is read-only, has no schema or transaction semantics, and will tell you quickly whether the column-mapping model fits your domain. Only then try Avro, because Avro adds a schema contract on top of the same mapping layer.

If your goal is genuinely "CSV import/export in Laravel," the honest recommendation is still league/csv (low level) or spatie/simple-excel / maatwebsite/excel (higher level). Reach for this bundle only if you are maintaining a Symfony codebase, need Avro files from PHP, or specifically want its declarative mapping idea.

Implementation Patterns

Borrow the pattern, not the dependency. The valuable idea here is declarative field mapping: attribute your model properties with the CSV header / Avro field they correspond to, and let one generic importer/exporter walk the metadata. You can reproduce the CSV half in ~80 lines of Laravel with PHP 8 attributes and reflection, and you keep full control over validation, casting and transactions. The Avro half is not worth reimplementing — use avro-php directly if that's the requirement.

Adapter service. If you do call into the bundle, isolate it behind one class so the rest of your app never sees Symfony types:

// app/Services/Csv/CsvBridge.php  (class names illustrative — confirm against src/)
final class CsvBridge
{
    public function export(iterable $records, string $path): void { /* bundle exporter */ }
    public function import(string $path, string $class): iterable { /* bundle importer */ }
    public function exportAvro(iterable $records, string $schemaPath, string $path): void { /* bundle avro writer */ }
}

Everything else — controllers, jobs, console commands — talks to CsvBridge. Note the constructor: since v1.2.2 the bundle's services receive their dependencies by constructor injection rather than reaching into the container, so if you instantiate anything by hand you must supply those arguments yourself (there is no setContainer() fallback any more).

Workflow for a CSV import:

• Upload to a temp/storage path; never parse the request body directly.
• Sniff encoding and delimiter, strip UTF-8 BOM, validate the header row against an expected column set before touching the database.
• Dispatch a queued job; stream row-by-row rather than file_get_contents.
• Wrap each chunk in DB::transaction(), with an idempotency key (e.g. external SKU) so re-runs update rather than duplicate.
• Collect per-row errors into a report file and return that to the user — silent partial imports are the worst outcome.

Workflow for a CSV export: build a query with an explicit select(), chunk it (lazy() / chunkById), and write to a streamed response or a file on disk with a TTL. Avoid hydrating full Eloquent models for a 200k-row export — use toBase()/query builder and map manually.

Workflow for Avro: treat the .avsc schema as a versioned artefact checked into the repo, not something generated at runtime. Validate every record against the reader/writer schema before writing, because Avro fails late and opaquely (you get a truncated or unreadable container, not a row number). Keep the writer schema alongside the produced file so downstream consumers can deserialize without a Schema Registry lookup.

Integration tips:

• Put import/export routes behind auth + rate limiting; these are expensive endpoints.
• For file storage, use Laravel's Storage facade and hand the bundle an absolute local path (most such libraries expect fopen-able local files, not S3 streams). Stream to a temp disk path and upload on completion.
• In tests, keep a small fixture per edge case: empty file, header only, quoted commas, embedded newlines, mixed line endings — plus one golden .avro fixture per schema version.

Gotchas and Tips

Maintenance risk is the headline gotcha — but it just moved. v1.2.2 (fix for the removal of ContainerAwareInterface) shows the package is still being touched, which is better than the previous picture. It is still one star, zero dependents, and single-maintainer. Pin the version in composer.json, and be prepared to fork. Do not put this on a critical path without a fallback.

Symfony version coupling. ContainerAwareInterface was deprecated in Symfony 4.4 and removed in Symfony 6.0; this release is the maintainer catching up. Practical consequences:

• v1.2.2 requires a modern Symfony DI component (6.x/7.x). On an old Symfony 4/5 app, check whether you actually need to stay on 1.2.1.
• Any code of yours that extended a bundle class and relied on $this->container or setContainer() will now break — dependencies must be injected. That is effectively a breaking change for subclasses even though the version bump is a patch.
• Anything the services pull from the container (event dispatcher, entity manager, filesystem) must now be satisfiable at construction time, which makes the Laravel wiring a little more explicit and a little less forgiving.

Framework mismatch. Symfony bundles assume a container, an event dispatcher and often Doctrine's EntityManager. In Laravel those services don't exist unless you pull in symfony/* pieces or run the bundle inside a Symfony kernel. Expect to construct dependencies by hand — and expect at least one class to type-hint an interface you now have to stub.

Entity coupling. The name says "entities," which usually means Doctrine. Eloquent models will not satisfy Doctrine\ORM type hints. Mapping Eloquent → plain DTOs → bundle is extra work that often erases the convenience you were chasing.

CSV itself is the trap, not the library.

• Excel exports: semicolon delimiters in European locales, \r\n endings, UTF-8 BOM.
• Leading zeros (01234) and long numbers become floats. Force string casting on read.
• Empty string vs null vs 0 — decide explicitly, and test all three.
• Dates: ambiguous 01/02/2024. Require ISO-8601 in the source contract.
• CSV injection: fields beginning with =, +, -, @ become formulas in Excel. Prefix with ' or strip on export for user-supplied data.

Avro-specific traps (new in scope with this package).

• Avro is binary; you cannot eyeball the output. Debug with avro-php's reader or avro-tools tojson, never with a text editor.
• Logical types: dates/timestamps are stored as int/long since epoch, decimals as bytes+precision/scale. A PHP DateTime handed over naively will either throw or silently encode wrong. Convert explicitly.
• Nullability must be declared as a union (["null","string"]) in the schema; you cannot send null to a non-union field.
• Field order and defaults matter for schema evolution. Adding a field without a default breaks backward compatibility for old readers.
• A single malformed record usually corrupts the whole container file — validate row by row before writing, and write to a temp file you rename only on success.

Memory. If the importer returns an array rather than a generator, a 50MB file will exhaust PHP memory. Check the return type before promising users "any size file." Set memory_limit guardrails and a max upload size.

Debugging. Start with var_dump of the parsed header and the first two rows from the bundle's own parse step — that separates "parsing is wrong" from "mapping is wrong" in one shot. Log the raw row alongside the mapped object when an exception fires. If construction itself fails after upgrading to 1.2.2, the error will be an unresolvable constructor argument, not a runtime exception — read the DI/instantiation trace first.

Extension points. Look for custom type converters, normalizers or event subscribers in src/ — those are usually where date/boolean/enum handling is customized, and they are the natural place to hang your own Avro logical-type converters. If none exist, don't fight it: pre-normalize values in your adapter before handing rows over.

Migration advice. The lowest-risk use is a one-off internal CSV export. If you find yourself writing adapters for Doctrine, container wiring and a bridge layer, stop — port the attribute-mapping idea to Laravel and use league/csv underneath. Keep the bundle only where the Avro writer is doing genuine work for you, since that is the part with no trivial Laravel equivalent.