コンテンツへスキップ

PHPフック

以下に、プラグインの機能を拡張または調整するために使えるPHPフックの一覧を示します。

パス

このフィルターを使うと、ブロックフォルダーのパスを調整できます。デフォルトでは、現在有効なテーマ内のblockstudioです。また、複数のソースディレクトリを使うために新しいインスタンスを作成することもできます。

PHP
add_filter('blockstudio/path', function() {
  $path = get_stylesheet_directory() . '/blocks';
  return $path;
});

初期化

グローバル

プラグインがすべてのブロックを登録した後に実行されます。

PHP
add_action('blockstudio/init', function($blocks) {
  // All blocks have been registered
});

インスタンス

プラグインが特定のインスタンスのすべてのブロックを登録した後に実行されます。 $instanceセグメントは、wp-contentからの相対インスタンスパスです。

PHP
$instance = 'themes/my-theme/client-blocks';
add_action("blockstudio/init/$instance", function() {
  // All blocks of this instance have been registered
});

global/before

プラグインがすべてのブロックを登録する前に実行されます。

PHP
add_action('blockstudio/init/before', function() {
  // Before blocks are registered
});

global/before/$instance

プラグインが特定のインスタンスのすべてのブロックを登録する前に実行されます。

PHP
$instance = 'themes/my-theme/client-blocks';
add_action("blockstudio/init/before/$instance", function() {
  // Before blocks of this instance are registered
});

ブロック

レンダリング

このフィルターを使うと、ブロックのレンダリング前に出力を調整できます。

PHP
add_filter('blockstudio/blocks/render', function($content, $block, $attributes) {
  // Modify the block content
  return $content;
}, 10, 3);

メタデータ

このフィルターを使うと、block.jsonファイルが登録される前に、そのデータを調整できます。

PHP
add_filter('blockstudio/blocks/meta', function($meta, $block) {
  if (str_starts_with($block['name'], 'marketing')) {
    $meta['icon'] = 'megaphone';
  }
  return $meta;
}, 10, 2);

上記のコードは、marketingで始まるすべてのブロックのアイコンを変更します。

条件

このフィルターを使うと、ブロック内で使用できるカスタム条件を追加できます。各条件タイプは、エディターが条件のvalueと比較する値に対応します。カスタム条件を参照してください。

PHP
add_filter('blockstudio/blocks/conditions', function($conditions) {
  $conditions['myCustomCondition'] = 'expected';
  return $conditions;
});

属性

このフィルターは、ブロックの登録前に1つのフィールド定義を調整します。 フィルター後の定義は、エディターのコントロールとレンダリング時の値の検証に使用されます。 詳しくはフィルタリングをご覧ください。

PHP
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
  // Modify this field definition before registration.
  return $attribute;
}, 10, 2);

attributes/render

このフィルターは、ブロックテンプレートに渡す前に、フィールドの値を調整します。フィールドごとに1回実行され、3つの引数を受け取ります: $value(解決済みの値)、$key(フィールドキー。$aで使用されるもの)、および$block(テンプレートが$blockまたは$bとして受け取るブロックデータ配列)。受け入れる引数を3つとして登録してください。詳しくはフィルタリングを参照してください。

PHP
add_filter('blockstudio/blocks/attributes/render', function($value, $key, $block) {
  // Modify the value of one field before rendering.
  return $value;
}, 10, 3);

attributes/files/sizes

filesフィールドでは、各画像とともにsizes配列が返されます。この配列には、URL、fullの幅と高さ、および登録されているすべての画像サイズの幅と高さが含まれます。たとえば、$image['sizes']['thumbnail']や$image['sizes']['thumbnail-width']です。サイズごとに画像あたりwp_get_attachment_image_src()呼び出しが1回行われるため、そのフィルターは引き続き適用されます。sizesを読み取らないテンプレートでは、リストを削除したり短くしたりできます。

PHP
add_filter('blockstudio/blocks/attributes/files/sizes', function($sizes, $id, $size) {
  // Keep only two sizes. Return an empty array to skip them, `sizes` is then null.
  return ['full', 'large'];
}, 10, 3);

$sizesはサイズ名のリストで、fullが先頭にあります(中間サイズが登録されていない場合は空です)。$idは添付ファイルID、$sizeは値のurlに要求されたサイズです。このフィルターは、リクエスト内のすべてのfiles値のsizes配列を変更します。フィルターを使用しない場合、配列は変更されません。

サイズ名を文字列として返します。無効な項目は無視され、重複する名前は1回だけ処理されます。配列以外の戻り値の場合、サイズはスキップされます。要求されたurlやその他の添付ファイルのプロパティは変更されません。returnFormat: "url"を持つfilesフィールドではサイズマップが作成されないため、このフックは実行されません。

attributes/validate

明示的なbs_validate_block()呼び出しの結果を調整します。たとえば、カスタムのレンダーフィルターが保存済みの参照を解決する場合に使います。これによって、保存時やレンダリング時の自動検証が有効になることはありません。

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  return $findings;
}, 10, 3);

検出結果のリストを返します。ブロックにBlockstudioフィールドや一致する拡張機能(null)がない場合、このフィルターは呼び出されません。

attributes/schema

bs_block_schema()が返すJSON Schema を調整します。たとえば、カスタムレンダーフィルターが保存済みの参照を解決する場合に使用します。

PHP
add_filter('blockstudio/blocks/attributes/schema', function($schema, $name) {
  return $schema;
}, 10, 2);

