README

Schema.org 类型与 ld+json 生成器的流畅构建器

spatie/schema-org 为所有 Schema.org 类型及其属性提供流畅构建器。`src` 目录中的代码是从 Schema.org 的 JSON-LD 标准文件生成的，因此它提供了整个核心词汇表的对象和方法。类和方法也有完整的文档，作为快速参考。

use Spatie\SchemaOrg\Schema;

$localBusiness = Schema::localBusiness()
    ->name('Spatie')
    ->email('[email protected]')
    ->contactPoint(Schema::contactPoint()->areaServed('Worldwide'));

echo $localBusiness->toScript();

<script type="application/ld+json">
{
    "@context": "https:\/\/schema.org",
    "@type": "LocalBusiness",
    "name": "Spatie",
    "email": "[email protected]",
    "contactPoint": {
        "@type": "ContactPoint",
        "areaServed": "Worldwide"
    }
}
</script>

支持我们

我们投入了大量资源来创建最佳类别的开源包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄给我们明信片，注明您正在使用我们哪个包。您可以在我们的联系页面上找到我们的地址。我们将所有收到的明信片发布在我们的虚拟明信片墙上。

安装

您可以通过 composer 安装此包

composer require spatie/schema-org

用法

所有类型都可以通过 Spatie\SchemaOrg\Schema 工厂类或使用 new 关键字进行实例化。

$localBusiness = Schema::localBusiness()->name('Spatie');

// Is equivalent to:

$localBusiness = new LocalBusiness();
$localBusiness->name('Spatie');

所有类型也接受预期数据类型的数组，例如 sameAs 接受字符串或字符串数组。

所有类型也实现了 SPL 的 ArrayAccess，可以通过数组符号访问属性。

$anotherLocalBusiness = new LocalBusiness();
var_dump(isset($anotherLocalBusiness['name'])); // => false
$anotherLocalBusiness['name'] = 'Spatie';
var_dump(isset($anotherLocalBusiness['name'])); // => true
var_dump($anotherLocalBusiness['name']); // => 'Spatie'
unset($anotherLocalBusiness['name']);
var_dump(isset($anotherLocalBusiness['name'])); // => false

类型可以被转换为数组或渲染为脚本。

$localBusiness->toArray();

echo $localBusiness->toScript();

echo $localBusiness; // Same output as `toScript()`

此外，所有类型都可以通过调用 json_encode() 并传递您的对象来转换为纯 JSON 字符串

echo json_encode($localBusiness);

我建议您使用 Google 的结构化数据测试工具仔细检查您的结构化数据。

枚举

从 v1.6.0 版本开始，所有枚举子类型都作为具有常量的类提供。

Schema::book()->bookFormat(Spatie\SchemaOrg\BookFormatType::Hardcover);

没有类型和属性的完整 API 文档。您可以参考源代码或 schema.org 网站。

如果您不希望中断大型模式对象链，可以使用 if 方法有条件地修改模式。

use Spatie\SchemaOrg\LocalBusiness;
use Spatie\SchemaOrg\Schema;

$business = ['name' => 'Spatie'];

$localBusiness = Schema::localBusiness()
    ->name($business['name'])
    ->if(isset($business['email']), function (LocalBusiness $schema) use ($business) {
        $schema->email($business['email']);
    });

标识符

从 v2.6.0 版本开始，`identifier` 键被替换为 `@id` 用于简单的字符串标识符。这是由于 `ld+json` 语法定义的结果。

所有 schema.org 语法都已经内置了对 URI 和 URL 的表示，例如在 Microdata 中的 'itemid'，在 RDFa 1.1 中的 'resource'，在 JSON-LD 中的 `@id`。

— schema.org/docs // PR#102 // PR#157

高级用法

如果您需要设置自定义属性，可以使用 setProperty 方法。

$localBusiness->setProperty('foo', 'bar');

如果您需要检索属性，可以使用 getProperty 方法。您可以可选地传递第二个参数以提供默认值。

$localBusiness->getProperty('name'); // 'Spatie'
$localBusiness->getProperty('bar'); // null
$localBusiness->getProperty('bar', 'baz'); // 'baz'

所有属性都可以通过getProperties方法作为数组检索。

$localBusiness->getProperties(); // ['name' => 'Spatie', ...]

可以使用addProperties方法一次设置多个属性。

$localBusiness->addProperties(['name' => 'value', 'foo' => 'bar']);

可以使用getContext和getType方法检索上下文和类型。

$localBusiness->getContext(); // 'https://schema.org'
$localBusiness->getType(); // 'LocalBusiness'

