--- /dev/null
+<?php
+
+namespace Drupal\media;
+
+use Drupal\Component\Plugin\ConfigurablePluginInterface;
+use Drupal\Component\Plugin\PluginInspectionInterface;
+use Drupal\Core\Plugin\PluginFormInterface;
+
+/**
+ * Defines the interface for media source plugins.
+ *
+ * Media sources provide the critical link between media items in Drupal and the
+ * actual media itself, which typically exists independently of Drupal. Each
+ * media source works with a certain kind of media. For example, local files and
+ * YouTube videos can both be catalogued in a similar way as media items, but
+ * they need very different handling to actually display them.
+ *
+ * Each media type needs exactly one source. A single source can be used on many
+ * media types.
+ *
+ * Examples of possible sources are:
+ * - File: handles local files,
+ * - Image: handles local images,
+ * - oEmbed: handles resources that are exposed through the oEmbed standard,
+ * - YouTube: handles YouTube videos,
+ * - SoundCould: handles SoundCloud audio,
+ * - Instagram: handles Instagram posts,
+ * - Twitter: handles tweets,
+ * - ...
+ *
+ * Their responsibilities are:
+ * - Defining how media is represented (stored). Media sources are not
+ * responsible for actually storing the media. They only define how it is
+ * represented on a media item (usually using some kind of a field).
+ * - Providing thumbnails. Media sources that are responsible for remote
+ * media will generally fetch the image from a third-party API and make
+ * it available for the local usage. Media sources that represent local
+ * media (such as images) will usually use some locally provided image.
+ * Media sources should fall back to a pre-defined default thumbnail if
+ * everything else fails.
+ * - Validating a media item before it is saved. The entity constraint system
+ * will be used to ensure the valid structure of the media item.
+ * For example, media sources that represent remote media might check the
+ * URL or other identifier, while sources that represent local files might
+ * check the MIME type of the file.
+ * - Providing a default name for a media item. This will save users from
+ * manually entering the name when it can be reliably set automatically.
+ * Media sources for local files will generally use the filename, while media
+ * sources for remote resources might obtain a title attribute through a
+ * third-party API. The name can always be overridden by the user.
+ * - Providing metadata specific to the given media type. For example, remote
+ * media sources generally get information available through a
+ * third-party API and make it available to Drupal, while local media sources
+ * can expose things such as EXIF or ID3.
+ * - Mapping metadata to the media item. Metadata that a media source exposes
+ * can automatically be mapped to the fields on the media item. Media
+ * sources will be able to define how this is done.
+ *
+ * @see \Drupal\media\Annotation\MediaSource
+ * @see \Drupal\media\MediaSourceBase
+ * @see \Drupal\media\MediaSourceManager
+ * @see \Drupal\media\MediaTypeInterface
+ * @see \Drupal\media\MediaSourceEntityConstraintsInterface
+ * @see \Drupal\media\MediaSourceFieldConstraintsInterface
+ * @see plugin_api
+ */
+interface MediaSourceInterface extends PluginInspectionInterface, ConfigurablePluginInterface, PluginFormInterface {
+
+ /**
+ * Default empty value for metadata fields.
+ */
+ const METADATA_FIELD_EMPTY = '_none';
+
+ /**
+ * Gets a list of metadata attributes provided by this plugin.
+ *
+ * Most media sources have associated metadata, describing attributes
+ * such as:
+ * - dimensions
+ * - duration
+ * - encoding
+ * - date
+ * - location
+ * - permalink
+ * - licensing information
+ * - ...
+ *
+ * This method should list all metadata attributes that a media source MAY
+ * offer. In other words: it is possible that a particular media item does
+ * not contain a certain attribute. For example: an oEmbed media source can
+ * contain both video and images. Images don't have a duration, but
+ * videos do.
+ *
+ * (The term 'attributes' was chosen because it cannot be confused
+ * with 'fields' and 'properties', both of which are concepts in Drupal's
+ * Entity Field API.)
+ *
+ * @return array
+ * Associative array with:
+ * - keys: metadata attribute names
+ * - values: human-readable labels for those attribute names
+ */
+ public function getMetadataAttributes();
+
+ /**
+ * Gets the value for a metadata attribute for a given media item.
+ *
+ * @param \Drupal\media\MediaInterface $media
+ * A media item.
+ * @param string $attribute_name
+ * Name of the attribute to fetch.
+ *
+ * @return mixed|null
+ * Metadata attribute value or NULL if unavailable.
+ */
+ public function getMetadata(MediaInterface $media, $attribute_name);
+
+ /**
+ * Get the source field definition for a media type.
+ *
+ * @param \Drupal\media\MediaTypeInterface $type
+ * A media type.
+ *
+ * @return \Drupal\Core\Field\FieldDefinitionInterface|null
+ * The source field definition, or NULL if it doesn't exist or has not been
+ * configured yet.
+ */
+ public function getSourceFieldDefinition(MediaTypeInterface $type);
+
+ /**
+ * Creates the source field definition for a type.
+ *
+ * @param \Drupal\media\MediaTypeInterface $type
+ * The media type.
+ *
+ * @return \Drupal\field\FieldConfigInterface
+ * The unsaved field definition. The field storage definition, if new,
+ * should also be unsaved.
+ */
+ public function createSourceField(MediaTypeInterface $type);
+
+}
projects / yaffs-website / blobdiff