Schema 配列を返します。ブロックにBlockstudioフィールドまたは一致する拡張機能(null)がない場合、このフィルターは呼び出されません。

attributes/populate

このフィルターを使うと、checkbox、select、またはradioフィールドの選択肢にカスタムデータを追加できます。詳しくは選択肢の設定をご覧ください。

このフィルターは、"populate": {"type": "custom", "custom": "myCustomOptions"}で使用される名前をキーとした、すべてのカスタムデータセットの配列を引数として受け取ります。

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['myCustomOptions'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

components/use_block_props/render

このフィルターを使うと、useBlockPropsコンテンツの出力を調整できます。

すべてのコンポーネントフィルター(use_block_props、inner_blocks、rich_text)は、最後の引数としてブロックを受け取ります。$blockは、レンダリング対象のブロックに登録されたWP_Block_Typeです。そのため、$block->nameはブロック名を指し、たとえばacme/heroです。

$propsはHTML属性の文字列であり、配列ではありません。フロントエンドでは、get_block_wrapper_attributes()の結果で、たとえばclass="wp-block-acme-hero my-class"です。エディターでは、要素のclass属性です。文字列を返してください。エディターでは、返された文字列のclass属性のみが適用されます。

PHP
add_filter('blockstudio/blocks/components/use_block_props/render', function($props, $block) {
  if ($block->name !== 'acme/hero') {
    return $props;
  }

  return str_replace('class="', 'class="my-custom-class ', $props);
}, 10, 2);

components/inner_blocks/render

このフィルターを使うと、<InnerBlocks />コンテンツの出力を調整できます。

PHP
add_filter('blockstudio/blocks/components/inner_blocks/render', function($content, $block) {
  return '<div class="inner-wrapper">' . $content . '</div>';
}, 10, 2);

components/inner_blocks/frontend/wrap

このフィルターを使うと、フロントエンドから<InnerBlocks />ラッパーを削除できます。

PHP
add_filter('blockstudio/blocks/components/inner_blocks/frontend/wrap', function($wrap, $block) {
  return false; // Remove wrapper
}, 10, 2);

components/rich_text/render

このフィルターを使うと、<RichText />コンテンツの出力を調整できます。属性の値とブロックを受け取ります。

PHP
add_filter('blockstudio/blocks/components/rich_text/render', function($content, $block) {
  return wp_kses_post($content);
}, 10, 2);

ブロックタグ

blockstudio/block_tags/builders

このフィルターは、ブロックタグやblockstudio/parser/element_mappingで選択されたカスタムブロックが使う、ブロック配列ビルダーを登録します。各ビルダーは、解析済みの属性と未加工の内部コンテンツを受け取ります。

PHP
add_filter('blockstudio/block_tags/builders', function($builders, $parser) {
  $builders['theme/paragraph'] = function(array $attributes, string $inner) {
    $attributes['content'] = trim($inner);

    return [
      'blockName' => 'theme/paragraph',
      'attrs' => [
        'blockstudio' => [
          'attributes' => $attributes,
        ],
      ],
      'innerBlocks' => [],
      'innerHTML' => '',
      'innerContent' => [],
    ];
  };

  return $builders;
}, 10, 2);

互換性のあるblockstudio/block_tags/renderersフィルターとblockstudio/parser/renderersフィルターは、このフックの後に実行され、同じブロック名を上書きできます。

blockstudio/block_tags/tag_aliases

このフィルターを使うと、実際のブロック名に解決される、独自のハイフン区切りの記述用タグを登録できます。これは、テーマで簡潔なプロジェクト固有のタグを使いながら、標準のHTMLブロックやコアブロックを引き続きレンダリングしたい場合に便利です。解決前に未加工のBlockstudioへのフォールバックが行われます。

PHP
add_filter('blockstudio/block_tags/tag_aliases', function($aliases) {
  $aliases['theme-button'] = 'bsui/button';
  $aliases['theme-card'] = 'theme/card';

  return $aliases;
});
HTML
<theme-button href="/download" label="Download" />
<theme-card title="Fast authoring">
  <p>Children are parsed as nested blocks.</p>
</theme-card>

blockstudio/block_tags/prefixes

このフィルターを使うと、プレフィックスの短縮形を1つ以上のブロック名前空間に対応付けられます。キーは、ハイフンを含まない小文字のプレフィックスです。値には、名前空間の文字列または順序付きの名前空間リストを指定できます。

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

<theme-card>はtheme-components/cardに解決されます。<theme-button>はまずtheme-components/buttonを試し、その後bsui/buttonにフォールバックします。同じタグでは明示的なblockstudio/block_tags/tag_aliasesエントリーが優先され、解決されないプレフィックス付きタグは変更されません。

プレフィックスは組み合わせて使えます。プレフィックス付きタグが直接解決されず、そのスラッグ自体が登録済みのプレフィックスタグである場合、解決処理が再帰的に行われます。theme => ['theme-components']とui => ['bsui']がある場合、<theme-ui-input>はuiプレフィックスにフォールバックして、bsui/inputに解決されます。登録済みのプレフィックスタグとエイリアスタグは、ページコンテンツだけでなく、ブロックテンプレートの出力でもレンダリングされます。

設定

パス

このフィルターを使うと、blockstudio.jsonファイルのパスを調整できます。デフォルトでは、現在有効なテーマ内のblockstudio.jsonです。

PHP
add_filter('blockstudio/settings/path', function() {
  return get_stylesheet_directory() . '/config/blockstudio.json';
});

users/ids

このフィルターを使うと、特定のユーザーIDに対してエディターを有効にできます。

PHP
add_filter('blockstudio/settings/users/ids', function() {
  return [1];
});

users/roles

このフィルターを使うと、特定のユーザーロールに対してエディターを有効にできます。

PHP
add_filter('blockstudio/settings/users/roles', function() {
  return ['administrator', 'editor'];
});

assets/enqueue

このフィルターを使うと、フロントエンドとエディターでのアセットの読み込みを有効または無効にできます。

PHP
add_filter('blockstudio/settings/assets/enqueue', function() {
  return false;
});

assets/reset/enabled

このフィルターを使うと、WordPressコアブロックのスタイルとエディターのユーティリティレイアウトリセットの削除を有効または無効にできます。

PHP
add_filter('blockstudio/settings/assets/reset/enabled', function() {
  return true;
});

assets/reset/full_width

このフィルターを使うと、全幅編集を使用する投稿タイプを制御できます。

PHP
add_filter('blockstudio/settings/assets/reset/full_width', function() {
  return ['page'];
});

assets/minify/css

このフィルターを使うと、CSSの圧縮を有効または無効にできます。

PHP
add_filter('blockstudio/settings/assets/minify/css', function() {
  return true;
});

assets/minify/js

このフィルターを使うと、JSの圧縮を有効または無効にできます。

PHP
add_filter('blockstudio/settings/assets/minify/js', function() {
  return true;
});

assets/process/scss

このフィルターを使うと、.cssファイル内のSCSSの処理を有効または無効にできます。

PHP
add_filter('blockstudio/settings/assets/process/scss', function() {
  return true;
});

assets/process/scss_files

このフィルターを使うと、.scssファイルからCSSへの変換処理を有効または無効にできます。

PHP
add_filter('blockstudio/settings/assets/process/scss_files', function() {
  return true;
});

assets/output

このフィルターを使うと、コンパイル済みブロックアセットの書き出し先を制御できます。

PHP
add_filter('blockstudio/settings/assets/output', function() {
  return 'cache';
});

assets/inline_limit

ページごとにインライン化する、外部ブロックCSSのバイト数を制御するフィルターです。

PHP
add_filter('blockstudio/settings/assets/inline_limit', function() {
  return 40000;
});

cache/enabled

このフィルターを使うと、Blockstudioファイルベースのランタイムおよびエディター用アセットのキャッシュをすべて有効または無効にできます。

PHP
add_filter('blockstudio/settings/cache/enabled', function() {
  return false;
});

cache/path

このフィルターを使うと、Blockstudioファイルベースのキャッシュディレクトリを変更できます。

PHP
add_filter('blockstudio/settings/cache/path', function() {
  return 'cache/blockstudio';
});

cache/namespace_grace

このフィルターを使うと、廃止されたキャッシュ名前空間が削除されるまでの保持期間を変更できます。

PHP
add_filter('blockstudio/settings/cache/namespace_grace', function() {
  return 777600;
});

githooks/commit

このフィルターは、Blockstudioが管理するPHPStanのコミットフックが有効かどうかを示します。

PHP
add_filter('blockstudio/settings/githooks/commit', function() {
  return true;
});

content/enabled

このフィルターを使うと、コンテンツ同期を有効または無効にできます。

PHP
add_filter('blockstudio/settings/content/enabled', function() {
  return true;
});

content/id

このフィルターを使うと、コンテンツ同期の所有権を示す名前空間を設定できます。

PHP
add_filter('blockstudio/settings/content/id', function() {
  return 'docs';
});

content/path

このフィルターを使うと、コンテンツ同期ファイルのディレクトリを設定できます。

PHP
add_filter('blockstudio/settings/content/path', function() {
  return 'content';
});

content/include_page_sync_managed

このフィルターを使うと、ページ同期が管理する投稿を含めるか除外するかを設定できます。

PHP
add_filter('blockstudio/settings/content/include_page_sync_managed', function() {
  return false;
});

content/authors

このフィルターを使うと、コンテンツ同期での投稿者の扱いを設定できます。

PHP
add_filter('blockstudio/settings/content/authors', function() {
  return 'ignore';
});

content/post_types

このフィルターを使うと、コンテンツ同期で許可する投稿タイプのリストを設定できます。

PHP
add_filter('blockstudio/settings/content/post_types', function() {
  return ['team_member'];
});

content/taxonomies

このフィルターを使うと、コンテンツ同期で許可するタクソノミーのリストを設定できます。

PHP
add_filter('blockstudio/settings/content/taxonomies', function() {
  return ['category', 'post_tag'];
});

content/media

このフィルターを使うと、コンテンツ同期でのメディアの扱いを設定できます。

PHP
add_filter('blockstudio/settings/content/media', function() {
  return 'manifest';
});

tailwind/enabled

このフィルターを使うと、Tailwindを有効または無効にできます。

PHP
add_filter('blockstudio/settings/tailwind/enabled', function() {
  return true;
});

tailwind/config

このフィルターを使うと、カスタムのTailwind CSS設定を追加できます。

PHP
add_filter('blockstudio/settings/tailwind/config', function() {
  return '@theme { --color-primary: pink; }';
});

tailwind/output

このフィルターを使うと、Tailwind CSSをインラインで出力するか、リンクして出力するかを選択できます。

PHP
add_filter('blockstudio/settings/tailwind/output', function() {
  return 'link';
});

ui/enabled

このフィルターを使うと、同梱のUIコンポーネントを有効または無効にできます。

PHP
add_filter('blockstudio/settings/ui/enabled', function() {
  return true;
});

editor/format_on_save

このフィルターを使うと、保存時のコード整形を有効または無効にできます。

PHP
add_filter('blockstudio/settings/editor/format_on_save', function() {
  return true;
});

editor/assets

このフィルターを使うと、エディターで追加のアセットを読み込めます。

PHP
add_filter('blockstudio/settings/editor/assets', function() {
  return ['my-stylesheet', 'another-stylesheet'];
});

editor/markup

このフィルターを使うと、エディターの末尾に追加のマークアップを挿入できます。

PHP
add_filter('blockstudio/settings/editor/markup', function() {
  return '<style>body { background: black; }</style>';
});

block_editor/disable_loading

このフィルターを使うと、ブロックエディター内でのブロックの読み込みを無効にできます。

PHP
add_filter('blockstudio/settings/block_editor/disable_loading', function() {
  return true;
});

block_editor/enhance

このフィルターを使うと、フォーカス時のスタイルの整理やホバー・選択時のアウトラインなど、Blockstudioエディターの操作性を高める機能を有効にできます。

PHP
add_filter('blockstudio/settings/block_editor/enhance', function() {
  return true;
});

block_editor/css_classes

このフィルターを使うと、クラスフィールドで選択できるクラスを定義したスタイルシートを追加できます。

PHP
add_filter('blockstudio/settings/block_editor/css_classes', function() {
  return ['my-stylesheet', 'another-stylesheet'];
});

block_editor/css_variables

このフィルターを使うと、コードフィールドの自動補完で使用できるCSS変数を定義したスタイルシートを追加できます。

PHP
add_filter('blockstudio/settings/block_editor/css_variables', function() {
  return ['my-stylesheet', 'another-stylesheet'];
});

block_editor/blocks/allow

このフィルターを使うと、挿入ツールで使用できるブロック名を制御できます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/allow', function() {
  return ['core/*', 'acf/*', 'my-theme/*'];
});

