Flat Laravel Package

Getting Started

• Install: composer require splash/flat. If Flex doesn't auto-register, add Splash\Bundle\FlatBundle\FlatBundle (or the vendor's actual namespace under src/) to config/bundles.php.
• Prerequisite: this is an embedded connector — it only makes sense once your splash/connector core is installed and configured (API keys, server URL, object definitions). Get a bare Splash connection working before touching this bundle; otherwise you'll be debugging two layers at once.
• First place to look: DependencyInjection/ and Resources/config/services*.yaml in the package. That tells you the real service IDs and the parameters (file path, delimiter, enclosure, encoding) you can override in your app config. Then skim src/ for the reader/writer services themselves — the codebase is small enough to read in full, which you should do given how little documentation/community exists.
• First use case: pick one direction only — e.g. "read a CSV export of products into a Splash object payload." Wire the file path and format parameters via config/services.yaml, register the object, run Splash's commit/import from a console command or the Splash console, and confirm rows land. Only then wire the write path (orders out to a legacy ERP, for example).

Implementation Patterns

• Thin adapter over Splash objects. Keep your domain logic in your own classes; let this bundle do the file↔array translation. Your service reads the file, maps rows to field arrays, and hands them to Splash's object services — don't let file parsing leak into your entities.
• Two symmetric workflows: import (file → Splash objects) and export (Splash objects → file). Implement import as a batch job (Splash's action queue + commit) and export as a separate command so a bad file on one side never blocks the other.
• Mapping config, not code. Put column→field mappings in a config array or a dedicated mapping class rather than inline $row[3] accesses. Flat-file schemas drift; you want the mapping editable without touching logic.
• Symfony wiring. Inject the bundle's file reader/writer services into your commands and services. Use a dedicated splash.flat.* parameter block in your app config and pass paths in from there — never hardcode into the bundle.
• Scheduling. Drive both directions from console commands so the same code runs from cron, a queue worker, or bin/console during debugging. Wrap each run in a lock (e.g. Symfony Lock component) — flat files are a single shared resource and concurrent writers will corrupt each other.
• Testing. Use a temp directory fixture, write a known CSV, run the command via KernelTestCase, assert on the resulting Splash payload/array. Because the package is unmaintained-in-practice, your tests are your upgrade safety net.

Gotchas and Tips

• Maturity signal: 0 stars, 0 dependents. Treat every assumption about API stability as false. Pin an exact version in composer.json, commit your composer.lock, and plan for the possibility of forking or vendoring the handful of classes you actually use.
• Encoding is the #1 failure mode. UTF-8 vs ISO-8859-1/Windows-1252, and stray BOMs at the start of the header row, will silently break column mapping. Read the header, strip BOM, and validate encoding explicitly rather than trusting it.
• CSV dialect quirks: delimiter, enclosure, escape character, and inconsistent quoting ("a""b", embedded newlines inside quoted fields) all differ per source system. Don't rely on auto-detection; configure it per source and add a fixture test.
• Write atomically. Write to a temp file in the same directory and rename() on success. A crashed process mid-write otherwise leaves a truncated file that the next reader treats as valid.
• Memory. Stream rows (fgetcsv / generator-based readers) instead of file() + explode. Large exports will otherwise hit memory_limit intermittently and be impossible to reproduce locally.
• Schema drift. Never assume column order or that headers are present. Match on header names, and fail loudly with the offending header rather than silently mapping the wrong column.
• Debugging: log the raw row plus the mapped array on any mapping exception. Without this, a single bad cell in a 100k-row file is undiagnosable.
• Extension points: prefer overriding service definitions/parameters in your app's services.yaml (aliasing the bundle's service ID to your subclass) over editing vendor code. Check DependencyInjection/Configuration.php for what's actually configurable before subclassing.
• Don't let it own your file contract. Keep the file format definition, mapping, and validation in your application layer, using this bundle purely as the I/O engine — that's the one way you stay portable if the package is abandoned.