Refactor the Uploading Document

[weaverryan]

The document in question: http://symfony.com/doc/current/cookbook/doctrine/file_uploads.html

There are a number of open issues about this document:

• File upload handling with doctrine #2278
• Cookbook entry for advanced file upload implementation #1559
• File Upload: Correctly instruct how to handle updates #600
• Fix the "doctrine file uploads" cookbook examples, see symfony/symfony-d... #2120

Here's a summary of issues:

a) I really dislike the use of paths inside the entity itself

b) Complication of the callbacks not triggering if only the file object property is changed (since it's not mapped). This may not be avoidable, but should be solved as simply as possible).

c) I agree that the VichUploaderBundle should be suggested to help with much of this

Suggestions: One big theme is building-up in complexity from little to more.

1. We should first show how to upload files. It's very easy and includes implementing the UploadedFile object which you can get off of the Request. This should live as a little "cookbook" in the HttpFoundation component

2. Have a cookbook article that talks about uploading in Symfony, but nothing about Doctrine. This would include using a Form, validation, and moving the uploaded file in the controller.

3. Update the Doctrine file uploads doc to build off of the new, short doc in (2). So, it would start with pointing you to (2), then continue by building an entity, persisting, etc.

Questions

• What is a good (but still somewhat simple - I don't want to introduce services with lots of big logic to do this) way to keep track of where different "types" of files are uploaded. For example, suppose a site allows you to upload avatars and product images - the first is stored in /uploads/avatars and the second in /uploads/products. Where each type is stored should be stored in configuration somewhere, then accessed in the controller and in the view. I want to show a nice, but still simple way you might handle this.

[mahmouds]

@weaverryan I totally agree that we need an article for the upload without doctrine 👍
btw i have updated my PR #2120 and it should have fixed all of the callbacks triggering issues.

[javiereguiluz]

Could someone please label this issue with the DX label? Thanks!

[weaverryan]

Done! This is a huge issue.

[gondo]

what about handling file upload in POST_SUBMIT event of the root (the one without a parent) form?

i really don't understand why everyone (s2 cookbook, VichUploaderBundle, all the blog posts/tutorials) is putting the logic into entity class. in my understanding, it doesn't belong there at all. it belongs to form processing, not to data storing.
or am i missing something?

edit 1:
i've spent more time on this and man its complex.
using form post hooks doesn't work as expected because of form validation (constraints).
i thought that my requirement is simple:

• i have entity with field image where i define my constraints Image and NotBlank
• i build a form where field image is type of file
• i want to handle the upload after form validation (to start with: in a controller) but i simply can't do this.

what symfony is forcing me to do:

• separate upload and data mapping. by having different properties of Entity class (image_path with constraint NotBlank and file with constraint Image), or by using unmapped file form field and define Image constraint inside form builder.
• handle upload inside Entity class (as mentioned above, i don't consider this correct), or handle this in controller what can be messy for a for with multiple files

why this has to be this complicated?

[weaverryan]

Hey @gondo!

First, the cookbook is just wrong, and I think a lot of blogs have probably followed that :). About VichUploaderBundle, it only has the configuration in the entity (other than the extra property, you have a point with this), which is no different than having the Doctrine or Validation metadata there. So, you're not missing anything - you are correct imo!

You bring up some great points about how complex this can be, but that's more of an issue for the core than the docs.

Cheers!

[javiereguiluz]

I think we can close this issue now that #5375 is merged.

[weaverryan]

@javiereguiluz what do you think about removing http://symfony.com/doc/current/cookbook/doctrine/file_uploads.html entirely now?

[javiereguiluz]

I agree ... but only when I implement the changes that you suggested here #5375 (comment) I plan to do that soon.

[weaverryan]

@javiereguiluz if that's on your list (which would be awesome), then I'll close this :). Thanks!