block_editor/blocks/deny

このフィルターを使うと、挿入ツールからブロック名を削除できます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/deny', function() {
  return ['core/embed', 'core/freeform'];
});

block_editor/blocks/directory

このフィルターを使うと、エディターでWordPressブロックディレクトリのアセットを有効または無効にできます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/directory', function() {
  return false;
});

block_editor/blocks/categories/allow

このフィルターを使うと、利用可能な状態にするブロックカテゴリーのスラッグを制御できます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/categories/allow', function() {
  return ['text', 'media', 'design'];
});

block_editor/blocks/categories/deny

このフィルターを使うと、挿入ツールからブロックカテゴリーのスラッグを削除できます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/categories/deny', function() {
  return ['embed'];
});

block_editor/blocks/categories/rename

このフィルターを使うと、スラッグを指定してブロックカテゴリーのラベルを変更できます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/categories/rename', function() {
  return [
    'text' => 'Writing',
    'design' => 'Layout'
  ];
});

block_editor/blocks/categories/order

このフィルターを使うと、挿入ツールでのブロックカテゴリーのスラッグの順序を指定できます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/categories/order', function() {
  return ['my-theme', 'text', 'media'];
});

block_editor/blocks/styles/deny

このフィルターを使うと、ブロック名を指定して、PHPが登録したブロックスタイルの登録を解除できます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/styles/deny', function() {
  return [
    'my-theme/card' => ['outline'],
    'my-theme/media' => ['framed']
  ];
});

