Upload Data Bundle Laravel Package

Getting Started

• Framework mismatch first: despite the task framing, this is a Symfony bundle, not a Laravel package. There is no service provider, no config/upload-data.php, and no facade. composer require manuelj555/upload-data-bundle inside a Laravel app will pull Symfony bundle scaffolding you cannot boot cleanly. If you are on Laravel, treat this as a reference implementation to copy patterns from, not a dependency.
• If you genuinely are on Symfony (4.x-era, given the 2019 last release): register the bundle in config/bundles.php (new Manuelj555\UploadDataBundle\UploadDataBundle()), then check the bundle's DependencyInjection/ directory and Resources/config/ for the actual service IDs and configuration keys. The README is the only documentation and it is thin.
• Where to look first, in order: README.md → composer.json (PHP/Symfony constraints) → DependencyInjection/Configuration.php (the real config surface) → Entity/ or Model/ (what gets persisted) → Service/ (the upload/parse logic you'd actually reuse).
• First use case to target: a single CSV upload that (1) lands the file on disk, (2) records a row in an uploads table (original name, mime, size, status, uploaded_by), and (3) hands the path to your own parser. That is the smallest slice that exercises the bundle and tells you whether its entity/service layer is worth keeping.
• Do not start with the bundle's form types or controllers. They are the most opinionated and least reusable parts, and they are the most likely to be tied to deprecated Symfony form APIs.

Implementation Patterns

• Absorb, don't extend. The most realistic day-to-day pattern is to reimplement the upload service in your own app: a StoreUploadedFile action that validates, moves to storage/app/data/, and persists an Upload model. Use the bundle as a spec for what metadata to capture, not as a runtime dependency.
• Two-phase upload is the pattern that matters. Separate ingest (receive file, checksum, store, create pending record) from processing (parse rows, map columns, import). The bundle was built around "carga de archivo de datos" — data file loading — and the value is in decoupling the arrival of bytes from the interpretation of them. Even a straight port should keep these as two jobs.
• Queue the parse step. Any CSV/Excel file with a "data bundle" heritage is going to be large. Dispatch an ImportUploadJob on ingest and update the upload record's status (pending → processing → imported/failed) so the UI can poll. This is a pattern the original bundle almost certainly did not include and you will need regardless.
• Mapping layer as your own concern. Column mapping (source header → destination field) is the part users will demand changes to weekly. Keep it in a config array or a column_map JSON column on your upload record, not in bundle-provided code.
• Integration tip — wrap it behind one interface. If you do consume the bundle's service, define interface DataFileIngestor { public function ingest(UploadedFile $f): UploadRecord; } and adapt the bundle service to it. That single seam lets you drop the bundle later without touching controllers.
• Laravel-flavoured equivalent if you are porting: UploadedFile::store() for placement, a Uploads model with $casts for metadata, Storage::disk('data') for the filesystem abstraction, a ShouldQueue job for parsing, and a UploadImported event for downstream fan-out. That is roughly what this bundle is trying to give you, but maintained.

Gotchas and Tips

• Maintenance risk is the headline gotcha. Last release 2019-05-20, 1 star, 0 dependents. Assume: no PHP 8.1+ compatibility, no Symfony 5/6 support, no security patches, no tests. Pin nothing to it. Treat any adoption as a fork-and-own decision.
• Security surface is file upload — the highest-risk endpoint you have. Regardless of what the bundle does, you must enforce: allowlist of extensions and MIME (verify with finfo, not the client header), max size, randomised stored filenames, storage outside the web root, and no execution bit on the upload directory. Do not rely on the bundle's validation config for this.
• CSV parsing pitfalls the bundle will not solve: BOM-prefixed headers, ; vs , delimiters, CRLF inside quoted fields, and Excel saving UTF-16. Detect encoding on read and normalise to UTF-8 before touching headers.
• Memory and time limits. file_get_contents + str_getcsv on a 50 MB file will blow memory_limit. Stream with fgetcsv and chunk inserts (e.g. 500 rows) — Symfony's StreamedResponse/league/csv or Laravel's LazyCollection both fit.
• Debugging a bundle you can't find docs for: bin/console debug:container | grep -i upload to discover the service IDs, and debug:config for the config tree. In a Laravel port there's no equivalent — read the source, don't guess.
• Extension points are classic Symfony: service overrides via services.yaml, form type extension via AbstractTypeExtension, and Doctrine event subscribers for post-persist hooks. If you fork, that's where your customisations belong — not by editing vendor files.
• Version constraints are the first thing to read in composer.json. A 2019 bundle will typically declare symfony/*: ^3.4|^4.0 and php: ^7.1, which composer will refuse on a modern stack. If that's the case, the decision is made for you.
• Reasonable alternatives to evaluate before writing code: league/csv (streaming CSV), PhpOffice/PhpSpreadsheet (XLSX), Laravel's built-in Storage + UploadedFile, or maatwebsite/excel if you're on Laravel and the files are spreadsheets. Any of these is better maintained than this bundle and covers 90% of the same ground.
• Verdict in one line: use it as a design reference for separating ingest from parse; do not take a runtime dependency on it, and do not introduce it into a Laravel application at all.