www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/file_mdm/README.md

   1 # File metadata manager
   2
   3 A Drupal 8 module providing a file metadata manager service and API. Allows to
   4 get, via an unified API, information stored in files like EXIF photo
   5 information, TrueType font information, etc.
   6
   7 Metadata protocols are pluggable. Developers can implement a plugin and use the
   8 service framework to get the metadata required.
   9
  10 The following plugins are provided by the module:
  11
  12 Plugin        | Read | Write | Description                                                  |
  13 --------------|:----:|:-----:|--------------------------------------------------------------|
  14 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.        |
  15 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.         |
  16 getimagesize  | X    |       | Caches calls to the PHP ```getimagesize()``` function.        |
  17
  18 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).
  19
  20
  21 ## Features:
  22
  23 1. Load from, and save to, file embedded metadata directly from the files.
  24 2. Metadata for a file is statically cached during a request's lifetime. This
  25    avoids different modules all repeat I/O on the same file.
  26 3. Metadata can be cached in a Drupal cache bin to avoid repeating I/O on the
  27    files in successive requests.
  28 4. Metadata standards (EXIF, TTF, etc.) are implemented as plugins. The service
  29    loads the metadata plugin needed based on the calling code request.
  30 5. Manages copying to/from local temporary storage files stored in remote file
  31    systems, to allow PHP functions that do not support remote stream wrappers
  32    access the file locally.
  33
  34
  35 ## Installing:
  36
  37 The module requires [using Composer to manage Drupal site dependencies](https://www.drupal.org/node/2718229).
  38 Once you have setup building your code base using composer, require the module
  39 via
  40
  41 ```$ composer require drupal/file_mdm```
  42
  43 then enable the module as usual. Also enable the EXIF or font submodules if
  44 needed.
  45
  46
  47 ## Configuration:
  48
  49 - Go to _Manage > Configuration > System > File Metadata Manager_ and specify
  50   the cache retention requirements, in general and/or per each metadata plugin.
  51
  52
  53 ## Usage examples:
  54
  55 Metadata are retrieved by specifying the protocol plugin required, and the
  56 specific _metadata key_ needed.
  57
  58 For the 'getimagesize' protocol, the metadata keys supported correspond to the
  59 array keys returned by the PHP ```getimagesize()``` function:
  60
  61 Key      | Description                                                  |
  62 ---------|--------------------------------------------------------------|
  63 0        | Width of the image                                           |
  64 1        | Height of the image                                          |
  65 2        | The _IMAGETYPE_*_ constant indicating the type of the image  |
  66 3        | Text string with the correct _height="yyy" width="xxx"_ string that can be used directly in an IMG tag |
  67 mime     | The MIME type of the image                                   |
  68 channels | 3 for RGB pictures and 4 for CMYK pictures                   |
  69 bits     | The number of bits for each color                            |
  70
  71 1. __Basic usage:__
  72
  73   a. Use the _file_metadata_manager_ service to prepare collecting metadata for
  74      the file located at a desired URI:
  75      ```php
  76        $fmdm = \Drupal::service('file_metadata_manager');
  77        $my_file_metadata = $fmdm->uri('public::/my_directory/test-image.jpeg');
  78      ```
  79   b. Get the metadata for the specific protocol, identified by the _plugin_, and
  80      the metadata _key_ required:
  81      ```php
  82        $mime = $my_file_metadata->getMetadata('getimagesize', 'mime');
  83      ```
  84   c. Summarizing, in the context of a controller returning a render array:
  85     ```php
  86       $fmdm = \Drupal::service('file_metadata_manager');
  87       $my_file_metadata = $fmdm->uri('public::/my_directory/test-image.jpeg');
  88       $mime = $my_file_metadata->getMetadata('getimagesize', 'mime');
  89       return ['#markup' => 'MIME type: ' . $mime];
  90     ```
  91
  92     will return something like
  93     ```
  94     MIME type: image/jpeg
  95     ```
  96
  97 2. __Use a known local temp copy of the remote file to avoid remote file access:__
  98
  99   ```php
 100     $fmdm = \Drupal::service('file_metadata_manager');
 101     $my_file_metadata = $fmdm->uri('remote_wrapper::/my_directory/test-image.jpeg');
 102     $my_file_metadata->setLocalTempPath($temp_path);
 103     $mime = $my_file_metadata->getMetadata('getimagesize', 'mime');
 104     ...
 105   ```
 106
 107 3. __Make a local temp copy of the remote file to avoid remote file access:__
 108
 109   ```php
 110     $fmdm = \Drupal::service('file_metadata_manager');
 111     $my_file_metadata = $fmdm->uri('remote_wrapper::/my_directory/test-image.jpeg');
 112     $my_file_metadata->copyUriToTemp();
 113     $mime = $my_file_metadata->getMetadata('getimagesize', 'mime');
 114     ...
 115   ```