block_editor/blocks/legacy_widgets/hide

このフィルターを使うと、レガシーウィジェットブロックから追加のレガシーウィジェットを非表示にできます。

PHP
add_filter('blockstudio/settings/block_editor/blocks/legacy_widgets/hide', function() {
  return ['archives', 'calendar'];
});

block_editor/patterns/core

このフィルターを使うと、WordPressコアブロックパターンを有効または無効にできます。

PHP
add_filter('blockstudio/settings/block_editor/patterns/core', function() {
  return false;
});

block_editor/patterns/remote

このフィルターを使うと、WordPressパターンディレクトリのリモートパターンを有効または無効にできます。

PHP
add_filter('blockstudio/settings/block_editor/patterns/remote', function() {
  return false;
});

block_editor/patterns/theme

このフィルターを使うと、テーマが提供するブロックパターンを有効または無効にできます。

PHP
add_filter('blockstudio/settings/block_editor/patterns/theme', function() {
  return false;
});

block_editor/patterns/blockstudio

このフィルターを使うと、Blockstudioのファイルベースのパターンを有効または無効にできます。

PHP
add_filter('blockstudio/settings/block_editor/patterns/blockstudio', function() {
  return false;
});

block_editor/patterns/categories/allow

このフィルターを使うと、利用可能な状態にするパターンカテゴリーのスラッグを制御できます。

PHP
add_filter('blockstudio/settings/block_editor/patterns/categories/allow', function() {
  return ['featured', 'buttons', 'columns'];
});

block_editor/patterns/categories/deny

このフィルターを使うと、パターン挿入ツールからパターンカテゴリーのスラッグを削除できます。

PHP
add_filter('blockstudio/settings/block_editor/patterns/categories/deny', function() {
  return ['gallery'];
});

block_editor/patterns/categories/rename

このフィルターを使うと、スラッグを指定してパターンカテゴリーのラベルを変更できます。

