Improve the file uploading documentation

[javiereguiluz]

We have a lot of issues related to file uploading. Let's merge them all in this meta-issue so we can coordinate the changes better:

• Stop using entities + form to upload and persist the file upload. Use a DTO + form instead. Consider improving the file upload tutorial #6753
• Explain how to upload multiple files at once. Add cookbook entry about uploading and validating multiple files #5603
• Better explain the way we manage uploaded file extension and MIME type ... and the difference between what the client send and what we guess. Better documentation for UploadedFile #2542
• There's a bug with the breadcrumb of the file upload article. "How to Upload Files" is misplaced under the Routing component #7606
• Mention VichUploaderBundle and entity listeners. upload_file.rst with entity listeners and vich options #7818
• How to create fake files for tests. [Testing] add more details on how to play with fake files for file uploading #5346
• Use a data transformer. upload_file.rst: Recommend view transformer instead of manually "transforming" the property? #11158
• File upload guide recommends insecure behaviour File upload guide recommends insecure behaviour #12192
• [Form] Upload file edit example tip is not needed [Form] Upload file edit example tip is not needed #13697

[darius-v]

https://symfony.com/doc/current/controller/upload_file.html

Here when you do as documentation says, you get an error:

Class Symfony\Component\Form\AbstractType not found
The problem is - it is not told that symfony/form should be installed.

https://stackoverflow.com/questions/47853790/symfony-4-class-symfony-component-form-abstracttype-not-found/47853846#47853846

[OlivierToussaint]

The documentation don't work with php 7.1

public function getBrochure(): ?string
    {
        return $this->brochure;
    }

    public function setBrochure(string $brochure): self
    {
        $this->brochure = $brochure;

        return $this;
    }

in Form we have :

            ->add('brochure', FileType::class, array('label' => 'Brochure (PDF file)'))

getBrochure waiting for a string and I receive FileType

in the listener we have

// src/EventListener/BrochureUploadListener.php
namespace App\EventListener;

use Symfony\Component\HttpFoundation\File\UploadedFile;
use Doctrine\ORM\Event\LifecycleEventArgs;
use Doctrine\ORM\Event\PreUpdateEventArgs;
use App\Entity\Product;
use App\Service\FileUploader;

class BrochureUploadListener
{
    private $uploader;

    public function __construct(FileUploader $uploader)
    {
        $this->uploader = $uploader;
    }

    public function prePersist(LifecycleEventArgs $args)
    {
        $entity = $args->getEntity();

        $this->uploadFile($entity);
    }

    public function preUpdate(PreUpdateEventArgs $args)
    {
        $entity = $args->getEntity();

        $this->uploadFile($entity);
    }

    private function uploadFile($entity)
    {
        // upload only works for Product entities
        if (!$entity instanceof Product) {
            return;
        }

        $file = $entity->getBrochure();

        // only upload new files
        if ($file instanceof UploadedFile) {
            $fileName = $this->uploader->upload($file);
            $entity->setBrochure($fileName);
        }
    }
}

Same issue here getBrochure can't be instances UploadedFile because it's a string.