<?php

namespace Drupal\Core\Field;

use Drupal\Component\Plugin\CategorizingPluginManagerInterface;
use Drupal\Component\Plugin\PluginManagerInterface;
use Drupal\Core\Entity\FieldableEntityInterface;

/**
 * Defines an interface for the field type plugin manager.
 *
 * @ingroup field_types
 */
interface FieldTypePluginManagerInterface extends PluginManagerInterface, CategorizingPluginManagerInterface {

  /**
   * Creates a new field item list.
   *
   * The provided entity is assigned as the parent of the created item list.
   * However, it is the responsibility of the caller (usually the parent entity
   * itself) to make the parent aware of the field as a new child.
   *
   * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
   *   The entity this field item list will be part of.
   * @param string $field_name
   *   The name of the field.
   * @param mixed $values
   *   (optional) The data value. If set, it has to match one of the supported
   *   data type format as documented for the data type classes.
   *
   * @return \Drupal\Core\Field\FieldItemListInterface
   *   The instantiated object.
   */
  public function createFieldItemList(FieldableEntityInterface $entity, $field_name, $values = NULL);

  /**
   * Creates a new field item as part of a field item list.
   *
   * The provided item list is assigned as the parent of the created item. It
   * However, it is the responsibility of the caller (usually the parent list
   * itself) to have the parent aware of the item as a new child.
   *
   * @param \Drupal\Core\Field\FieldItemListInterface $items
   *   The field item list, for which to create a new item.
   * @param int $index
   *   The list index at which the item is created.
   * @param array|null $values
   *   (optional) The values to assign to the field item properties.
   *
   * @return \Drupal\Core\Field\FieldItemInterface
   *   The instantiated object.
   */
  public function createFieldItem(FieldItemListInterface $items, $index, $values = NULL);

  /**
   * Returns the default field-level settings for a field type.
   *
   * @param string $type
   *   A field type name.
   *
   * @return array
   *   The field's default settings, as provided by the plugin definition, or
   *   an empty array if type or settings are undefined.
   */
  public function getDefaultFieldSettings($type);

  /**
   * Returns the default storage-level settings for a field type.
   *
   * @param string $type
   *   A field type name.
   *
   * @return array
   *   The type's default settings, as provided by the plugin definition, or an
   *   empty array if type or settings are undefined.
   */
  public function getDefaultStorageSettings($type);

  /**
   * Returns the summary of storage-level settings for a field type.
   *
   * @param \Drupal\Core\Field\FieldStorageDefinitionInterface $storage_definition
   *   The field storage definition.
   *
   * @return array
   *   A renderable array for the field's storage-level settings summary, as
   *   provided by the plugin definition.
   */
  public function getStorageSettingsSummary(FieldStorageDefinitionInterface $storage_definition): array;

  /**
   * Returns the summary of field-level settings for a field type.
   *
   * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
   *   The field entity.
   *
   * @return array
   *   A renderable array for the field's field-level settings summary, as
   *   provided by the plugin definition.
   */
  public function getFieldSettingsSummary(FieldDefinitionInterface $field_definition): array;

  /**
   * Gets the definition of all field types that can be added via UI.
   *
   * If the field type extends
   * \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface, then include the
   * preconfigured definitions. The key is 'field_ui', the base field name, and
   * the key from getPreconfiguredOptions(), joined with ':'.
   *
   * @return array
   *   An array of field type definitions.
   */
  public function getUiDefinitions();

  /**
   * Get the field type definitions that can be added via UI for an entity type.
   *
   * @param string $entity_type_id
   *   The entity type id.
   *
   * @return array
   *   An array of field type definitions.
   *
   * @see \Drupal\Core\Field\FieldTypePluginManagerInterface::getUiDefinitions()
   * @see hook_field_info_entity_type_ui_definitions_alter()
   */
  public function getEntityTypeUiDefinitions(string $entity_type_id): array;

  /**
   * Returns preconfigured field options for a field type.
   *
   * This is a wrapper around
   * \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions()
   * allowing modules to alter the result of this method by implementing
   * hook_field_ui_preconfigured_options_alter().
   *
   * @param string $field_type
   *   The field type plugin ID.
   *
   * @return array
   *   A multi-dimensional array as returned from
   *   \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions().
   *
   * @see \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions()
   * @see hook_field_ui_preconfigured_options_alter()
   */
  public function getPreconfiguredOptions($field_type);

  /**
   * Returns the PHP class that implements the field type plugin.
   *
   * @param string $type
   *   A field type name.
   *
   * @return string
   *   Field type plugin class name.
   *
   * @throws \Drupal\Component\Plugin\Exception\PluginNotFoundException
   *   Thrown if the field type plugin name is invalid.
   */
  public function getPluginClass($type);

}