PHP
add_filter('blockstudio/settings/block_editor/patterns/categories/rename', function() {
  return [
    'featured' => 'Featured Layouts'
  ];
});

block_editor/patterns/categories/order

このフィルターを使うと、挿入ツールでのパターンカテゴリーのスラッグの順序を指定できます。

PHP
add_filter('blockstudio/settings/block_editor/patterns/categories/order', function() {
  return ['featured', 'buttons'];
});

block_editor/media/openverse

このフィルターを使うと、ブロックエディターのメディア挿入ツールでOpenverseメディアカテゴリーを有効または無効にできます。

PHP
add_filter('blockstudio/settings/block_editor/media/openverse', function() {
  return false;
});

block_editor/media/image_sizes/allow

このフィルターを使うと、エディターのメディアコントロールで使用できる画像サイズ名を制御できます。

PHP
add_filter('blockstudio/settings/block_editor/media/image_sizes/allow', function() {
  return ['thumbnail', 'large'];
});

block_editor/media/image_sizes/deny

このフィルターを使うと、エディターのメディアコントロールから画像サイズ名を削除できます。

PHP
add_filter('blockstudio/settings/block_editor/media/image_sizes/deny', function() {
  return ['medium_large'];
});

ai/enable_context_generation

このフィルターを使うと、LLMツール連携用のコンテキストファイル生成を有効または無効にできます。有効にすると、最新のブロックデータ、現在のインストール環境のBlockstudio設定、関連するすべてのスキーマ、Blockstudioドキュメントを1つのソースにまとめ、AI開発ツールで利用できるようにします。

PHP
add_filter('blockstudio/settings/ai/enable_context_generation', function() {
  return true;
});

block_tags/enabled

このフィルターを使うと、ページレベルのブロックタグのレンダリングを有効または無効にできます。

PHP
add_filter('blockstudio/settings/block_tags/enabled', function() {
  return true;
});

block_tags/prefixes

このフィルターを使うと、ブロックタグ用のプレフィックスと名前空間の短縮形を登録できます。

PHP
add_filter('blockstudio/settings/block_tags/prefixes', function() {
  return [
    'theme' => ['theme-components', 'bsui']
  ];
});

dev/grab/enabled

このフィルターを使うと、要素ピッカーを有効または無効にできます。

PHP
add_filter('blockstudio/settings/dev/grab/enabled', function() {
  return false;
});

dev/perf

このフィルターを使うと、パフォーマンスプロファイラーを有効または無効にできます。

PHP
add_filter('blockstudio/settings/dev/perf', function() {
  return false;
});

dev/canvas/enabled

このフィルターを使うと、キャンバスを有効または無効にできます。

PHP
add_filter('blockstudio/settings/dev/canvas/enabled', function() {
  return false;
});

dev/canvas/admin_bar

このフィルターを使うと、キャンバス上のWordPress管理バーを表示または非表示にできます。

PHP
add_filter('blockstudio/settings/dev/canvas/admin_bar', function() {
  return true;
});

WPML

blockstudio/wpml/config/label

wp bs wpml configが書き込む各キーのラベルをフィルタリングします。コンテキスト配列については、ラベルの変更を参照してください。

PHP
add_filter('blockstudio/wpml/config/label', function($label, $context) {
  return str_replace(' (optional)', '', $label);
}, 10, 2);

キャンバス

blockstudio/canvas/inventory

このフィルターは、Canvasが選択項目について報告するインベントリーを調整します。コールバックはインベントリーDTO、元の選択項目、呼び出し時に渡されたオプションを受け取ります。

PHP
add_filter('blockstudio/canvas/inventory', function(array $result, array $selection, array $options) {
  return $result;
}, 10, 3);

blockstudio/canvas/documents

このフィルターは、Canvasが返すレンダリング済みドキュメントを調整します。引数はインベントリーフィルターと同じ3つです。

blockstudio/canvas/item_loaded

このアクションは、インベントリーレコードの読み込みごとに1回実行され、インベントリータイプ、正規レコードID、正規化済みレコードを受け取ります。

blockstudio/canvas/source_compiled

このアクションは、Canvas用のソースファイルがコンパイルされた後に実行され、選択されたソースパスと正規ソースレコードを受け取ります。

同梱のUI

blockstudio/ui/directories

このフィルターは、同梱のUIコンポーネントを検索するディレクトリを調整します。

blockstudio/ui/inventory

このフィルターは公開UIファミリーの一覧を調整します。

blockstudio/ui/examples

このフィルターはUIのサンプルレコードを調整します。サンプルと、その元になった公開UI一覧を受け取ります。

トポロジー

blockstudio/blocks/topology_refreshed

ブロックのトポロジーが再構築された後に、このアクションが発火します。

blockstudio/pages/topology_refreshed

ページのトポロジーが再構築された後に、このアクションが発火します。

blockstudio/pages/layout_error

ページレイアウトのレンダリングに失敗したとき、エラーを黙って無視せずにこのアクションが発火します。

ランタイム

blockstudio/runtime/initialized

ランタイムが設定を解決した後、一度だけこのアクションが発火します。

blockstudio/runtime/changed

解決済みランタイムの識別情報が変わると、このアクションが発火します。これにより、キャッシュの名前空間と静的プリレンダーの状態が切り替わります。

blockstudio/performance/default_config

このフィルターは、プロジェクト独自のblockstudio.json値を重ねる前に、パフォーマンスのデフォルト値を調整します。

