alleyinteractive/wp-match-blocks

匹配给定内容中的WordPress块。

维护者

详细信息

github.com/alleyinteractive/wp-match-blocks

源代码

问题

安装量: 30 217

依赖项: 3

建议者: 0

安全: 0

星标: 6

关注者: 23

分支: 1

开放问题: 0

v3.1.0 2023-11-02 03:13 UTC

Requires

Requires (Dev)

GPL-2.0-or-later 1fa48dc7059653df7ac46ec1fad05e36da236578

  • Alley <info.woop@alley.com>

This package is auto-updated.

Last update: 2024-08-31 00:30:02 UTC

README

match_blocks() 选取与给定标准匹配的块，如块名称、块属性或块在集合中的位置。

块可以通过以下方式匹配

  • 块名称或名称（name）
  • 块属性（attrs，with_attrs）
  • 块内部HTML（with_innerhtml）
  • 块在集合中的正负索引（position）
  • 块是否仅代表空间（skip_empty_blocks）
  • 块是否有内部块（has_innerblocks）
  • 自定义验证类（is_valid）

传递匹配参数是可选的；默认情况下，所有非空块都会匹配。

此外

  • 支持递归到内部块（flatten）。
  • 可以通过大小（limit）或它们在匹配集合中的位置（nth_of_type）来限制匹配块的集合。
  • 可以返回匹配的数量而不是匹配的块（count）。
  • 辅助函数 match_block() 将筛选后的结果集减少到单个解析块。
  • 传递单个块实例将返回其内部块的匹配项。

match_blocks() 由一组块验证类提供支持，这些类利用了 Laminas Validator 框架和 Laminas Validator Extensions 包。这些验证器以及一个用于验证块的基类都包含在此处。 请参阅验证器部分以获取其文档。

安装

使用以下命令安装最新版本

$ composer require alleyinteractive/wp-match-blocks

基本用法

查找帖子中的所有段落块

<?php

$grafs = \Alley\WP\match_blocks( $post, [ 'name' => 'core/paragraph' ] );

包括内部块中的段落

<?php

$grafs = \Alley\WP\match_blocks(
    $post,
    [
        'flatten' => true,
        'name'    => 'core/paragraph',
    ]
);

获取段落块的数量

<?php

$count = \Alley\WP\match_blocks(
    $post,
    [
        'count' => true,
        'name'  => 'core/paragraph',
    ]
);

获取给定组块内部段落块的数量

<?php

$blocks = parse_blocks( '<!-- wp:group --><div class="wp-block-group"><!-- wp:paragraph -->…<!-- wp:group /-->' );

$count = \Alley\WP\match_blocks(
    $blocks[0],
    [
        'count' => true,
        'name'  => 'core/paragraph',
    ]
);

获取所有段落和标题

<?php

$blocks = \Alley\WP\match_blocks(
    '<!-- wp:paragraph -->…',
    [
        'name' => [ 'core/heading', 'core/paragraph' ],
    ]
);

获取所有明确对齐的段落

<?php

$blocks = \Alley\WP\match_blocks(
    [ /* blocks */ ],
    [
        'name'       => 'core/paragraph',
        'with_attrs' => 'align',
    ]
);

获取所有右对齐的段落

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'attrs' => [
            [
                'key'   => 'align',
                'value' => 'right',
            ],
        ],
        'name'  => 'core/paragraph',
    ]
);

获取所有未右对齐但对齐的段落

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'attrs' => [
            [
                'key'      => 'align',
                'value'    => 'right',
                'operator' => '!==',
            ],
        ],
        'name'  => 'core/paragraph',
    ]
);

获取所有左对齐或右对齐的段落

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'attrs' => [
            [
                'key'      => 'align',
                'value'    => [ 'left', 'right' ],
                'operator' => 'IN',
            ],
        ],
        'name'  => 'core/paragraph',
    ]
);

获取所有署名为美联社的图片

<?php

$images = \Alley\WP\match_blocks(
    $post,
    [
        'attrs' => [
            [
                'key'      => 'credit',
                'value'    => '/(The )?Associated Press/i',
                'operator' => 'REGEX',
            ],
            [
                'key'   => 'credit',
                'value' => 'AP',
            ],
            'relation' => 'OR',
        ],
        'name'  => 'core/image',
    ]
);

获取具有特定短语的短代码块

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'name'           => 'core/shortcode',
        'with_innerhtml' => '[bc_video',
    ]
);

审计帖子以检查引用不再可访问视频的YouTube嵌入块。

<?php

final class YouTube_Video_Exists extends \Alley\WP\Validator\Block_Validator {
    // ...
}

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'name'     => 'core/embed',
        'attrs'    => [
            [
                'key'   => 'providerNameSlug',
                'value' => 'youtube',
            ],
        ],
        'is_valid' => new \Alley\Validator\Not( new YouTube_Video_Exists(), '…' ),
    ],
);

