Drupal: Plugin API and PHP Attributes

<?php

// Before: Drupal 10.0 and 10.1 style, still supported but deprecated.
/**
 * Shows the opening hours of the museum.
 *
 * @Block(
 *   id = "meridian_opening_hours",
 *   admin_label = @Translation("Opening hours"),
 *   category = @Translation("Meridian Museum"),
 * )
 */
final class OpeningHoursBlock extends BlockBase {
}

// After: Drupal 10.2 and later.
use Drupal\Core\Block\Attribute\Block;
use Drupal\Core\Block\BlockBase;
use Drupal\Core\StringTranslation\TranslatableMarkup;

/**
 * Shows the opening hours of the museum.
 */
#[Block(
  id: 'meridian_opening_hours',
  admin_label: new TranslatableMarkup('Opening hours'),
  category: new TranslatableMarkup('Meridian Museum'),
)]
final class OpeningHoursBlock extends BlockBase {
}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection;

use Drupal\Component\Plugin\PluginInspectionInterface;
use Drupal\Core\Entity\ContentEntityInterface;

/**
 * Turns collection objects into a downloadable representation.
 */
interface ObjectExporterInterface extends PluginInspectionInterface {

  /**
   * The human readable label of the exporter.
   */
  public function label(): string;

  /**
   * Exports the given objects.
   *
   * @param \Drupal\Core\Entity\ContentEntityInterface[] $objects
   *   The collection objects to export.
   *
   * @return string
   *   The exported file contents.
   */
  public function export(array $objects): string;

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Attribute;

use Drupal\Component\Plugin\Attribute\Plugin;
use Drupal\Core\StringTranslation\TranslatableMarkup;

/**
 * Defines an object exporter attribute for plugin discovery.
 *
 * @see \Drupal\meridian_collection\ObjectExporterManager
 * @see \Drupal\meridian_collection\ObjectExporterInterface
 */
#[\Attribute(\Attribute::TARGET_CLASS)]
class ObjectExporter extends Plugin {

  /**
   * Constructs an ObjectExporter attribute.
   *
   * @param string $id
   *   The plugin ID.
   * @param \Drupal\Core\StringTranslation\TranslatableMarkup $label
   *   The human readable name of the exporter.
   * @param \Drupal\Core\StringTranslation\TranslatableMarkup|null $description
   *   (optional) A short description shown on the settings form.
   * @param string $extension
   *   (optional) The file extension of the export, without a dot.
   * @param string $mime_type
   *   (optional) The MIME type of the export.
   * @param class-string|null $deriver
   *   (optional) The deriver class.
   */
  public function __construct(
    public readonly string $id,
    public readonly TranslatableMarkup $label,
    public readonly ?TranslatableMarkup $description = NULL,
    public readonly string $extension = 'txt',
    public readonly string $mime_type = 'text/plain',
    public readonly ?string $deriver = NULL,
  ) {}

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection;

use Drupal\Core\Plugin\PluginBase;

/**
 * Base class for object exporters.
 */
abstract class ObjectExporterBase extends PluginBase implements ObjectExporterInterface {

  /**
   * {@inheritdoc}
   */
  public function label(): string {
    return (string) $this->pluginDefinition['label'];
  }