コンテンツ

blockstudio/content/orphan_action

このフィルターは、コンテンツ同期でソースがなくなったレコードをどう扱うかを決定します。

Bootstrap

blockstudio/url

このフィルターは、Blockstudioのエディター用および管理画面用アセットに使う公開URLを変更します。Composerとの連携では、Blockstudioのautoloadファイルを読み込む前に登録する必要があります。第2引数はパッケージの物理ディレクトリです。

PHP
add_filter(
  'blockstudio/url',
  function(string $url, string $directory) {
    return get_stylesheet_directory_uri() . '/vendor/blockstudio/blockstudio/';
  },
  10,
  2
);

ランタイムキャッシュ

blockstudio/cache/dir

このフィルターは、ランタイム、エディター用アセット、その他のキャッシュスコープが追加される前に、解決済みのキャッシュベースディレクトリを受け取ります。

PHP
add_filter('blockstudio/cache/dir', function(string $directory) {
  return WP_CONTENT_DIR . '/cache/blockstudio';
});

blockstudio/cache/context

このフィルターは、キャッシュの識別情報にシリアライズ可能なランタイムバリアントを追加します。同じ検出元から異なる論理的な一覧が選ばれる場合に使用します。

PHP
add_filter('blockstudio/cache/context', function($context, string $scope) {
  return [
    'preview' => get_query_var('preview_id'),
    'site' => get_current_blog_id(),
  ];
}, 10, 2);

blockstudio/cache/site_key

このフィルターは、独自のテナント境界を持つホスト向けに、ネットワーク/ブログのディレクトリ識別情報を変更します。返される値は使用前にサニタイズされます。

PHP
add_filter(
  'blockstudio/cache/site_key',
  function(string $key, int $networkId, int $blogId) {
    return sprintf('tenant-%d-%d', $networkId, $blogId);
  },
  10,
  3
);

blockstudio/runtime/identity

このフィルターは、ランタイムスコープ内のすべてのオブジェクトに影響するホスト情報を追加します。アイテム固有のソースフィンガープリントは、代わりにそれを管理するAPIから明示的な依存関係として渡してください。

PHP
add_filter(
  'blockstudio/runtime/identity',
  function(array $identity, string $scope) {
    $identity['deployment'] = getenv('RELEASE_SHA') ?: 'local';
    return $identity;
  },
  10,
  2
);

blockstudio/cache/watch_debounce

検証済みのファイル監視スナップショットを、次のファイルシステムのstat処理なしで再利用できる秒数をフィルターします。デフォルトはローカル環境と開発環境では0、それ以外では20です。

PHP
add_filter('blockstudio/cache/watch_debounce', function() {
  return 30;
});

blockstudio/cache/build_wait_budget

別のビルダーがランタイムキャッシュまたは選択肢一覧の更新を公開するまで、リクエストが待機する時間をミリ秒単位でフィルターします。待機時間を超えると処理は縮退します。デフォルトは構造の再構築では5000、選択肢の更新では4000です。

PHP
add_filter('blockstudio/cache/build_wait_budget', function() {
  return 2000;
});

blockstudio/cache/populate_debounce

コンテンツ、ターム、ユーザー、またはメタデータへの連続した書き込みを、選択肢一覧の1回の更新にまとめる秒数をフィルターします。静止期間後の最初の書き込みではすぐに更新され、連続書き込みの最後の内容はウィンドウ経過後に反映されます。デフォルトは30です。0を返すと、書き込みごとに更新します。

PHP
add_filter('blockstudio/cache/populate_debounce', function() {
  return 120;
});

blockstudio/cache/populate_ignored_meta_keys

書き込み時に選択肢の再生成が行われないメタキーをフィルタリングします。デフォルトでは、編集やログインの記録としてWordPressが書き込む次のキーが対象です。投稿が開いている間、エディターとHeartbeatによって更新される_edit_lock、すでに更新処理が行われる投稿の保存時に書き込まれる_edit_last、ログインとログアウト時に書き込まれるsession_tokensです。頻繁に変更されても選択肢の取得クエリーに影響しないキーを追加してください。

PHP
add_filter('blockstudio/cache/populate_ignored_meta_keys', function(array $keys) {
  $keys[] = '_my_view_counter';
  return $keys;
});

blockstudio/cache/max_files_per_scope

各ランタイムキャッシュスコープに保持する公開済みペイロードの数をフィルターします。

PHP
add_filter('blockstudio/cache/max_files_per_scope', function($maximum, $scope) {
  return $scope === 'runtime' ? 50 : $maximum;
}, 10, 2);

blockstudio/cache/compress

キャッシュのペイロードに、通常のPHP配列ではなく、圧縮したシリアライズデータを使うかどうかをフィルタリングします。デフォルトでは、1 MiB以下のペイロードに限り、保存先をキャッシュできる有効なOPcache共有メモリがある場合に、通常の形式が使われます。それ以外のプロセス、除外されたファイル、大きなペイロードには圧縮が使われます。

PHP
add_filter('blockstudio/cache/compress', function($compress, $scope) {
  return $scope === 'runtime' ? false : $compress;
}, 10, 2);

falseを返すと、サイズ制限も無効になります。opcache.enable_cliなしでWP-CLIがファイルをウォームアップすると、OPcacheが有効なウェブワーカーで役立つことがありますが、OPcacheを使わない各読み取り処理は生成された配列を解析します。追加のメモリコストを許容できる場合を除き、大きな共有ペイロードには圧縮を使ってください。デフォルトの保護策については、キャッシュペイロードの形式を参照してください。

