Update the documentation to prepare for 2.0 tag

README.md

@@ -8,13 +8,16 @@
 
 Netgen Remote Media Bundle is an eZ Publish bundle providing field type which supports remote resource providers, primarily [Cloudinary](http://cloudinary.com/).
 
-This repository contains field type (and legacy data type) implementation and provides the interface for the legacy administration.
+This repository contains field type (and legacy data type) implementation and provides the interface for the legacy administration. It also contains integration for eZ XML and Richtext fields (as a custom tag).
 
 ## Features
 
 - field type support for remote resources (only Cloudinary supported at the moment)
-- support for images, videos, and documents upload
+- eZ XML field custom tag
+- eZ Richtext field custom tag
+- support for images, videos, audio files, documents and raw files upload
 - images cropping editor
+- support for both legacy and new stack administrations
 
 ## Licence and installation instructions
 
@@ -26,11 +29,17 @@ This repository contains field type (and legacy data type) implementation and pr
 
 For usage documentation see [USAGE.md](docs/USAGE.md)
 
+For transformations usage see [TRANSFORMATIONS.md](docs/TRANSFORMATIONS.md)
+
+## Changelog
+
+For changes in specific versions see [CHANGELOG.md](docs/CHANGELOG.md)
+
 ## Contributing
 
 For frontend development see [FRONTEND.md][docs/frontend.md]
 
 ## Copyright
 
-- Copyright (C) 2016 Keyteq. All rights reserved.
-- Copyright (C) 2016 Netgen. All rights reserved.
+- Copyright (C) 2021 Keyteq. All rights reserved.
+- Copyright (C) 2021 Netgen. All rights reserved.

docs/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Netgen Remote Media Bundle changelog
 
+## 2.0
+
+* now all resource types are fully supported
+* filtering and search options have been improved
+* re-implemented integration for eZ XML text field
+* added implementation for eZ Richtext field
+* added support for multi-level folder structure
+* re-implemented frontend in Vue.js
+* added support for waveform image for audio files
+* updated PHP CS fixer configuration for coding standards
+* added configuration for GitHub CI (coding standards and tests)
+* improved coverage with tests
+
 ## 1.1.11
 
 ### Fixed

docs/FRONTEND.md

@@ -89,7 +89,6 @@ $ node copyFilesDev.js
 
 This script fakes additional files (normally created with production build).
 
-
 ## Project structure
 
 ```bash

docs/INSTALL.md

@@ -1,54 +1,88 @@
-# Installation instructions for Netgen Remote Media Bundle
+# Installation instructions
 
 ## Requirements
 
 * eZ Platform
 
 **Suggested**
-* this package works best with NetgenAdminUI.
+
+* this package works best with [Netgen Admin UI](https://github.com/netgen/NetgenAdminUIBundle)
 
 ## Installation steps
 
-* Configure the bundle:
-    * in `config.yml` add basic configuration:
-    ```
-    netgen_remote_media:
-        provider: cloudinary
-        account_name: [your_cloud_name]
-        account_key: [your_key]
-        account_secret: [your_secret]
-    ```
-
-* Run the following from your website root folder:
-    `$ composer require netgen/remote-media-bundle:^2.0`
-    
-* Activate legacy extension
-    
-* Activate the bundle:
-    ```
-    public function registerBundles()
-    {
-        ...
+### Configure the bundle
+
+In `config.yml` add basic configuration:
+
+```yaml
+netgen_remote_media:
+    provider: cloudinary
+    account_name: [your_cloud_name]
+    account_key: [your_key]
+    account_secret: [your_secret]
+```
+
+### Install the bundle via Composer
+
+Run the following from your website root folder:
+
+```
+composer require netgen/remote-media-bundle:^2.0
+```
 
-        $bundles[] = new Netgen\Bundle\RemoteMediaBundle\NetgenRemoteMediaBundle();
+### Activate legacy extension
+
+Add the following in your central `site.ini.append.php` file (usually `ezpublish_legacy/settings/override/site.ini.append.php`):
+
+```
+[ExtensionSettings]
+ActiveExtensions[]=ngremotemedia
+```
 
-        return $bundles;
-    }
-    ```
+### Activate the bundle
+
+Add the following in your `app/AppKernel.php` file:
+
+```php
+public function registerBundles()
+{
+    ...
+
+    $bundles[] = new Netgen\Bundle\RemoteMediaBundle\NetgenRemoteMediaBundle();
+
+    return $bundles;
+}
+```
 
-* Add the following entry to your main `routing.yaml` file:
+### Add routing configuration
+
+Add the following entry to your main `routing.yaml` file:
 
-    ```
-    netgen_remote_media:
-        resource: "@NetgenRemoteMediaBundle/Resources/config/routing.yml"
-    ```
+```yaml
+netgen_remote_media:
+    resource: "@NetgenRemoteMediaBundle/Resources/config/routing.yml"
+```
     
-* Update the database with a custom table:
-	* `$ mysql -u<user> -p<password> -h<host> <db_name> < vendor/netgen/remote-media-bundle/bundle/Resources/sql/schema.sql`
-    * **OR** run `php app/console doctrine:schema:update --force` (or run with `--dump-sql` to get the sql needed for creating the table)
-
-* Clear the caches
-    * run the following command:
-    ```
-    $ php bin/console cache:clear
-    ```
+### Update the database
+
+This bundle has a custom table in the database which needs to be created:
+    
+```
+mysql -u<user> -p<password> -h<host> <db_name> < vendor/netgen/remote-media-bundle/bundle/Resources/sql/schema.sql`
+```
+
+Or you can also do it via Doctrine:
+
+```
+php app/console doctrine:schema:update --force
+```
+
+(or run with `--dump-sql` to get the sql needed for creating the table).
+
+### Clear caches
+
+Run the following command:
+
+```
+php bin/console cache:clear
+```

docs/UPGRADE.md

@@ -0,0 +1,38 @@
+Netgen Remote Media Bundle upgrade instructions
+===============================================
+
+Upgrade from 1.0 to 2.0
+-----------------------
+
+Version 2.0 is a major release which brings many improvements and new features, as well as code cleanup but it contains some breaking changes as well as removed supports.
+
+### Changed requiremets
+* This bundle now supports only Symfony v3, the support for Symfony v2.8 (or lower) has been dropped
+* This bundle now supports only PHP 7.2 - 7.4 versions
+* This bundle now supports only eZ Platform v2 (from 2.4, or kernel 7.4)
+
+### Data structure changes
+
+The data structure for eZ field value as well as for eZ XML field custom tag, which is being stored in the database, has been changed. There's a migration command which will iterate through all fields (both NGRM and eZ XML fields) in the database and fix their data to support the new version.
+
+**WARNING:** the command works directly with the database, bypassing eZ's API. This means that it will fix all the data (including previous versions, drafts etc.) but it also means that **database backup is mandatory** prior to executing the command.
+
+#### Command
+
+```console
+php bin/console netgen:ngremotemedia:refresh:ez_fields  
+```
+
+#### Options
+
+* `--dry-run` - this will only display the actions that will be performed
+* `--force` - this will use the first found resource and empty fields with non-existing resources
+* `--content-ids` - list of content IDs to process (default: all)
+* `--chunk-size` - the size of the chunk of attributes to fetch (and size of chunk of resource to get from remote media in one API request)
+* `--rate-limit-treshold` - Percentage of remaining API rate limit below which the command will exit to prevent crashing the media on frontend (default 50 (%)).
+
+#### 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. 
+
+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.