DrupalレシピのConfig Actions API完全ガイド【カスタム設定アクションの作成方法】

Use Drupal’s Config Actions API to Spice Up Your Recipes

Drupalレシピの進化は、Drupal設定を管理する強力な新しい方法を生み出しました。Config Actions APIの導入により、開発者はレシピ内で使用するカスタムconfig actionsを作成できるようになり、より動的にconfigエンティティを変更できるようになりました。これは、ピザのレシピに従いながら独自のソースに置き換えるようなもので、幅広いカスタマイズの可能性が開けます。私は自分のチームの開発作業でconfig actionsを使用し、大きな成功を収めています。

この記事では、config actionsとは何か、レシピでどのように使用するか、そしてレシピに特別なキックが必要なときに独自のものを作成する方法について探ります。

Config Actions APIとDrupalレシピの基本概念

レシピは、Drupal 10.3および11以降の新機能で、モジュールとテーマのインストールと設定のプロセスを自動化します。新しいサイトのセットアップを支援したり、既存のサイトに機能を追加したりするために適用できます。レシピの作成者は、モジュールを有効化し、権限を設定し、フィールドを設定し、コンテンツを作成するなどのYAMLベースの指示を定義します。これらは、適用されるたびに同じ予測可能な結果が得られるように再利用可能であることを意図しています。

Config actionsを使用すると、configオブジェクト全体を置き換えることなく、設定の一部を更新できます。たとえば、field.field.page.bodyでconfig action setRequiredを使用して基本ページのBodyフィールドを必須にしたり、grantPermissionを使用して指定されたロールに権限を付与したりできます。Config actionsは、configエンティティに変更を加えるYAMLから呼び出すことができるメソッドと考えてください。これらはレシピ内の多くの操作を強化します。

レシピで既存のconfig actionsを使用する

set

configエンティティの単一の値を設定する最も基本的な方法。

config:
  actions:
    pizza_newsletter.config:
      set:
        property: email_title
        value: This Week's Pizza Recipes

setMultiple

setの複数形で、このconfig actionは一度に複数の値を設定します。

config:
  actions:
    pizza_newsletter.config:
      setMultiple:
        -
          property: from_email
          value: ${from_email}
        -
          property: cc_email
          value: ${cc_email}

この例では、${from_email}と${cc_email}を入力変数として使用していますが、これについては公式レシピドキュメントで詳しく学ぶことができます。

simpleConfigUpdate

設定ファイルと同じ形式で設定プロパティを設定します。simpleConfigUpdateは将来的に非推奨になることが予想されるため、使用を最小限に抑えるようにしてください。

config:
  actions:
    pizza_newsletter.config:
      simpleConfigUpdate:
        email_title: This Week's Pizza Recipes
        from_email: ${from_email}
        cc_email: ${cc_email}

これらは、config actionsがどのように使用されるかを示すいくつかの基本的な例です。公式Drupalレシピドキュメントでアクションの完全なリストを見つけることができます。

カスタムConfig Actionプラグインの実装方法

既存のconfig actionsで必要なことを行うことができない場合、Config Action APIを使用して独自のアクションを作成できます。これを実現するには2つの方法があります：プラグインクラスまたはAction Method属性を使用する方法です。

プラグインクラスでconfig actionを作成するには、この例のようにConfigActionPluginInterfaceを実装します：

<?php
namespace Drupal\food_newsletter_module\Plugin\ConfigAction;
use Drupal\Core\Config\Action\ConfigActionPluginInterface;
use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
use Drupal\Core\Config\Action\Attribute\ConfigAction;
use Drupal\Core\Config\ConfigManagerInterface;
use Drupal\Core\Config\Entity\ConfigEntityInterface;
use Drupal\Core\StringTranslation\TranslatableMarkup;
use Symfony\Component\DependencyInjection\ContainerInterface;
/**
 * Set the title for newsletter emails.
 */
#[ConfigAction(
  id: 'setNewsletterTitle',
  admin_label: new TranslatableMarkup('Set Newsletter Title'),
  entity_types: ['newsletter'],
)]
final class SetNewsletterTitle implements ConfigActionPluginInterface, ContainerFactoryPluginInterface {
  ...
}

ここでは、newsletter configエンティティで機能するsetNewsletterTitleというconfig actionを作成しています。これはfrequency、food、chefをタイトルとして受け入れ、ニュースレターメールタイトルに使用される文字列を構築します。

config:
  actions:
    newsletter.type.pizza:
      setNewsletterTitle:
        frequency: weekly
        food: pizza
        chef: Donatello

これにより、ニュースレターのタイトルが「Weekly Pizza Newsletter by Donatello」に設定されます。

Action Method属性を使った効率的な実装

Config actionを作成するもう1つの方法は、Action Method属性を使用することです。これは、configエンティティにconfig actionに変換したいメソッドがすでにある場合に特に便利です。

<?php
namespace Drupal\food_newsletter_module;
use Drupal\Core\Config\Action\Attribute\ActionMethod;
use Drupal\Core\Config\Entity\ConfigEntityBase;
class NewsletterConfigEntity extends ConfigEntityBase {
  #[ActionMethod(adminLabel: new TranslatableMarkup('Set CC Email'), pluralize: 'setCcEmails')]
  public function setCcEmail($email): void {
    ...
  }
}

レシピでの使用例：

config:
  actions:
    pizza_newsletter.config:
      setCcEmail:
        email: Donatello@ninjaturtle.pizza

複数形の使用例：

config:
  actions:
    pizza_newsletter.config:
      setCcEmails:
        -
          email: ${cc_email_1}
        -
          email: ${cc_email_2}

プログラムでの使用例：

\Drupal::service('plugin.manager.config_action')
  ->applyAction("setCcEmail", "pizza_newsletter.config", ['email' => 'Donatello@ninjaturtle.pizza']);

実装時のベストプラクティスと今後の展望

Config Actions APIは、Drupalの設定管理ツールキットへの強力な追加機能です。レシピと組み合わせると、レシピを活用した強力なアプリケーション開発が可能になります。ベストプラクティスでは、レシピは予測可能で繰り返し可能な結果を作成することが規定されているため、レシピに貢献する際にはそれを念頭に置いてください。

あなたまたはあなたの組織がcontribモジュールを維持している場合、それらには設定エンティティ（設定フォームのようなもの）が含まれている可能性があります。これらの設定の多くは、単純なセッターよりも多くを必要とします。値の検証、文字列処理、またはその他の特殊なデータ処理が必要になることがよくあります。あなたの利益のため、また、あなたのモジュールを利用するサイトのためにも、レシピの一部として設定エンティティを正しく更新できるようにconfig actionsを追加することを検討してください。近い将来、これは標準的な実装方法になる可能性が高いため、今努力すれば、将来のあなた（とユーザー）に感謝されるでしょう。

この記事は 「Use Drupal's Config Actions API to Spice Up Your Recipes」の翻訳記事です。

カテゴリ