Issue #3088476 by phenaproxima, Wim Leers: Document Media Library's API and architecture

<?php

/**

 * @file

 * Documentation related to Media Library.

 */

/**

 * @defgroup media_library_architecture Media Library Architecture

 * @{

 *

 * Media Library is a UI for the core Media module. It provides a visual

 * interface for users to manage media in their site, and it allows authors to

 * visually select media for use in entity reference and text fields, using a

 * modal dialog.

 *

 * In order to provide a consistent user experience, Media Library is

 * intentionally opinionated, with few extension points and no hooks. Most of

 * its code is internal and should not be extended or instantiated by external

 * code.

 *

 * @section openers Openers

 * Interaction with the modal media library dialog is mediated by "opener"

 * services. All openers must implement

 * \Drupal\media_library\MediaLibraryOpenerInterface.

 *

 * Openers are responsible for determining access to the media library, and for

 * generating an AJAX response when the user has finished selecting media items

 * in the library. An opener is a "bridge" between the opinionated media library

 * modal dialog and whatever is consuming it, allowing the dialog to be

 * triggered in a way that makes sense for that particular consumer. Examples in

 * Drupal core include entity reference fields and text editors.

 *

 * @see \Drupal\media_library\MediaLibraryOpenerInterface

 * @see \Drupal\media_library\MediaLibraryEditorOpener

 * @see \Drupal\media_library\MediaLibraryFieldWidgetOpener

 *

 * @section state Modal dialog state

 * When the media library modal is used, its configuration and state (such as

 * how many items are currently selected, the maximum number that can be

 * selected, which media types the user is allowed to see, and so forth) are

 * stored in an instance of \Drupal\media_library\MediaLibraryState. The state

 * object also stores the service ID of the opener being used, as well as any

 * additional parameters or data that are specific to that opener.

 *

 * The media library state is passed between the user and the server in the

 * URL's query parameters. Therefore, the state is also protected by a hash in

 * order to prevent tampering.

 *

 * @see \Drupal\media_library\MediaLibraryState

 *

 * @section add_form Adding media in the dialog

 * Users with appropriate permissions can add media to the library from directly

 * within the modal dialog.

 *

 * This interaction is implemented using forms, and is customizable by modules.

 * Since the media library is segmented by media type, each media type can

 * expose a different form for adding media of that type; the type's source

 * plugin specifies the actual form class to use. Here is an example of a media

 * source plugin definition which provides an add form for the media library:

 *

 * @code

 * @MediaSource(

 *   id = "file",

 *   label = @Translation("File"),

 *   description = @Translation("Use local files for reusable media."),

 *   allowed_field_types = {"file"},

 *   default_thumbnail_filename = "generic.png",

 *   forms = {

 *     "media_library_add" = "\Drupal\media_library\Form\FileUploadForm",

 *   },

 * )

 * @endcode

 *

 * This can also be done in hook_media_source_info_alter(). For example:

 *

 * @code

 * function example_media_source_info_alter(array &$sources) {

 *   $sources['file']['forms']['media_library_add'] = "\Drupal\media_library\Form\FileUploadForm";

 * }

 * @endcode

 *

 * The add form is a standard form class, and can be altered by modules and

 * themes just like any other form. For easier implementation, it is recommended

 * that modules extend \Drupal\media_library\Form\AddFormBase when providing add

 * forms.

 *

 * @see \Drupal\media_library\Form\AddFormBase

 * @see \Drupal\media_library\Form\FileUploadForm

 * @see \Drupal\media_library\Form\OEmbedForm

 *

 * @}

 */