Improve docs (#1204)

📝 improve docs + fix php-cs-fixer

.gitattributes

@@ -1,10 +1,8 @@
-/.gitattributes   export-ignore
-/.github          export-ignore
-/.gitignore       export-ignore
-/.php_cs          export-ignore
+/.git*            export-ignore
+/.php-cs-fixer*   export-ignore
 /CONTRIBUTING.md  export-ignore
 /Makefile         export-ignore
-/phpstan*         export-ignore
+/phpstan*.neon    export-ignore
 /README.md        export-ignore
 /UPGRADE.md       export-ignore
 /phpunit.xml.dist export-ignore

.php_cs → .php-cs-fixer.php

@@ -5,17 +5,15 @@
     ->in([__DIR__.'/src', __DIR__.'/tests'])
 ;
 
-return PhpCsFixer\Config::create()
+return (new PhpCsFixer\Config())
     ->setRiskyAllowed(true)
     ->setRules([
         '@Symfony' => true,
         '@Symfony:risky' => true,
         '@PHP71Migration:risky' => true,
         '@PHPUnit60Migration:risky' => true,
-        'array_syntax' => ['syntax' => 'short'],
-        'ordered_imports' => true,
         'declare_strict_types' => false,
-        'native_function_invocation' => true,
+        'native_function_invocation' => ['include' => ['@all']],
         'fopen_flags' => ['b_mode' => true],
         'php_unit_mock_short_will_return' => true,
     ])

CONTRIBUTING.md

@@ -32,12 +32,12 @@ Thank you!
 ## Running the test suite
 
 Tests suite uses Docker environments in order to be idempotent to OS's. More than this 
-PHP version is written inside the Dockerfile; this assure to tests the bundle with
-the same resources. No need to have php or Mongo installed. 
+PHP version is written inside the Dockerfile; this assures to test the bundle with
+the same resources. No need to have PHP or Mongo installed. 
 
 You only need Docker set it up.
 
-To allow testing environments more smooth we implemented **Makefile** 
+To allow testing environments more smooth we implemented **Makefile**.
 You have two commands available:
 
 ```bash
@@ -50,7 +50,7 @@ which will execute all tests inside the docker.
 make test TEST="Tests/Util/FilenameUtilsTest.php"
 ```
 
-will allow to tests single Test Classes.
+will allow testing single Test Classes.
 
 There are 3 environments available: PHP 7.3, 7.4 and 8.0.
 Default environment is *PHP 7.4* if you want to execute it against 

UPGRADE.md

@@ -1,5 +1,5 @@
-Upgrading from v1.17.1 to ...
-================================
+Upgrading from v1.17.0 to v1.18.0
+=================================
 
 - the "symfony/form" package is now a suggestion. Make sure to explicitly require this package if you use Symfony forms.
 

docs/events/howto/remove_files_asynchronously.md

@@ -23,15 +23,14 @@ namespace App\Message;
 
 class RemoveProductImageMessage
 {
-
-    private $filename;
+    private string $filename;
 
     public function __construct(string $filename)
     {
         $this->filename = $filename;
     }
 
-    public function getFilename()
+    public function getFilename(): string
     {
         return $this->filename;
     }
@@ -51,7 +50,7 @@ use Symfony\Component\Messenger\Handler\MessageHandlerInterface;
 
 class RemoveProductImageMessageHandler implements MessageHandlerInterface
 {
-    public function __invoke(RemoveProductImageMessage $message)
+    public function __invoke(RemoveProductImageMessage $message): void
     {
         $filename = $message->getFilename();
 
@@ -84,7 +83,7 @@ class RemoveFileEventSubscriber implements EventSubscriberInterface
         $this->messageBus = $messageBus;
     }
 
-    public static function getSubscribedEvents()
+    public static function getSubscribedEvents(): array
     {
         return [
             Events::PRE_REMOVE => ['onPreRemove'],

docs/form/vich_file_type.md

@@ -109,9 +109,7 @@ Can be callable
 use Vich\UploaderBundle\Form\Type\VichFileType;
 
 $builder->add('genericFile', VichFileType::class, [
-    'download_label' => static function (Product $product) {
-        return $product->getTitle();
-    },
+    'download_label' => static fn (Product $product): string => $product->getTitle(),
 ]);
 
 ```

docs/form/vich_image_type.md

@@ -72,7 +72,7 @@ $builder->add('genericFile', VichImageType::class, [
 
 ```
 
-Can be callable
+Can be a callable
 
 ```php
 use Vich\UploaderBundle\Form\Type\VichImageType;
@@ -107,9 +107,7 @@ Can be callable
 use Vich\UploaderBundle\Form\Type\VichImageType;
 
 $builder->add('genericFile', VichImageType::class, [
-    'download_label' => static function (Product $product) {
-        return $product->getTitle();
-    },
+    'download_label' => static fn (Product $product): string => $product->getTitle(),
 ]);
 
 ```

docs/generating_urls.md

@@ -28,13 +28,13 @@ If `image` is your only mapped field, you can omit it and use simply `$helper->a
 In a Twig template you can use the `vich_uploader_asset` function:
 
 ``` twig
-<img src="{{ vich_uploader_asset(product, 'image') }}" alt="{{ product.name }}" />
+<img src="{{ vich_uploader_asset(product, 'image') }}" alt="{{ product.name }}">
 ```
 
 Or, in the simpler case of a single mapped field:
 
 ``` twig
-<img src="{{ vich_uploader_asset(product) }}" alt="{{ product.name }}" />
+<img src="{{ vich_uploader_asset(product) }}" alt="{{ product.name }}">
 
 ```
 

docs/installation.md

@@ -10,7 +10,7 @@ your Symfony project:
 composer require vich/uploader-bundle
 ```
 
-Alternatively, you can add the requirement `"vich/uploader-bundle": "^1.12"` to your composer.json and run `composer update`.
+Alternatively, you can add the requirement `"vich/uploader-bundle": "^1.17"` to your composer.json and run `composer update`.
 This could be useful when the installation of VichUploaderBundle is not compatible with some currently installed dependencies.
 Anyway, the previous option is the preferred way, since composer can pick the best requirement constraint for you.
 
@@ -55,4 +55,4 @@ vich_uploader:
 ## That was it!
 
 Yeah, the bundle is installed! Move onto the [usage section](usage.md) to find out how
-to configure and setup your first upload.
+to configure and set up your first upload.

docs/known_issues.md

@@ -1,7 +1,7 @@
 Known issues
 ============
 
-## The file is not updated if there are not other changes in the entity
+## The file is not updated if there are no other changes in the entity
 
 As the bundle is listening to Doctrine `prePersist` and `preUpdate` events, which are not fired
 when there is no change on field mapped by Doctrine, the file upload is not handled if the image field
@@ -62,7 +62,7 @@ Vendor\Bundle\CoolBundle\Entity\CoolEntity:
 
 An upload will only be triggered if an instance of `Symfony\Component\HttpFoundation\File\UploadedFile`
 is injected into the setter for the `Vich\UploadableField` property of your class. Normally this is done
-automatically if using Symfony Form but if your application logic is attempting to do this manually and you
+automatically if using Symfony Form but if your application logic is attempting to do this manually, and you
 inject an instance of `Symfony\Component\HttpFoundation\File\File` *instead* the bundle will silently ignore
 your attempted upload.
 Consider the following class:
@@ -107,7 +107,7 @@ class Product
 
 If the bundle's configuration parameter `inject_on_load` is set to `true` the `Product::setImageFile()`
 method above must take an instance of `File` as when this class is hydrated by Doctrine this
-bundle will automatically inject an instance of `File` there. However if you were to change
+bundle will automatically inject an instance of `File` there. However, if you were to change
 the image path to a new image in that instance of `File` and attempted a `flush()` nothing
 would happen, instead inject a new instance of `UploadedFile` with the new path to your new
 image to sucessfully trigger the upload.

docs/storage/custom.md

@@ -1,7 +1,7 @@
 Custom Storage
 ==============
 
-The bundle supports some built-in storage but you can also create your own 
+The bundle supports some built-in storage, but you can also create your own 
 by implementing the `Vich\UploaderBundle\Storage\StorageInterface` or by
 extending the `Vich\UploaderBundle\Storage\AbstractStorage`.
 

docs/storage/gaufrette.md

@@ -3,7 +3,9 @@ Gaufrette
 
 > Gaufrette is a PHP library that provides a filesystem abstraction layer.
 
-**N.B.**: although Gaufrette is a well-known library, please note that it hasn't been updated in a while and that there are still lots of unresolved issues. One of them being a broken metadata implementation, [causing us troubles](../known_issues.md#failed-to-set-metadata-before-uploading-the-file).
+**N.B.**: although Gaufrette is a well-known library, please note that it hasn't been updated
+in a while and that there are still lots of unresolved issues. One of them being a broken metadata
+implementation, [causing us troubles](../known_issues.md#failed-to-set-metadata-before-uploading-the-file).
 
 
 ## Configuration

docs/usage.md

@@ -51,7 +51,7 @@ want to make uploadable.
 
 We already created an abstract representation of the filesystem (the mapping),
 so we just have to tell the bundle which entity should use which mapping. In
-this guide we'll use annotations to achieve this but you can also use
+this guide we'll use annotations to achieve this, but you can also use
 [YAML](mapping/yaml.md) or [XML](mapping/xml.md).
 
 First, annotate your class with the `Uploadable` annotation. This is really like