drupal-render

Drupal レンダー配列

基本構造

$build = [
  '#type' => 'container',
  '#attributes' => ['class' => ['my-wrapper']],
  'content' => [
    '#markup' => $this->t('Hello world'),
  ],
];

キャッシュメタデータ（常に必須）

$build['content'] = [
  '#markup' => $output,
  '#cache' => [
    'tags' => ['node:' . $node->id(), 'node_list'],
    'contexts' => ['user.permissions', 'url.query_args'],
    'max-age' => 3600,
  ],
];

キャッシュタグの規則

タグ	無効になるタイミング
node:123	ノード 123 が保存されたとき
node_list	いずれかのノードが作成または削除されたとき
user:456	ユーザー 456 が保存されたとき
taxonomy_term:789	ターム 789 が保存されたとき
config:my_module.settings	設定が保存されたとき
block_content:1	ブロックコンテンツが保存されたとき

キャッシュコンテキスト

コンテキスト	変化する条件
user	現在のユーザーの識別情報
user.permissions	ユーザーの権限
user.roles	ユーザーのロール
url	完全な URL
url.path	URL パスのみ
url.query_args	クエリー文字列
languages	現在の言語
session	セッションデータ
theme	アクティブなテーマ

マークアップの安全性

// Plain text — always safe
$build['#plain_text'] = $user_input;

// Trusted markup — use Markup class
use Drupal\Core\Render\Markup;
$build['#markup'] = Markup::create('<strong>Safe</strong>');

// User input in markup — filter first
use Drupal\Component\Utility\Xss;
$build['#markup'] = Markup::create(Xss::filter($user_input));

// Admin-level markup — allows more tags
$build['#markup'] = Markup::create(Xss::filterAdmin($html));

レンダー要素

// HTML tag
$build['heading'] = [
  '#type' => 'html_tag',
  '#tag' => 'h2',
  '#value' => $this->t('Title'),
  '#attributes' => ['class' => ['my-heading']],
];

// Link
$build['link'] = [
  '#type' => 'link',
  '#title' => $this->t('Go'),
  '#url' => Url::fromRoute('entity.node.canonical', ['node' => $nid]),
  '#attributes' => ['class' => ['button']],
];

// Entity view
$build['node'] = $this->entityTypeManager
  ->getViewBuilder('node')
  ->view($node, 'teaser');

// Inline template
$build['inline'] = [
  '#type' => 'inline_template',
  '#template' => '<div class="{{ class }}">{{ content }}</div>',
  '#context' => ['class' => 'my-class', 'content' => $content],
];

遅延ビルダー（キャッシュ不可のコンテンツ）

$build['dynamic'] = [
  '#lazy_builder' => [
    'my_module.service:buildDynamicContent',
    [$arg1, $arg2],
  ],
  '#create_placeholder' => TRUE,
];

プログラムによるレンダリング

// Inject renderer service
public function __construct(
  private readonly RendererInterface $renderer,
) {}

// Render to string
$html = $this->renderer->render($build);

// Render in isolated context (doesn't bubble cache)
$html = $this->renderer->renderInIsolation($build);