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