获取前三个块

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'limit' => 3,
    ]
);

获取前三个段落块

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'limit' => 3,
        'name'  => 'core/paragraph',
    ]
);

获取第三个段落

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'name'        => 'core/paragraph',
        'nth_of_type' => 3,
    ]
);

// Or, skip straight to the parsed block:

$block = \Alley\WP\match_block(
    $post,
    [
        'name'        => 'core/paragraph',
        'nth_of_type' => '3n',
    ]
);

获取每三个段落

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'name'        => 'core/paragraph',
        'nth_of_type' => '3n',
    ]
);

获取第3-8个段落

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'name'        => 'core/paragraph',
        'nth_of_type' => [ 'n+3', '-n+8' ],
    ]
);

如果它是段落，则获取集合中位置为3的块

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'name'     => 'core/paragraph',
        'position' => 3,
    ]
);

获取最后两个块

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'position' => [ -1, -2 ],
    ]
);

获取所有非空块

<?php

$blocks = \Alley\WP\match_blocks( $post );

获取所有空块

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'name'              => null,
        'skip_empty_blocks' => false,
    ]
);

获取仅包含内部块的块

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'has_innerblocks' => true,
    ]
);

获取不包含内部块的块

<?php

$blocks = \Alley\WP\match_blocks(
    $post,
    [
        'has_innerblocks' => false,
    ]
);

验证器

此包提供了基于 Laminas Validator 框架和 Laminas Validator Extensions 包的类，以及一个自定义的基块验证类。

match_blocks() 也内部使用这些验证器，并且可以将它们作为 is_valid 参数传递给 match_blocks() 或单独使用。

基本验证器

抽象类 Alley\WP\Validator\BlockValidator 继承自 Alley\Validator\BaseValidator，类似于 BaseValidator，它标准化了块验证。

当扩展 BlockValidator 时，验证逻辑将放入 test_block() 方法中。 test_block() 总是接收一个 \WP_Block_Parser_Block 实例；如果输入不是 \WP_Block、\WP_Block_Parser_Block 或块的数组表示形式，则验证将自动失败。

块属性

Alley\WP\Validator\Block_Attribute 验证块是否包含或不含指定的属性名称、值或名称-值对。

如果指定了名称比较，并且块包含一个名称匹配比较的属性，则块通过验证；如果指定了值比较，并且块包含一个值匹配比较的属性，则块通过验证；或者如果同时指定了名称和值比较，并且块包含一个名称和值都匹配的属性，则块通过验证。

支持选项

以下选项支持 Alley\WP\Validator\Block_Attribute

  • key：块属性的名称，或名称数组，或正则表达式模式。默认无。
  • value：块属性值，或值数组，或正则表达式模式。默认无。
  • operator：用于比较 $value 与块属性的运算符。接受 CONTAINS、NOT CONTAINS（区分大小写）、IN、NOT IN、LIKE、NOT LIKE（不区分大小写）、REGEX、NOT REGEX 或由 \Alley\Validator\Comparison 支持的任何运算符。默认为 ===。
  • key_operator：等同于 operator，但用于 $key。

基本用法

<?php

// '<!-- wp:media-text {"mediaId":617,"mediaType":"image","isStackedOnMobile":false,"className":"alignwide"} -->';

$valid = new Alley\WP\Validator\Block_Attribute(
    [
        'key'   => 'mediaType',
        'value' => 'image',
    ],
);

$valid = new Alley\WP\Validator\Block_Attribute(
    [
        'key'          => [ 'mediaType', 'mediaId' ],
        'key_operator' => 'IN',
    ],
);

$valid = new Alley\WP\Validator\Block_Attribute(
    [
        'key'          => '/^media/',
        'key_operator' => 'REGEX',
        'value'        => [ 'image', 'video' ],
        'operator'     => 'IN',
    ],
);

$valid = new Alley\WP\Validator\Block_Attribute(
    [
        'key'          => '/^media/',
        'key_operator' => 'REGEX',
        'value'        => [ 'audio', 'document' ],
        'operator'     => 'NOT IN',
    ],
);

块内HTML

Alley\WP\Validator\Block_InnerHTML 验证块是否在其 innerHTML 属性中包含指定的内容。如果块包含匹配比较的 innerHTML 值，则块通过验证。

支持选项

以下选项支持 Alley\WP\Validator\Block_InnerHTML

  • content：要查找的内容或正则表达式模式。
  • operator：用于比较 $content 与块内 HTML 的运算符。接受 CONTAINS、NOT CONTAINS（区分大小写）、IN、NOT IN、LIKE、NOT LIKE（不区分大小写）、REGEX、NOT REGEX 或由 \Alley\Validator\Comparison 支持的任何运算符。默认为 LIKE。

