README

一个PHP库，用于从HTML页面中读取schema.org结构化数据。

简介

此库使用brick/structured-data从HTML页面中提取结构化数据（Microdata、RDFa Lite & JSON-LD），并将找到的任何schema.org信息映射到实现schema.org接口的IDE和静态分析友好的对象。

安装

此库可以通过Composer安装。

composer require brick/schema

要求

此库需要PHP 7.2或更高版本。它使用以下扩展

这些扩展默认启用，并且应在大多数PHP安装中可用。

项目状态和发布流程

此库处于开发状态。在早期的0.x版本中，它可能变化很快。然而，此库遵循严格的BC破坏约定

当前版本编号为0.x.y。当引入非破坏性更改时（添加新方法、修复错误、优化现有代码等），y递增。

当引入破坏性更改时，总是开始一个新的0.x版本周期。

因此，将您的项目锁定到给定的发布周期，例如0.1.*是安全的。

如果您需要升级到较新的发布周期，请查看发布历史记录以获取每个后续0.x.0版本引入的更改列表。

快速入门

首先，您需要实例化一个SchemaReader

use Brick\Schema\SchemaReader;

// read all available formats:
$schemaReader = SchemaReader::forAllFormats();

// or read a single format:
// $schemaReader = SchemaReader::forMicrodata();
// $schemaReader = SchemaReader::forRdfaLite();
// $schemaReader = SchemaReader::forJsonLd();

然后，您可以继续读取HTML文档

// The URL the document was retrieved from. This will be used only to resolve relative
// URLs in property values. No attempt will be performed to connect to this URL.
$url = 'https://example.com/product/123';

$things = $schemaReader->readHtml($html, $url);               // An HTML document as a string
// or $things = $schemaReader->readHtmlFile($htmlFile, $url); // A path to an HTML file
// or $things = $schemaReader->read($domDocument, $url);      // A DOMDocument instance

这返回一个Thing实例数组，这是所有schema.org对象继承的基类。

所有返回的对象都实现了Thing，但更重要的是，它们实现了在标记中定义的接口，例如Person或Product。这些对象通过列出它们的可用属性来通过instanceof检查，并允许IDE自动完成和静态分析。

schema.org接口位于Brick\Schema\Interfaces命名空间下

Brick\Schema\Interfaces\Thing
- Brick\Schema\Interfaces\Person
- ...

每个接口的每个属性，例如Person::$birthDate是SchemaTypeList的实例，它是一个包含零个或多个值的容器。每个值可以是另一个Thing，或一个纯文本string。

考虑到这一点，让我们看一个例子

use Brick\Schema\Interfaces as Schema;

foreach ($things as $thing) {
    if ($thing instanceof Schema\Product) {
        // Your IDE should now provide autocompletion for available Product properties:
        // category, color, gtin, sku, offers, ...

        foreach ($thing->offers as $offer) {
            // You should always check if the Thing matches the expected type,
            // even if the schema.org property documents a single type (here, Offer).
            // See the Caveats section below for an explanation why.

            if ($offer instanceof Schema\Offer) {
                // Yes! we do have an offer, let's check its price.
                // Don't forget that all properties have zero or more values, let's take the first one:

                $price = $offer->price->getFirstValue();

                // For the same reason as above (see Caveats), always check the type of the value,
                // it could very well be a nested Thing instance, or null if there is no value.

                if (is_string($price)) {
                    echo $price;
                }

                // There are also helper functions in the SchemaTypeList object when you expect a string.
                // For example, this will return the first string value, or null if not found:

                $priceCurrency = $offer->priceCurrency->toString();

                if ($priceCurrency !== null) {
                    echo $priceCurrency;
                }
            }
        }
    }
}

注意：如果您尝试访问未定义在任何Thing对象实现的类型上的属性，将抛出异常。

注意事项

虽然schema.org属性定义得很好，但它们在接收值方面相当宽松。虽然它们为每个属性记录了预期的类型（例如，一个Product的offer可能只能是Offer类型），但实际上，根据schema.org数据模型，此库在任意字段中接受任何Thing或string。

因此，您应该对所有文档化的接口属性类型持保留态度，并在您的代码中始终执行如 instanceof 或 is_string() 这样的检查。

引用 schema.org 网站

符合性

尽管在搜索应用中，如果结构化数据标记始终严格遵守 schema.org 可能有所帮助，但在实践中这是不现实的。我们的模式也在根据反馈、讨论和数据的新应用不断进化。在可能的情况下，我们逐步修改现有定义，而不是为类似用例引入大量新属性。因此，schema.org 基于一个非常灵活的数据模型，并持务实观点来处理符合性。

我们预计 schema.org 属性将用于新的类型，这些类型来自 schema.org 和外部扩展。我们预计，通常情况下，当我们期望属性值为 Person、Place、Organization 或其他 Thing 的子类时，我们可能会得到一个文本字符串，即使我们的模式没有正式记录这种期望。本着“有数据比没有数据好”的精神，搜索引擎通常会接受这种标记，并尽最大努力处理。同样，一些类型如 Role 和 URL 可以与所有属性一起使用，我们鼓励数据消费者进行此类实验。

brick / schema

维护者

详细信息

README

简介

安装

要求

项目状态和发布流程

快速入门

注意事项