README

帮助生成 schema.org 标记

用法

注意： 目前，Schemer 仅生成 "microdata" 格式。

Schemer 设计得非常简单易用：只需将结构化数组传递给您想要使用的 Scheme 的 ::build() 静态方法。

echo AlwaysBlank\Schemer\Scheme\PostalAddress::build([
    ['street', '123 Oak St'],
    ['state', 'OR'],
    ['city', 'Portland'],
    ['zip', '97123'],
    ['pobox', 'P.O. 1234'],
    ['country', 'USA'],
]);

// <span itemscope itemprop="http://schema.org/PostalAddress"><span itemprop="streetAddress">123 Oak St</span><span itemprop="addressRegion">OR</span><span itemprop="addressLocality">Portland</span><span itemprop="postalCode">97123</span><span itemprop="postOfficeBoxNumber">P.O. 1234</span><span itemprop="addressCountry">USA</span></span>

您可以选择传递第二个参数，这是一个数组，其中包含将覆盖默认值的参数。这允许您进行更改元素标签、添加任意属性等操作。

echo AlwaysBlank\Schemer\Scheme\PostalAddress::build([
    ['street', '123 Oak St'],
    ['state', 'OR'],
    ['city', 'Portland'],
    ['zip', '97123'],
    ['pobox', 'P.O. 1234'],
    ['country', 'USA'],
], [
    'tag' => 'a',
    'attributes' => [
        'href'      => 'https://www.alwaysblank.org',
        'hidden'    => true,
    ],
]);
// <a itemscope itemprop="http://schema.org/PostalAddress" href="https://www.alwaysblank.org' hidden><span itemprop="streetAddress">123 Oak St</span><span itemprop="addressRegion">OR</span><span itemprop="addressLocality">Portland</span><span itemprop="postalCode">97123</span><span itemprop="postOfficeBoxNumber">P.O. 1234</span><span itemprop="addressCountry">USA</span></a>

实际的 HTML 输出略有不同：为了允许简单的断点但提供最大化的样式选项，每个内联元素后面都跟着 <span class="spc"></span>，一个零宽度的空格。这允许浏览器在此处断行，但除了这一点之外不提供任何格式化。

方案

目前 Schemer 以某种方式支持以下方案。未来将添加更多！请随时提交您希望看到的方案的问题，或者——更好的是！——提交添加它们的拉取请求。有关如何创建新的方案和属性的更多信息，请参阅下方的“如何工作”。

PostalAddress 可以理解以下内容
- 街道
- 州
- 城市
- zip（邮编）
- pobox（邮政信箱）
- 国家
LocalBusiness 可以理解以下内容
- 名称
- phone（电话号码将以 tel: 链接的形式呈现）
- url（url 可以是一个字符串，或者一个包含两个元素的数组，键为 url 和 content）
- address（这是一个包含将被 PostalAddress 理解的键的数组）

如何工作

Schemer 有三个基本部分

节点
属性
方案

节点

《节点》是最简单的元素，也是唯一一个真正像类（尽管《属性》和《方案》是类，但它们实际上是静态方法的包装器）的元素。《节点》为单个段提供了某种包装器，并用于生成实际的 HTML。

通常，您不太可能直接与 Node 交互，除非通过传递一系列参数创建它们。

$Node = Node::add([
    'itemscope'     => true,
    'itemtype'      => 'http://schema.org/LocalBusiness',
    'itemprop'      => 'description',
    'tag'           => 'div',
    'content'       => "Always Blank",
    'attributes'    => [
        'href'      => 'https://www.alwaysblank.org',
        'hidden'    => true,
    ]
]);

理解这个语法是有帮助的，因为这将对于创建新的 Property 或修改现有的属性或 Scheme 是必要的。

属性

《属性》在其一生中只有一个目的，就是返回一个带有适当的参数的《节点》，这些参数代表 schema.org 属性。它也被实现为特质，以便可以稍后将其组合到《方案》中。

《属性》必须满足以下要求

它实现了一个公共静态方法，该方法的名称与您希望用作相关字段键/名称的名称相同——即 address 或 phone。通常，这些名称应该是简单的，而不是直接匹配 schema.org 属性。例如，telephone 在这里被表示为 phone。
此方法只接受一个参数。
此方法必须返回一个 Node。
《属性》的类和文件名必须是方法名称的 CamelCase 版本。即 pobox => POBox，name => Name 等。

属性可以接受任何类型的输入（尽管大多数接受字符串），但您应该知道，除了阅读源代码之外，没有明显的机制来知道属性可能期望其参数采用的具体格式，因此在构建这些内容时，请考虑用户体验。

方案

方案是最高级的；方案存在的主要目的是。它们非常简单。方案必须执行以下操作

扩展类AlwaysBlank\Schemer\Scheme\Scheme。这实际上可能是大部分功能。
实现一个名为wrap的公共静态方法。它接受两个参数：字符串类型的content，以及可选的数组args。它返回一个Node。使用此方法设置包含此Scheme的元素所需的属性（即itemprop）。
使用您希望此Scheme可以访问的任何Property特征。这定义了它将接受的参数。

以下是一个示例Scheme

class Example extends AlwaysBlank\Schemer\Scheme\Scheme
{
    use City;
    use Name;
    
    public static function wrap(string $content, array $args = []): Node
    {
        return Node::add(array_merge([
            'itemscope'     => true,
            'itemtype'      => 'http://schema.org/Example',
            'content'       => $content,
            'tag'           => 'section',
            'attributes'    => [
                'data-section' => 'example',
            ],
        ], $args));
    }

别名

在定义节点时，您可以使用属性的缩写。如果您发现自己需要输入大量的节点，这可能会很有用。

支持的缩写包括

这将创建一个名为Example的Scheme，它将理解city和name，并使用一个带有额外属性data-section="example"的<section>。

进一步了解

如果您对这些事物的工作方式有更多疑问，我鼓励您深入研究源代码。我已经努力清晰地记录了代码，并保持一切简单明了。

调试

要调试Schemer，将PHP常量ALWAYSBLANK_SCHEMER_DEBUG设置为true。与其他调试标志一样，我不建议您在生产环境中设置此值。

当前调试标志有以下效果（此列表可能会随着时间的推移而扩展）

在调用具有坏参数的Property时停止抑制异常。

局限性

嵌套

Scheme的输出通常非常“扁平”，即它只是一系列没有嵌套在其他元素中的元素。（例外的是，如果所涉及的Scheme将其他Scheme作为Property使用，如LocalBusiness使用Address。）这基本上是设计决定的：据我所知，构建一个允许用户动态修改任意元素嵌套的系统将在一个本应非常简单的库中创造极端的复杂性。总的来说，Scheme级别的内内容通常不是非常嵌套的（除了前面提到的例外）。

如果您发现自己需要更复杂的结构，Schemer设计得足够灵活，您可以“即时”构建Scheme和Property——或者甚至可以直接使用Property，而无需使用Scheme。

选项

这个库在“理解”方面目前有限。虽然它可以很容易地扩展，但我没有打算让它全面覆盖schema.org规范。欢迎礼貌地提出功能请求（并且好的PR可能会毫无疑问地合并），但请记住，这个库的主要目的是让一小部分重复性任务变得更少重复，而不是解决所有与微数据相关的所有问题。

alwaysblank / schemer

维护者

详细信息

README

用法

方案

如何工作

节点

属性

方案

别名

进一步了解

调试

局限性

嵌套

选项