  /**
   * Reads one value of an object field, for subclasses.
   */
  protected function fieldValue(\Drupal\Core\Entity\ContentEntityInterface $object, string $field): string {
    return (string) $object->get($field)->value;
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection;

use Drupal\Component\Plugin\Exception\PluginException;
use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Extension\ModuleHandlerInterface;
use Drupal\Core\Plugin\DefaultPluginManager;
use Drupal\meridian_collection\Attribute\ObjectExporter;

/**
 * Manages object exporter plugins.
 */
class ObjectExporterManager extends DefaultPluginManager {

  public function __construct(
    \Traversable $namespaces,
    CacheBackendInterface $cache_backend,
    ModuleHandlerInterface $module_handler,
  ) {
    parent::__construct(
      'Plugin/ObjectExporter',
      $namespaces,
      $module_handler,
      ObjectExporterInterface::class,
      ObjectExporter::class,
    );
    // Other modules implement hook_meridian_object_exporter_info_alter().
    $this->alterInfo('meridian_object_exporter_info');
    // Derivatives of the label sheet are built from gallery terms, so the
    // cached definitions must be dropped when a gallery term changes.
    $this->setCacheBackend($cache_backend, 'meridian_object_exporter_plugins', ['taxonomy_term_list:gallery']);
  }

  /**
   * {@inheritdoc}
   */
  public function processDefinition(&$definition, $plugin_id): void {
    parent::processDefinition($definition, $plugin_id);
    foreach (['label', 'extension', 'mime_type'] as $required) {
      if (empty($definition[$required])) {
        throw new PluginException(sprintf('The object exporter %s must define the "%s" key.', $plugin_id, $required));
      }
    }
  }

}

services:
  plugin.manager.meridian_object_exporter:
    class: Drupal\meridian_collection\ObjectExporterManager
    parent: default_plugin_manager
  Drupal\meridian_collection\ObjectExporterManager: '@plugin.manager.meridian_object_exporter'

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Hook;

use Drupal\Core\Hook\Attribute\Hook;

/**
 * Alters object exporter definitions.
 */
final class ExporterHooks {

  /**
   * Implements hook_meridian_object_exporter_info_alter().
   */
  #[Hook('meridian_object_exporter_info_alter')]
  public function alterExporters(array &$definitions): void {
    // The definition array is the processed attribute: change keys, swap
    // the class, or unset an entry to hide the plugin.
    unset($definitions['meridian_json']);
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Plugin\ObjectExporter;

use Drupal\Component\Plugin\ConfigurableInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Plugin\PluginFormInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\meridian_collection\Attribute\ObjectExporter;
use Drupal\meridian_collection\ObjectExporterBase;

/**
 * Exports collection objects as comma separated values.
 */
#[ObjectExporter(
  id: 'meridian_csv',
  label: new TranslatableMarkup('CSV'),
  description: new TranslatableMarkup('One line per object, for spreadsheets.'),
  extension: 'csv',
  mime_type: 'text/csv',
)]
final class CsvExporter extends ObjectExporterBase implements ConfigurableInterface, PluginFormInterface {

  public function __construct(array $configuration, $plugin_id, $plugin_definition) {
    parent::__construct($configuration, $plugin_id, $plugin_definition);
    $this->setConfiguration($configuration);
  }

  public function export(array $objects): string {
    $handle = fopen('php://temp', 'r+');
    if ($this->configuration['include_header']) {
      fputcsv($handle, ['accession_number', 'title', 'period', 'material'], $this->configuration['delimiter'], '"', '\\');
    }
    foreach ($objects as $object) {
      fputcsv($handle, [
        $this->fieldValue($object, 'accession_number'),
        (string) $object->label(),
        $this->fieldValue($object, 'period'),
        $this->fieldValue($object, 'material'),
      ], $this->configuration['delimiter'], '"', '\\');
    }
    rewind($handle);
    return (string) stream_get_contents($handle);
  }

  public function defaultConfiguration(): array {
    return ['delimiter' => ',', 'include_header' => TRUE];
  }

  public function getConfiguration(): array {
    return $this->configuration;
  }

  public function setConfiguration(array $configuration): void {
    $this->configuration = $configuration + $this->defaultConfiguration();
  }

  public function buildConfigurationForm(array $form, FormStateInterface $form_state): array {
    $form['delimiter'] = [
      '#type' => 'select',
      '#title' => $this->t('Delimiter'),
      '#options' => [',' => $this->t('Comma'), ';' => $this->t('Semicolon'), "\t" => $this->t('Tab')],
      '#default_value' => $this->configuration['delimiter'],
    ];
    $form['include_header'] = [
      '#type' => 'checkbox',
      '#title' => $this->t('Include a header row'),
      '#default_value' => $this->configuration['include_header'],
    ];
    return $form;
  }

  public function validateConfigurationForm(array &$form, FormStateInterface $form_state): void {
    if (!in_array($form_state->getValue('delimiter'), [',', ';', "\t"], TRUE)) {
      $form_state->setError($form['delimiter'], $this->t('Choose one of the offered delimiters.'));
    }
  }

  public function submitConfigurationForm(array &$form, FormStateInterface $form_state): void {
    $this->configuration['delimiter'] = $form_state->getValue('delimiter');
    $this->configuration['include_header'] = (bool) $form_state->getValue('include_header');
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Plugin\ObjectExporter;

use Drupal\Component\Serialization\Json;
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\meridian_collection\Attribute\ObjectExporter;
use Drupal\meridian_collection\ObjectExporterBase;

/**
 * Exports collection objects as JSON.
 */
#[ObjectExporter(
  id: 'meridian_json',
  label: new TranslatableMarkup('JSON'),
  extension: 'json',
  mime_type: 'application/json',
)]
final class JsonExporter extends ObjectExporterBase {

  public function export(array $objects): string {
    $rows = [];
    foreach ($objects as $object) {
      $rows[] = [
        'accession_number' => $this->fieldValue($object, 'accession_number'),
        'title' => (string) $object->label(),
        'period' => $this->fieldValue($object, 'period'),
      ];
    }
    return Json::encode($rows);
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection;

/**
 * Exports collection objects with the exporter chosen by the caller.
 */
final class ObjectExportBuilder {

  public function __construct(
    private readonly ObjectExporterManager $exporters,
  ) {}

  /**
   * Returns the export of the objects, or NULL for an unknown exporter.
   *
   * @param \Drupal\Core\Entity\ContentEntityInterface[] $objects
   */
  public function build(string $exporterId, array $objects, array $configuration = []): ?string {
    if (!$this->exporters->hasDefinition($exporterId)) {
      return NULL;
    }
    return $this->exporters->createInstance($exporterId, $configuration)->export($objects);
  }

  /**
   * Returns exporter labels keyed by plugin ID, for a select list.
   *
   * @return string[]
   */
  public function options(): array {
    $options = [];
    foreach ($this->exporters->getDefinitions() as $id => $definition) {
      $options[$id] = (string) $definition['label'];
    }
    asort($options);
    return $options;
  }

}

services:
  Drupal\meridian_collection\ObjectExportBuilder:
    autowire: true

ddev drush generate plugin:manager
ddev drush generate plugin:block
ddev drush generate --help | grep plugin

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Plugin\Derivative;

use Drupal\Component\Plugin\Derivative\DeriverBase;
use Drupal\Core\Entity\EntityTypeManagerInterface;
use Drupal\Core\Plugin\Discovery\ContainerDeriverInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Creates one label sheet exporter for every gallery term.
 */
final class GalleryLabelSheetDeriver extends DeriverBase implements ContainerDeriverInterface {

  public function __construct(
    private readonly EntityTypeManagerInterface $entityTypeManager,
  ) {}

  public static function create(ContainerInterface $container, $base_plugin_id): static {
    return new static($container->get('entity_type.manager'));
  }

  public function getDerivativeDefinitions($base_plugin_definition): array {
    $this->derivatives = [];
    $terms = $this->entityTypeManager->getStorage('taxonomy_term')->loadByProperties(['vid' => 'gallery']);
    foreach ($terms as $term) {
      $definition = $base_plugin_definition;
      $definition['label'] = new TranslatableMarkup('Label sheet: @gallery', ['@gallery' => $term->label()]);
      $definition['gallery_tid'] = (int) $term->id();
      $this->derivatives[$term->id()] = $definition;
    }
    return $this->derivatives;
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Plugin\ObjectExporter;

use Drupal\Core\StringTranslation\TranslatableMarkup;
use Drupal\meridian_collection\Attribute\ObjectExporter;
use Drupal\meridian_collection\ObjectExporterBase;
use Drupal\meridian_collection\Plugin\Derivative\GalleryLabelSheetDeriver;

/**
 * Prints a label sheet for the objects of one gallery.
 */
#[ObjectExporter(
  id: 'meridian_label_sheet',
  label: new TranslatableMarkup('Label sheet'),
  extension: 'txt',
  mime_type: 'text/plain',
  deriver: GalleryLabelSheetDeriver::class,
)]
final class GalleryLabelSheet extends ObjectExporterBase {

  public function export(array $objects): string {
    $gallery = (int) $this->getDerivativeId();
    $lines = [];
    foreach ($objects as $object) {
      $terms = array_column($object->get('gallery')->getValue(), 'target_id');
      if (in_array($gallery, array_map('intval', $terms), TRUE)) {
        $lines[] = sprintf('%s  %s', $this->fieldValue($object, 'accession_number'), $object->label());
      }
    }
    return implode("\n", $lines);
  }

}

<?php

declare(strict_types=1);

namespace Drupal\meridian_collection\Form;

use Drupal\Core\Config\ConfigFactoryInterface;
use Drupal\Core\Config\TypedConfigManagerInterface;
use Drupal\Core\Form\ConfigFormBase;
use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Form\SubformState;
use Drupal\Core\Plugin\PluginFormInterface;
use Drupal\meridian_collection\ObjectExporterManager;
use Symfony\Component\DependencyInjection\ContainerInterface;

/**
 * Chooses and configures the default object exporter.
 */
final class ExportSettingsForm extends ConfigFormBase {

  public function __construct(
    ConfigFactoryInterface $config_factory,
    TypedConfigManagerInterface $typedConfigManager,
    private readonly ObjectExporterManager $exporters,
  ) {
    parent::__construct($config_factory, $typedConfigManager);
  }

  public static function create(ContainerInterface $container): static {
    return new static(
      $container->get('config.factory'),
      $container->get('config.typed'),
      $container->get('plugin.manager.meridian_object_exporter'),
    );
  }

  public function getFormId(): string {
    return 'meridian_collection_export_settings';
  }

  protected function getEditableConfigNames(): array {
    return ['meridian_collection.export'];
  }

  public function buildForm(array $form, FormStateInterface $form_state): array {
    $config = $this->config('meridian_collection.export');
    $options = [];
    foreach ($this->exporters->getDefinitions() as $id => $definition) {
      $options[$id] = (string) $definition['label'];
    }
    $selected = $form_state->getValue('exporter') ?? $config->get('exporter.id');

    $form['exporter'] = [
      '#type' => 'select',
      '#title' => $this->t('Default exporter'),
      '#options' => $options,
      '#default_value' => $selected,
      '#ajax' => [
        'callback' => '::updateSettings',
        'wrapper' => 'meridian-exporter-settings',
      ],
    ];
    $form['settings'] = [
      '#type' => 'container',
      '#tree' => TRUE,
      '#attributes' => ['id' => 'meridian-exporter-settings'],
    ];
    if ($selected && $this->exporters->hasDefinition($selected)) {
      $plugin = $this->exporters->createInstance($selected, (array) $config->get('exporter.settings'));
      if ($plugin instanceof PluginFormInterface) {
        $subform_state = SubformState::createForSubform($form['settings'], $form, $form_state);
        $form['settings'] = $plugin->buildConfigurationForm($form['settings'], $subform_state);
      }
    }
    return parent::buildForm($form, $form_state);
  }

  public function updateSettings(array $form, FormStateInterface $form_state): array {
    return $form['settings'];
  }

  public function validateForm(array &$form, FormStateInterface $form_state): void {
    parent::validateForm($form, $form_state);
    $plugin = $this->pluginFromState($form_state);
    if ($plugin instanceof PluginFormInterface) {
      $plugin->validateConfigurationForm($form['settings'], SubformState::createForSubform($form['settings'], $form, $form_state));
    }
  }

  public function submitForm(array &$form, FormStateInterface $form_state): void {
    $plugin = $this->pluginFromState($form_state);
    $settings = [];
    if ($plugin instanceof PluginFormInterface) {
      $plugin->submitConfigurationForm($form['settings'], SubformState::createForSubform($form['settings'], $form, $form_state));
      $settings = $plugin->getConfiguration();
    }
    $this->config('meridian_collection.export')
      ->set('exporter', ['id' => $form_state->getValue('exporter'), 'settings' => $settings])
      ->save();
    parent::submitForm($form, $form_state);
  }

  private function pluginFromState(FormStateInterface $form_state): ?object {
    $id = $form_state->getValue('exporter');
    return $this->exporters->hasDefinition($id) ? $this->exporters->createInstance($id) : NULL;
  }

}

# config/install/meridian_collection.export.yml
exporter:
  id: meridian_csv
  settings:
    delimiter: ','
    include_header: true

# config/schema/meridian_collection.schema.yml
meridian_collection.export:
  type: config_object
  label: 'Meridian export settings'
  mapping:
    exporter:
      type: mapping
      label: 'Default exporter'
      mapping:
        id:
          type: string
          label: 'Exporter plugin ID'
        settings:
          type: meridian_collection.exporter.settings.[%parent.id]

meridian_collection.exporter.settings.meridian_csv:
  type: mapping
  label: 'CSV exporter settings'
  mapping:
    delimiter:
      type: string
      label: 'Delimiter'
    include_header:
      type: boolean
      label: 'Include header row'

meridian_collection.exporter.settings.meridian_json:
  type: ignore
  label: 'JSON exporter settings'

// In an ExportProfile config entity: the stored keys are "exporter" (plugin ID) and "settings".
protected string $exporter = '';
protected array $settings = [];
private ?\Drupal\Core\Plugin\DefaultSingleLazyPluginCollection $collection = NULL;

public function getPluginCollections(): array {
  $this->collection ??= new \Drupal\Core\Plugin\DefaultSingleLazyPluginCollection(
    \Drupal::service('plugin.manager.meridian_object_exporter'),
    $this->exporter,
    $this->settings,
  );
  return ['settings' => $this->collection];
}