图 - 多个项

图有很多方法和实用工具 - 最安全、最简单的方式是使用Spatie\SchemaOrg\Schema类的重载方法。这些方法将获取已创建或新创建的请求架构实例。

$graph = new Graph();

// Create a product and prelink organization
$graph
    ->product()
    ->name('My cool Product')
    ->brand($graph->organization());

// Hide the organization from the created script tag
$graph->hide(\Spatie\SchemaOrg\Organization::class);

// Somewhere else fill out the organization
$graph
    ->organization()
    ->name('My awesome Company');

// Render graph to script tag
echo $graph;

使用这些工具，图是所有可用架构的集合，可以将这些架构相互链接，并防止辅助架构在脚本标签中被渲染。

图节点标识符

有时您需要跟踪多个相同类型的图节点 - 例如，在您的组织中为不同的人使用多个Person节点。为此，您可以在图实例上使用节点标识符。如果您没有提供标识符，将使用保留关键字default标识符。

use Spatie\SchemaOrg\Graph;
use Spatie\SchemaOrg\Person;

$graph = new Graph();

// add a Person using chaining
$graph->person('freekmurze')
    ->givenName('Freek')
    ->familyName('Van der Herten')
    ->alternateName('freekmurze');

// add a Person using closure
$graph->person('sebastiandedeyne', function(Person $sebastian, Graph $graph): void {
    $sebastian
        ->givenName('Sebastian')
        ->familyName('De Deyne')
        ->alternateName('sebastiandedeyne');
}); 

// add a person using closure and second call with same identifier
$graph->person(
    'gummibeer', 
    fn(Person $gummibeer) => $gummibeer->alternateName('gummibeer')
);
$graph->person('gummibeer')
    ->givenName('Tom')
    ->familyName('Witkowski');

$graph->person('random')->name('Random Person');

// hide the random person from Graph
$graph->hide(Person::class, 'random');

echo json_encode($graph);

{
    "@context":"https:\/\/schema.org",
    "@graph":[
        {
            "@type":"Person",
            "givenName":"Freek",
            "familyName":"Van der Herten",
            "alternateName":"freekmurze"
        },
        {
            "@type":"Person",
            "givenName":"Sebastian",
            "familyName":"De Deyne",
            "alternateName":"sebastiandedeyne"
        },
        {
            "@type":"Person",
            "alternateName":"gummibeer",
            "givenName":"Tom",
            "familyName":"Witkowski"
        }
    ]
}

多类型实体

Schema.org允许多类型实体 - 使用此包时，您可以使用MultiTypedEntity类 - 它的工作方式类似于图。

$mte = new MultiTypedEntity();
$mte->hotelRoom()->name('The Presidential Suite');
$mte->product()->offers(
    Schema::offer()
        ->name('One Night')
        ->price(100000.00)
        ->priceCurrency('USD')
);
$mte->product(function (Product $product) {
    $product->aggregateRating(
        Schema::aggregateRating()
            ->bestRating(5)
            ->worstRating(4)
    );
});

echo json_encode($mte);

{
   "@context":"https:\/\/schema.org",
   "@type":[
      "HotelRoom",
      "Product"
   ],
   "name":"The Presidential Suite",
   "offers":{
      "@type":"Offer",
      "name":"One Night",
      "price":100000,
      "priceCurrency":"USD"
   },
   "aggregateRating":{
      "@type":"AggregateRating",
      "bestRating":5,
      "worstRating":4
   }
}

没有关于如何合并属性的真正规则。它仅在幕后使用array_merge()。因此，您应该避免在MTE的不同类型中定义相同的属性，或者确保所有属性具有相同的值，这样就不重要哪个属性被最终使用。

已知问题

由于在PHP中是保留关键字，因此没有提供Float类型。
由于它扩展了来自health扩展规范的类型，因此没有提供Physician类型。

更改日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

测试

$ composer test

贡献

请参阅CONTRIBUTING以获取详细信息。

安全性

如果您发现有关安全性的错误，请通过[email protected]发送邮件，而不是使用问题跟踪器。

Postcardware

您可以使用此包，但如果它进入您的生产环境，我们非常感谢您从您的家乡寄给我们一张明信片，说明您正在使用我们的哪个包。

我们的地址是：Spatie，Kruikstraat 22，2018 安特卫普，比利时。

我们在公司网站上发布所有收到的明信片。

鸣谢

许可

MIT许可（MIT）。请参阅许可文件以获取更多信息。

spatie / schema-org

维护者

详细信息