www.aleph1.co.uk Git - yaffs-website/blob - web/core/modules/media/src/MediaSourceInterface.php

   1 <?php
   2
   3 namespace Drupal\media;
   4
   5 use Drupal\Component\Plugin\ConfigurablePluginInterface;
   6 use Drupal\Component\Plugin\PluginInspectionInterface;
   7 use Drupal\Core\Entity\Display\EntityFormDisplayInterface;
   8 use Drupal\Core\Entity\Display\EntityViewDisplayInterface;
   9 use Drupal\Core\Plugin\PluginFormInterface;
  10
  11 /**
  12  * Defines the interface for media source plugins.
  13  *
  14  * Media sources provide the critical link between media items in Drupal and the
  15  * actual media itself, which typically exists independently of Drupal. Each
  16  * media source works with a certain kind of media. For example, local files and
  17  * YouTube videos can both be catalogued in a similar way as media items, but
  18  * they need very different handling to actually display them.
  19  *
  20  * Each media type needs exactly one source. A single source can be used on many
  21  * media types.
  22  *
  23  * Examples of possible sources are:
  24  * - File: handles local files,
  25  * - Image: handles local images,
  26  * - oEmbed: handles resources that are exposed through the oEmbed standard,
  27  * - YouTube: handles YouTube videos,
  28  * - SoundCloud: handles SoundCloud audio,
  29  * - Instagram: handles Instagram posts,
  30  * - Twitter: handles tweets,
  31  * - ...
  32  *
  33  * Their responsibilities are:
  34  * - Defining how media is represented (stored). Media sources are not
  35  *   responsible for actually storing the media. They only define how it is
  36  *   represented on a media item (usually using some kind of a field).
  37  * - Providing thumbnails. Media sources that are responsible for remote
  38  *   media will generally fetch the image from a third-party API and make
  39  *   it available for the local usage. Media sources that represent local
  40  *   media (such as images) will usually use some locally provided image.
  41  *   Media sources should fall back to a pre-defined default thumbnail if
  42  *   everything else fails.
  43  * - Validating a media item before it is saved. The entity constraint system
  44  *   will be used to ensure the valid structure of the media item.
  45  *   For example, media sources that represent remote media might check the
  46  *   URL or other identifier, while sources that represent local files might
  47  *   check the MIME type of the file.
  48  * - Providing a default name for a media item. This will save users from
  49  *   manually entering the name when it can be reliably set automatically.
  50  *   Media sources for local files will generally use the filename, while media
  51  *   sources for remote resources might obtain a title attribute through a
  52  *   third-party API. The name can always be overridden by the user.
  53  * - Providing metadata specific to the given media type. For example, remote
  54  *   media sources generally get information available through a
  55  *   third-party API and make it available to Drupal, while local media sources
  56  *   can expose things such as EXIF or ID3.
  57  * - Mapping metadata to the media item. Metadata that a media source exposes
  58  *   can automatically be mapped to the fields on the media item. Media
  59  *   sources will be able to define how this is done.
  60  *
  61  * @see \Drupal\media\Annotation\MediaSource
  62  * @see \Drupal\media\MediaSourceBase
  63  * @see \Drupal\media\MediaSourceManager
  64  * @see \Drupal\media\MediaTypeInterface
  65  * @see \Drupal\media\MediaSourceEntityConstraintsInterface
  66  * @see \Drupal\media\MediaSourceFieldConstraintsInterface
  67  * @see plugin_api
  68  */
  69 interface MediaSourceInterface extends PluginInspectionInterface, ConfigurablePluginInterface, PluginFormInterface {
  70
  71   /**
  72    * Default empty value for metadata fields.
  73    */
  74   const METADATA_FIELD_EMPTY = '_none';
  75
  76   /**
  77    * Gets a list of metadata attributes provided by this plugin.
  78    *
  79    * Most media sources have associated metadata, describing attributes
  80    * such as:
  81    * - dimensions
  82    * - duration
  83    * - encoding
  84    * - date
  85    * - location
  86    * - permalink
  87    * - licensing information
  88    * - ...
  89    *
  90    * This method should list all metadata attributes that a media source MAY
  91    * offer. In other words: it is possible that a particular media item does
  92    * not contain a certain attribute. For example: an oEmbed media source can
  93    * contain both video and images. Images don't have a duration, but
  94    * videos do.
  95    *
  96    * (The term 'attributes' was chosen because it cannot be confused
  97    * with 'fields' and 'properties', both of which are concepts in Drupal's
  98    * Entity Field API.)
  99    *
 100    * @return array
 101    *   Associative array with:
 102    *   - keys: metadata attribute names
 103    *   - values: human-readable labels for those attribute names
 104    */
 105   public function getMetadataAttributes();
 106
 107   /**
 108    * Gets the value for a metadata attribute for a given media item.
 109    *
 110    * @param \Drupal\media\MediaInterface $media
 111    *   A media item.
 112    * @param string $attribute_name
 113    *   Name of the attribute to fetch.
 114    *
 115    * @return mixed|null
 116    *   Metadata attribute value or NULL if unavailable.
 117    */
 118   public function getMetadata(MediaInterface $media, $attribute_name);
 119
 120   /**
 121    * Get the source field definition for a media type.
 122    *
 123    * @param \Drupal\media\MediaTypeInterface $type
 124    *   A media type.
 125    *
 126    * @return \Drupal\Core\Field\FieldDefinitionInterface|null
 127    *   The source field definition, or NULL if it doesn't exist or has not been
 128    *   configured yet.
 129    */
 130   public function getSourceFieldDefinition(MediaTypeInterface $type);
 131
 132   /**
 133    * Creates the source field definition for a type.
 134    *
 135    * @param \Drupal\media\MediaTypeInterface $type
 136    *   The media type.
 137    *
 138    * @return \Drupal\field\FieldConfigInterface
 139    *   The unsaved field definition. The field storage definition, if new,
 140    *   should also be unsaved.
 141    */
 142   public function createSourceField(MediaTypeInterface $type);
 143
 144   /**
 145    * Prepares the media type fields for this source in the view display.
 146    *
 147    * This method should normally call
 148    * \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent() or
 149    * \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent() to
 150    * configure the media type fields in the view display.
 151    *
 152    * @param \Drupal\media\MediaTypeInterface $type
 153    *   The media type which is using this source.
 154    * @param \Drupal\Core\Entity\Display\EntityViewDisplayInterface $display
 155    *   The display which should be prepared.
 156    *
 157    * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent()
 158    * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent()
 159    */
 160   public function prepareViewDisplay(MediaTypeInterface $type, EntityViewDisplayInterface $display);
 161
 162   /**
 163    * Prepares the media type fields for this source in the form display.
 164    *
 165    * This method should normally call
 166    * \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent() or
 167    * \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent() to
 168    * configure the media type fields in the form display.
 169    *
 170    * @param \Drupal\media\MediaTypeInterface $type
 171    *   The media type which is using this source.
 172    * @param \Drupal\Core\Entity\Display\EntityFormDisplayInterface $display
 173    *   The display which should be prepared.
 174    *
 175    * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::setComponent()
 176    * @see \Drupal\Core\Entity\Display\EntityDisplayInterface::removeComponent()
 177    */
 178   public function prepareFormDisplay(MediaTypeInterface $type, EntityFormDisplayInterface $display);
 179
 180   /**
 181    * Get the primary value stored in the source field.
 182    *
 183    * @param MediaInterface $media
 184    *   A media item.
 185    *
 186    * @return mixed
 187    *   The source value.
 188    *
 189    * @throws \RuntimeException
 190    *   If the source field for the media source is not defined.
 191    */
 192   public function getSourceFieldValue(MediaInterface $media);
 193
 194 }