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

   1 # File metadata EXIF
   2
   3 A Drupal 8 module providing a file metadata plugin for the EXIF protocol.
   4
   5
   6 ## Features:
   7
   8 Uses the [PHP Exif Library](https://github.com/lsolesen/pel) to read/write EXIF
   9 information to image files, so bypassing the limitations of the standard PHP
  10 Exif extensions which only provides read capabilities.
  11
  12
  13 ## Usage examples:
  14
  15 1. __Get EXIF information from a file:__
  16
  17   a. Prepare collecting metadata for the file located at a desired URI:
  18
  19      ```php
  20       $fmdm = \Drupal::service('file_metadata_manager');
  21       $my_file_metadata = $fmdm->uri('public::/my_directory/test-exif.jpeg');
  22       ...
  23      ```
  24
  25   b. Get the metadata for the metadata _$key_ required. The value returned is an
  26      associative array with two keys:
  27      - 'text': the string representation of the EXIF tag, suitable for
  28        presentation;
  29      - 'value': the EXIF tag value in PEL internal format.
  30
  31     ```php
  32      ...
  33      $val = $my_file_metadata->getMetadata('exif', $key);
  34      ...
  35     ```
  36
  37   c. EXIF metadata is organized in 'headers' (IFDs) and 'tags'. For this reason,
  38      the metadata _$key_ can be specified in the ```getMetadata``` method:
  39      - as a string: in this case, it is assumed that a TAG is specified, and the
  40        default IFD for that TAG will be used to fetch the information:
  41      - as an array: in this case, the first and the second array elements
  42        specify respectively the IFD and the TAG requested. IFD and TAG can be
  43        strings, or integers.
  44      The following statements all are equivalent in returning the same
  45      information about the 'ApertureValue' TAG in the 'Exif' IFD:
  46
  47      ```php
  48       ...
  49       $aperture = $my_file_metadata->getMetadata('exif', 'ApertureValue');
  50       $aperture = $my_file_metadata->getMetadata('exif', ['Exif', 'ApertureValue']);
  51       $aperture = $my_file_metadata->getMetadata('exif', [2, 'ApertureValue']);
  52       $aperture = $my_file_metadata->getMetadata('exif', ['Exif', 0x9202]);
  53       $aperture = $my_file_metadata->getMetadata('exif', [2, 0x9202]);
  54       ...
  55      ```
  56
  57   d. Get a list of IFDs:
  58
  59      ```php
  60       ...
  61       $my_file_metadata->getSupportedKeys('exif', ['ifds' => TRUE]);
  62       ...
  63      ```
  64
  65   e. Get a list of TAGs for a given IFD:
  66
  67      ```php
  68       ...
  69       $my_file_metadata->getSupportedKeys('exif', ['ifd' => 'GPS']);
  70       ...
  71      ```
  72
  73   f. Walk through all possible IFDs/TAGs and build a table with results:
  74
  75      ```php
  76       ...
  77       $header = [
  78         ['data' => 'key'],
  79         ['data' => 'text'],
  80         ['data' => 'value'],
  81       ];
  82       $rows = [];
  83       foreach ($my_file_metadata->getSupportedKeys('exif', ['ifds' => TRUE]) as $ifd) {
  84         $rows[] = [['data' => $ifd[0], 'colspan' => 3]];
  85         $keys = $my_file_metadata->getSupportedKeys('exif', ['ifd' => $ifd[0]]);
  86         foreach ($keys as $key) {
  87           $x = $my_file_metadata->getMetadata('exif', $key);
  88           if ($x) {
  89             $rows[] = ['data' => [$key[1], $x ? $x['text'] : NULL, $x ? var_export($x['value'], TRUE) : NULL]];
  90           }
  91         }
  92       }
  93       return [
  94         '#theme' => 'table',
  95         '#header' => $header,
  96         '#rows' => $rows,
  97       ];
  98      ```
  99
 100 2. __Change EXIF information and save to file:__
 101
 102 Changing EXIF information and saving it back to the file requires some
 103 understanding of how the PEL library manages EXIF entries.
 104
 105 a. If you are changing information that is _already_ existing in the source
 106    file, then you can use the plugin ```setMetadata``` method, passing the value
 107    that the PEL Exif entry expects:
 108
 109    ```php
 110     ...
 111     $my_file_metadata->setMetadata('exif', 'Orientation', 7);
 112     ...
 113    ```
 114
 115 b. If you are _adding_ a TAG that was not existing before, you need to pass a
 116    new PEL Exif entry, as expected for that entry. This can also be done as an
 117    alternative to change an existing entry:
 118
 119   ```php
 120    ...
 121    $artist_tag = \Drupal::service('file_mdm_exif.tag_mapper')->resolveKeyToIfdAndTag('Artist');
 122    $value = 'MEEeeee!';
 123    $artist = new PelEntryAscii($artist_tag['tag'], $value);
 124    $my_file_metadata->setMetadata('exif', 'Artist', $artist);
 125    ...
 126   ```
 127
 128 c. Save changed metadata to file:
 129
 130   ```php
 131    ...
 132    $my_file_metadata->saveMetadataToFile('exif');
 133    ...
 134   ```