blockstudio/cache/protected_paths

キャッシュパスの保持処理で削除してはならないパスです。Blockstudioは、インストール済みの早期配信マップが参照するすべてのファイルを登録します。

PHP
add_filter('blockstudio/cache/protected_paths', function(array $paths, string $scope, string $directory) {
  if ('static-prerender' === $scope) {
    $paths[] = $directory . '/pinned.html';
  }
  return $paths;
}, 10, 3);

blockstudio/cache/outcome

このアクションは、共有キャッシュスコープと、hit、build、miss-stale、stale-last-good、write-failureなどの結果を報告します。

PHP
add_action('blockstudio/cache/outcome', function(string $scope, string $reason) {
  my_metrics()->increment("blockstudio.cache.{$scope}.{$reason}");
}, 10, 2);

blockstudio/static_prerender/request_bypass

このフィルターは、匿名アクセスの安全性に関する最終判断と、サーバーおよびCookieの入力を受け取ります。trueを返すと、静的配信と生成を常にバイパスします。

PHP
add_filter(
  'blockstudio/static_prerender/request_bypass',
  function(bool $bypass, array $server, array $cookies) {
    return $bypass || isset($cookies['commerce_session']);
  },
  10,
  3
);

blockstudio/static_prerender/public_urls

このフィルターは、スケジュール実行されるウォーマーと明示的なグラフツールが使用する、公開URLの全一覧を提供または調整します。

PHP
add_filter('blockstudio/static_prerender/public_urls', function(array $urls) {
  $urls[] = home_url('/custom-route/');
  return array_values(array_unique($urls));
});

フィルターが返す値は最終的な一覧ではありません。結果はキャッシュ可能性のチェックに渡され、設定済みの動的パス、およびデフォルトでバイパスされる/wp-admin、/wp-json、/wp-login.php、/xmlrpc.php、/feed/を含むパス、さらにサイトのホームパス(デフォルトは/search/)にある検索ベース配下の検索結果は除外されます。そのため、追加したURLが警告なしに破棄されることがあります。ビルド済みの一覧に期待したルートがない場合は、フィルターが実行されなかったと判断する前に、これらのルールに該当しないか確認してください。

blockstudio/static_prerender/render_internal

このフィルターは、プロセス内でのオプションのバッチ転送を実装します。正規化された結果配列を返すか、値を変更せずに返すと、レンダラーは設定済みのHTTPフォールバックを使用します。結果にはhtmlが含まれ、status、dependencies、virtualHashes、headersを任意で含められます。performance.staticPrerender.replayHeadersで指定されたヘッダーはドキュメントとともに保存されます。

PHP
add_filter(
  'blockstudio/static_prerender/render_internal',
  function($result, string $url, array $options) {
    return my_static_renderer()->render($url, $options);
  },
  10,
  3
);

blockstudio/static_prerender/cacheable_html

このフィルターは、Blockstudioが出力全体を含むHTMLドキュメントであり、no-cacheマーカーがなく、観測されたレスポンスステータスが成功であることを確認した後に、最終判断を行います。第3引数は観測されたステータスです。ステータスが宣言されていない場合はnullです。

PHP
add_filter('blockstudio/static_prerender/cacheable_html', function(bool $cacheable, string $html, ?int $status) {
  return $cacheable && !str_contains($html, 'data-personalized');
}, 10, 3);

blockstudio/static_prerender/outcome

このアクションは、ヒット、ミス、書き込み、グラフの書き込み、古いエントリー、失敗など、静的プリレンダーの結果を報告します。

PHP
add_action('blockstudio/static_prerender/outcome', function(string $reason) {
  my_metrics()->increment("blockstudio.prerender.{$reason}");
});

blockstudio/tailwind/cache_max_files

コンパイル済みTailwind CSSエントリーの最大数をフィルターします。デフォルトは1000です。

PHP
add_filter('blockstudio/tailwind/cache_max_files', function() {
  return 1500;
});

blockstudio/tailwind/cache_max_age

コンパイル済みTailwind CSSエントリーの最大保持期間を秒単位でフィルターします。デフォルトは30日、最小は1時間です。

PHP
add_filter('blockstudio/tailwind/cache_max_age', function() {
  return 14 * DAY_IN_SECONDS;
});

管理画面

有効化

このフィルターでは、ツール > BlockstudioにあるBlockstudioの管理画面を有効または無効にできます。

PHP
add_filter('blockstudio/admin/enabled', function() {
  return false;
});

アセット

editor/canvas/body_class

アセットリセットが有効な場合、このフィルターはブロックエディターのキャンバスにコピーされる、サニタイズ済みのフロントエンドのbodyクラスを調整します。

PHP
add_filter('blockstudio/editor/canvas/body_class', function(array $classes) {
  return array_values(array_diff($classes, ['logged-in']));
});

有効化

このフィルターでは、特定の種類のアセット処理とキュー登録を無効にできます。

PHP
add_filter('blockstudio/assets/enable', function($enable, $type, $block) {
  if ($type === 'css' && $block['name'] === 'my/block') {
    return false;
  }
  return $enable;
}, 10, 3);

無効化

このフィルターでは、IDを指定して特定のアセットを無効にできます。返される配列内のIDに一致するアセットは、フロントエンドにレンダリングされません。

