Updated all the contrib modules to their latest versions.

[yaffs-website] / web / modules / contrib / file_mdm / README.md

diff --git a/web/modules/contrib/file_mdm/README.md b/web/modules/contrib/file_mdm/README.md
new file mode 100644 (file)
index 0000000..aa26f10
--- /dev/null
+++ b/web/modules/contrib/file_mdm/README.md
@@ -0,0 +1,115 @@
+# File metadata manager
+
+A Drupal 8 module providing a file metadata manager service and API. Allows to
+get, via an unified API, information stored in files like EXIF photo
+information, TrueType font information, etc.
+
+Metadata protocols are pluggable. Developers can implement a plugin and use the
+service framework to get the metadata required.
+
+The following plugins are provided by the module:
+
+Plugin        | Read | Write | Description                                                  |
+--------------|:----:|:-----:|--------------------------------------------------------------|
+exif          | X    | X     | Uses the [PHP Exif Library](https://github.com/lsolesen/pel) to read/write EXIF information to image files, bypassing the limitations of the standard PHP Exif extensions which only provides read capabilities. Enable the _file_mdm_exif_ submodule to enable this plugin.        |
+font          | X    |       | Uses the [PHP Font Lib](https://github.com/PhenX/php-font-lib) to read font information from TTF/OTF/WOFF font files. Enable the _file_mdm_exif_ submodule to enable this plugin.         |
+getimagesize  | X    |       | Caches calls to the PHP ```getimagesize()``` function.        |
+
+The module is inspired by discussions at [#2630242 Provide methods to retrieve EXIF image information via the Image object](https://www.drupal.org/node/2630242).
+
+
+## Features:
+
+1. Load from, and save to, file embedded metadata directly from the files.
+2. Metadata for a file is statically cached during a request's lifetime. This
+   avoids different modules all repeat I/O on the same file.
+3. Metadata can be cached in a Drupal cache bin to avoid repeating I/O on the
+   files in successive requests.
+4. Metadata standards (EXIF, TTF, etc.) are implemented as plugins. The service
+   loads the metadata plugin needed based on the calling code request.
+5. Manages copying to/from local temporary storage files stored in remote file
+   systems, to allow PHP functions that do not support remote stream wrappers
+   access the file locally.
+
+
+## Installing:
+
+The module requires [using Composer to manage Drupal site dependencies](https://www.drupal.org/node/2718229).
+Once you have setup building your code base using composer, require the module
+via
+
+```$ composer require drupal/file_mdm```
+
+then enable the module as usual. Also enable the EXIF or font submodules if
+needed.
+
+
+## Configuration:
+
+- Go to _Manage > Configuration > System > File Metadata Manager_ and specify
+  the cache retention requirements, in general and/or per each metadata plugin.
+
+
+## Usage examples:
+
+Metadata are retrieved by specifying the protocol plugin required, and the
+specific _metadata key_ needed.
+
+For the 'getimagesize' protocol, the metadata keys supported correspond to the
+array keys returned by the PHP ```getimagesize()``` function:
+
+Key      | Description                                                  |
+---------|--------------------------------------------------------------|
+0        | Width of the image                                           |
+1        | Height of the image                                          |
+2        | The _IMAGETYPE_*_ constant indicating the type of the image  |
+3        | Text string with the correct _height="yyy" width="xxx"_ string that can be used directly in an IMG tag |
+mime     | The MIME type of the image                                   |
+channels | 3 for RGB pictures and 4 for CMYK pictures                   |
+bits     | The number of bits for each color                            |
+
+1. __Basic usage:__
+
+  a. Use the _file_metadata_manager_ service to prepare collecting metadata for
+     the file located at a desired URI:
+     ```php
+       $fmdm = \Drupal::service('file_metadata_manager');
+       $my_file_metadata = $fmdm->uri('public::/my_directory/test-image.jpeg');
+     ```
+  b. Get the metadata for the specific protocol, identified by the _plugin_, and
+     the metadata _key_ required:
+     ```php
+       $mime = $my_file_metadata->getMetadata('getimagesize', 'mime');
+     ```
+  c. Summarizing, in the context of a controller returning a render array:
+    ```php
+      $fmdm = \Drupal::service('file_metadata_manager');
+      $my_file_metadata = $fmdm->uri('public::/my_directory/test-image.jpeg');
+      $mime = $my_file_metadata->getMetadata('getimagesize', 'mime');
+      return ['#markup' => 'MIME type: ' . $mime];
+    ```
+
+    will return something like
+    ```
+    MIME type: image/jpeg
+    ```
+
+2. __Use a known local temp copy of the remote file to avoid remote file access:__
+
+  ```php
+    $fmdm = \Drupal::service('file_metadata_manager');
+    $my_file_metadata = $fmdm->uri('remote_wrapper::/my_directory/test-image.jpeg');
+    $my_file_metadata->setLocalTempPath($temp_path);
+    $mime = $my_file_metadata->getMetadata('getimagesize', 'mime');
+    ...
+  ```
+
+3. __Make a local temp copy of the remote file to avoid remote file access:__
+
+  ```php
+    $fmdm = \Drupal::service('file_metadata_manager');
+    $my_file_metadata = $fmdm->uri('remote_wrapper::/my_directory/test-image.jpeg');
+    $my_file_metadata->copyUriToTemp();
+    $mime = $my_file_metadata->getMetadata('getimagesize', 'mime');
+    ...
+  ```