Update upgrade instructions

README.md

@@ -25,6 +25,8 @@ This repository contains field type (and legacy data type) implementation and pr
 
 [Installation instructions](docs/INSTALL.md)
 
+[Upgrade instructions](docs/UPGRADE.md)
+
 ## Documentation
 
 For usage documentation see [USAGE.md](docs/USAGE.md)

docs/UPGRADE.md

@@ -33,6 +33,89 @@ php bin/console netgen:ngremotemedia:refresh:ez_fields
 
 #### Possible rate-limit issues
 
-As you may know, cloud providers (eg. Cloudinary) mostly have the limit of requests that can be executed towards their API in specific period (one hour for Cloudinary). Since the command iterates through all fields and asks the API for each of these resources, it might break the rate limit which will make remote media resources on the live site unavailable. 
+As you may know, cloud providers (eg. Cloudinary) mostly have the limit of requests that can be executed towards their API in specific period (one hour for Cloudinary). Since the command iterates through all fields and asks the API for each of these resources, it might break the rate limit which will make remote media resources on the live site unavailable.
 
 In order to prevent this, the command will perform API fetches in chunks: it will first generate the list of all resources that need to be fetched and then fetch them in one request. You can control the size of the chunk with `--chunk-size` parameter. You can also set the `--rate-limit-treshold` which will stop the execution if the command consumes more than a set percentage of the rate limit.
+
+### Code changes
+
+#### Netgen\Bundle\RemoteMediaBundle\RemoteMedia\RemoteMediaProvider
+
+Due to dropping support for PHP versions lower than 7.2, the signature for some methods has been changed to include parameter type and return type declaration:
+
+```diff
+-public function buildVariation(Value $value, $contentTypeIdentifier, $variationName, $secure = true)
++public function buildVariation(Value $value, string $contentTypeIdentifier, $variationName, ?bool $secure = true): Variation
+```
+
+```diff
+-public function getRemoteResource($resourceId, $resourceType = 'image')
++public function getRemoteResource(string $resourceId, string $resourceType = 'image'): Value
+```
+
+```diff
+-protected function prepareUploadOptions($fileName, $fileUri, $options = array())
++protected function prepareUploadOptions(UploadFile $uploadFile, $options = []): array
+```
+
+This, of course, also affects the Cloudinary implementation: `Netgen\Bundle\RemoteMediaBundle\RemoteMedia\Provider\Cloudinary`.
+
+#### Netgen\Bundle\RemoteMediaBundle\RemoteMedia\Provider\Cloudinary\Gateway
+
+Search function now receives `Netgen\Bundle\RemoteMediaBundle\RemoteMedia\Provider\Cloudinary\Search\Query` object and returns `Netgen\Bundle\RemoteMediaBundle\RemoteMedia\Provider\Cloudinary\Search\Result` object:
+
+```diff
+-abstract public function search($query, $options = array(), $limit = 10, $offset = 0)
++abstract public function search(Query $query): Result;
+```
+
+Since Cloudinary requires type, resource type and resource public ID to uniquely identify a resource (eg. both image and video can exist with the same public ID), resource type parameter has been added to many methods to be more precise at determining the resource that we want to work with. The type parameter has been skipped for now since we mostly use `upload` type. This will be implemented in the next major release.
+
+```diff
+-abstract public function addTag($id, $tag)
++abstract public function addTag($id, $type, $tag);
+```
+
+```diff
+-abstract public function removeTag($id, $tag)
++abstract public function removeTag($id, $type, $tag);
+```
+
+```diff
+-abstract public function update($id, $options)
++abstract public function update($id, $type, $options)
+```
+
+```diff
+-abstract public function getDownloadLink($id, $options)
++abstract public function getDownloadLink($id, $type, $options);
+```
+
+```diff
+-abstract public function delete($id)
++abstract public function delete($id, $type)
+```
+
+### New methods
+
+#### Netgen\Bundle\RemoteMediaBundle\RemoteMedia\RemoteMediaProvider
+
+```php
+public function usage(): array
+public function searchResourcesCount(Query $query): int
+public function listSubFolders(string $parentFolder): array
+public function createFolder(string $path): void
+public function listTags(): array
+public function removeAllTagsFromResource($id, $type)
+```
+
+#### Netgen\Bundle\RemoteMediaBundle\RemoteMedia\Provider\Cloudinary\Gateway
+
+```php
+public function usage()
+public function searchCount(Query $query)
+public function listSubFolders(string $parentFolder)
+public function createFolder(string $path)
+public function listTags()
+public function removeAllTags($id, $type)
+```