PHP
add_filter('blockstudio/assets/disable', function($disabled) {
  $disabled[] = 'my-block-style';
  return $disabled;
});

process/scss/import_paths

このフィルターでは、SCSSコンパイラーの@import文にパスを追加できます。

PHP
add_filter('blockstudio/assets/process/scss/import_paths', function($paths) {
  $paths[] = get_stylesheet_directory() . '/scss';
  return $paths;
});

process/scss/prelude

このフィルターでは、各SCSSファイルのコンパイル前に、共通のSassコードを先頭に追加できます。

PHP
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);

process/css/content

このフィルターでは、CSSファイルがコンパイルされる前に、その内容を調整できます。

PHP
add_filter('blockstudio/assets/process/css/content', function($content, $block) {
  return str_replace('old-class', 'new-class', $content);
}, 10, 2);

process/js/content

このフィルターでは、JSファイルがコンパイルされる前に、その内容を調整できます。

PHP
add_filter('blockstudio/assets/process/js/content', function($content, $block) {
  return $content;
}, 10, 2);

バッファー

有効化

Blockstudioはフロントエンドのレスポンスをバッファリングします。これにより、body内にレンダリングされたブロックのstyleタグとscriptタグをheadとfooterに移動し、Tailwindがドキュメント全体をスキャンできるようにします。バッファリングでは、フロントエンドのリクエストごとにドキュメント全体を保持してスキャンします。Blockstudioブロックのアセットをレンダリングせず、Tailwindも使用しないサイトでは、falseを返して両方をスキップできます。

PHP
add_filter('blockstudio/buffer/enabled', '__return_false');

管理画面とカスタマイザーのプレビューでもバッファリングは無効です。wp_enqueue_scripts以降でbs_is_buffering()を呼び出すと、現在のレスポンスがバッファリングされているか確認できます。template_redirectで判定される前にfalseを返します。

出力

このフィルターは、送信前のバッファリング済みHTMLドキュメント全体を受け取ります。Blockstudio独自のアセット移動は優先度1000000で、Tailwindのコンパイルは999999で実行されるため、それらより前のドキュメントを見るには先に、最終出力を見るには後に実行します。

PHP
add_filter('blockstudio/buffer/output', function(string $html) {
  return $html;
}, 2000000);

レンダリング

依存関係

このフィルターは、Blockstudioがブロックをレンダリングするたびに、選択されたテンプレートとアセットの依存関係を報告します。静的エクスポーターや、プロセス内で依存関係を収集するその他のツールに便利です。

PHP
add_filter(
  'blockstudio/render/dependencies',
  function($paths, $name, $block, $isEditor, $isPreview) {
    my_dependency_graph()->add($name, $paths);
    return $paths;
  },
  10,
  5
);

グローバル

このフィルターでは、ページのレンダリング前に出力を調整できます。

PHP
add_filter('blockstudio/render', function($content) {
  return $content;
});

このフィルターを使うと、レンダリング前に<head>タグの出力を調整できます。Blockstudioがレスポンスをバッファリングする場合にのみ実行されます。bs_is_buffering()を参照してください。

PHP
add_filter('blockstudio/render/head', function($content) {
  return $content . '<meta name="custom" content="value">';
});

このフィルターでは、レンダリング前に</body>の出力を調整できます。

PHP
add_filter('blockstudio/render/footer', function($content) {
  return $content . '<script>console.log("loaded")</script>';
});

エラー処理

error/logged

エラーがログに記録された後にアクションが発火します。外部のログサービスにエラーを送信するために使用します。

PHP
add_action('blockstudio/error/logged', function($message, $level, $context) {
  if ($level === 'error') {
    my_external_logger($message, $context);
  }
}, 10, 3);

error/exception

例外が処理された後にアクションが発火します。

PHP
add_action('blockstudio/error/exception', function($exception, $context) {
  my_error_tracker($exception);
}, 10, 2);

データベース

すべてのデータベースフックは、単一の$params配列を受け取ります。

db/before_create

レコードの作成前にアクションが発火します。

PHP
add_action('blockstudio/db/before_create', function($params) {
  // $params: block, schema, data, storage
});

db/after_create

レコードの作成後にアクションが発火します。

PHP
add_action('blockstudio/db/after_create', function($params) {
  // $params: block, schema, record, storage
  wp_mail($params['record']['email'], 'Welcome!', 'Thanks for subscribing.');
});

db/before_update

レコードの更新前にアクションが発火します。

PHP
add_action('blockstudio/db/before_update', function($params) {
  // $params: block, schema, id, data, storage
});

db/after_update

レコードの更新後にアクションが発火します。

PHP
add_action('blockstudio/db/after_update', function($params) {
  // $params: block, schema, id, record, storage
});

db/before_delete

レコードの削除前にアクションが発火します。

PHP
add_action('blockstudio/db/before_delete', function($params) {
  // $params: block, schema, id, storage
});

db/after_delete

レコードの削除後にアクションが発火します。

PHP
add_action('blockstudio/db/after_delete', function($params) {
  // $params: block, schema, id, storage
});

RPC

すべてのRPCフックは、単一の$params配列を受け取ります。

rpc/before_call

RPC関数の呼び出し前にアクションが発火します。

PHP
add_action('blockstudio/rpc/before_call', function($params) {
  // $params: block, function, params
});

rpc/after_call

RPC関数の呼び出し後にアクションが発火します。

PHP
add_action('blockstudio/rpc/after_call', function($params) {
  // $params: block, function, params, result
});