Filefield Bundle Laravel Package

Getting Started

• Understand what this is first. symfonycontrib/filefield-bundle is a Symfony 2.x-era bundle that enhances the core file form type. Its value-add is exactly the thing Symfony's native FileType never did out of the box: render a link to the currently stored file, expose a delete checkbox, and reconcile "keep / replace / remove" on submit. If you are on Symfony 3.4+ you almost certainly want VichUploaderBundle instead — but on a legacy 2.x codebase this bundle solves a real, recurring annoyance.
• Install (legacy constraints apply). PHP 5.x / Symfony 2.x only. Add the requirement to composer.json (there is no maintained stable release line; expect a dev-master constraint) and run composer update.
• Register the bundle in app/AppKernel.php: new SymfonyContrib\FileFieldBundle\FileFieldBundle(),. Do this for the environments that build forms (all of them, realistically).
• Look here first: Resources/config/ for the service/form-type alias, and the Form/Type/ directory for the actual type class and its setDefaultOptions/configureOptions — that is your source of truth for option names (upload_dir, multiple, size/mime limits, delete option, etc.). The README is thin; the type class is the documentation.
• First use case: an entity with a photo column holding a stored path/string. Build the form with the bundle's file type instead of the core file type, point upload_dir at your web-accessible uploads directory, and the widget will render: current file link + [x] delete + file input. Handle the file in your controller/entity exactly as you would a normal upload.

Implementation Patterns

• Single-file "replace or remove" pattern. The core workflow. On PRE_SUBMIT/SUBMIT your handler must branch three ways: (1) new UploadedFile present → move it, delete the old one, persist the new path; (2) delete checkbox checked and no new file → delete the old file and null the column; (3) neither → leave everything untouched. Write this as a private handleFile() method on the controller or an entity listener so every form reuses one implementation.
• Persist files in a Doctrine listener, not the controller. prePersist/preUpdate (or @PrePersist) on the owning entity lets you call the same move/delete logic regardless of whether the entity was saved via a form, a fixture, or an import. Keep the stored value as a relative path and resolve the absolute path from a single upload_dir parameter — never store absolute paths in the DB.
• Multiple uploads use the bundle's multiple option (a file-collection widget). Persist them as a FileFieldCollection/array on the entity via a OneToMany join entity with its own path + original name, and hydrate the widget's data from that collection so the rendered "current files" list is correct on every edit.
• Custom storage / adapter. If the bundle exposes a storage or naming strategy service, wire your own via the bundle config or by overriding the service definition. Default naming tends to be based on the client filename — swap in a random/hash namer (uniqid/sha1 + extension) to avoid collisions and path traversal.
• Validation. Prefer the bundle's own size/mime options for UX, but keep a Symfony File constraint (maxSize, mimeTypes, extensions) on the entity/form as the authoritative gate — options on the widget are display-time conveniences and are easy to bypass.
• Twig rendering. The type is designed to be dropped in as-is; in your template just {{ form_row(form.photo) }} and let it render link + checkbox + input. If you need custom markup, access form.photo.vars.data for the current path and the delete field by its generated child name.
• Integration tip: if the bundle replaces the core file alias globally (check the service alias before assuming), every existing ->add('x', 'file') in the app now renders a link + checkbox — verify your other forms still behave before shipping.

Gotchas and Tips

• It is effectively abandoned. Zero stars/dependents means no maintained support, no security patches, and no Symfony 3+/4+/5 compatibility. Treat it as frozen code you own: fork it or vendor it, and do not expect upstream fixes. On any new project, VichUploaderBundle + Symfony\Component\HttpFoundation\File\UploadedFile is the sane replacement.
• The override trap. If the bundle aliases itself over the core file type, it silently changes existing forms. Check Resources/config/*.xml|yml for the form.type alias and whether it is file or a distinct name like filefield; the safest adoption is to use the distinct name explicitly.
• Data shape is inconsistent by design. $form->getData() may hand you a string path (existing file kept), an UploadedFile (new upload), or null (no data). Always type-check before calling ->move() or string functions, or you will fatal on the first edit-after-upload.
• Delete + upload on the same submit. Decide the precedence explicitly (almost always: new upload wins, ignore the checked delete box) and document it — otherwise users replace a file, tick delete by reflex, and lose the upload.
• Uploaded files are lost on validation failure (the standard Symfony re-render problem). The file input cannot be repopulated for security reasons — make required fields fail before the upload is considered, or accept that users re-select after fixing errors.
• Filesystem prerequisites. The upload_dir must exist and be writable by the web user; the bundle does not create it. Set upload_tmp_dir, post_max_size, upload_max_filesize, and max_file_uploads in php.ini — the bundle's size option runs after PHP has already rejected oversized bodies, so mismatched limits produce confusing silent failures.
• Unique names, always. Never trust the client filename for the stored path (collisions, ../, unicode, NUL bytes). Generate a server-side name and keep the original name only as display metadata.
• Serving files. Do not link directly into a public upload_dir for anything sensitive — route downloads through a controller with BinaryFileResponse and an authorization check. The rendered "current file" link is only as safe as the path you stored.
• Debugging the form. {{ dump(form.photo.vars) }} (Twig debug bundle) is the fastest way to see what data the widget actually received; most "it shows the wrong file / no link" bugs are a wrong mapped data value, not a bundle bug.
• Extension points. The type's buildView/configureOptions and the service definitions are minimal — if you need different markup, override the form theme block in the bundle's Resources/views/Form/ rather than editing vendor code.