基本用法

<?php

// '
// <!-- wp:paragraph -->
// <p>The goal of this new editor is to make adding rich content to WordPress simple and enjoyable.</p>
// <!-- /wp:paragraph -->
// '

$valid = new Alley\WP\Validator\Block_InnerHTML(
    [
        'content'  => 'wordpress',
        'operator' => 'LIKE',
    ],
);

$valid = new Alley\WP\Validator\Block_InnerHTML(
    [
        'content'  => 'WordPress',
        'operator' => 'CONTAINS',
    ],
);

$valid = new Alley\WP\Validator\Block_InnerHTML(
    [
        'content'  => '/^\s*<p>\s*</p>/',
        'operator' => 'NOT REGEX',
    ],
);

块名称

Alley\WP\Validator\Block_Name 验证块是否具有指定的名称或一组名称。如果块名称在集合中，则块通过验证。

支持选项

以下选项支持 Alley\WP\Validator\Block_Name

-name：块名称或名称。

基本用法

<?php

$valid = new Alley\WP\Validator\Block_Name(
    [
        'name' => 'core/paragraph',
    ]
);

$valid = new Alley\WP\Validator\Block_Name(
    [
        'name' => [ 'core/gallery', 'jetpack/slideshow', 'jetpack/tiled-gallery' ],
    ]
);

块偏移

Alley\WP\Validator\Block_Offset 验证块是否出现在给定数字偏移量内的块列表中。

如果块出现在列表中的偏移量之一，则块匹配。

通过比较 \WP_Block_Parser_Block 实例作为数组来确定身份。

支持选项

以下选项支持 Alley\WP\Validator\Block_Offset

  • blocks：块数组或可迭代对象。
  • offset：预期的偏移量或偏移量。负偏移量从列表末尾开始计算。
  • skip_empty_blocks：在索引 $blocks 时是否跳过根据 Nonempty_Block_Validator 被视为“空”的块。默认为 true。

基本用法

<?php

$blocks = parse_blocks(
    <<<HTML
<!-- wp:paragraph --><p>Hello, world!</p><!-- /wp:paragraph -->

<!-- wp:archives {\"displayAsDropdown\":true,\"showPostCounts\":true} /-->

<!-- wp:media-text {\"mediaId\":617,\"mediaType\":\"image\",\"isStackedOnMobile\":false,\"className\":\"alignwide\"} -->
HTML
);

$valid = new Alley\WP\Validator\Block_Offset(
    [
        'blocks' => $blocks,
        'offset' => 1,
    ],
);
$valid->isValid( $blocks[2] ); // true

$valid = new Alley\WP\Validator\Block_Offset(
    [
        'blocks'            => $blocks,
        'offset'            => [ 4 ],
        'skip_empty_blocks' => false,
    ],
);
$valid->isValid( $blocks[4] ); // true

$valid = new Alley\WP\Validator\Block_Offset(
    [
        'blocks' => $blocks,
        'offset' => -2,
    ],
);
$valid->isValid( $blocks[2] ); // true

块内部块计数

Alley\WP\Validator\Block_InnerBlocks_Count 验证给定块内部块的数量是否通过指定的比较。

如果内部块的计数比较为真，则块通过验证。内部块中的内部块不计入总数。

支持选项

以下是对 Alley\WP\Validator\Block_InnerBlocks_Count 支持的选项：

  • count：比较中期望的内部块数量。
  • operator：用于比较输入块的内部块和 count 的 PHP 比较运算符。

基本用法

<?php

$blocks = parse_blocks(
    <<<HTML
<!-- wp:foo -->
    <!-- wp:bar -->
        <!-- wp:baz /-->
    <!-- /wp:bar -->
<!-- /wp:foo -->
HTML
);

$valid = new \Alley\WP\Validator\Block_InnerBlocks_Count(
    [
        'count'    => 1,
        'operator' => '===',
    ]
);
$valid->isValid( $blocks[0] ); // true

$valid = new \Alley\WP\Validator\Block_InnerBlocks_Count(
    [
        'count'    => 0,
        'operator' => '>',
    ]
);
$valid->isValid( $blocks[0] ); // true

$valid = new \Alley\WP\Validator\Block_InnerBlocks_Count(
    [
        'count'    => 42,
        'operator' => '<=',
    ]
);
$valid->isValid( $blocks[0] ); // true

Nonempty_Block

Alley\WP\Validator\Nonempty_Block 验证给定的块不是“空的”——例如，不是一个仅代表换行的块。

如果块具有非空名称，则块通过验证。

支持选项

无。

基本用法

<?php

$blocks = parse_blocks( "\n" );

$valid = new \Alley\WP\Validator\Nonempty_Block();
$valid->isValid( $blocks[0] ); // false

关于

许可

GPL-2.0-or-later

维护者

Alley Interactive