README

用于生成 Schema.org JSON-LD 模式的辅助工具。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令之一

php composer.phar require --prefer-dist beastbytes/schemadotorg

或将其添加到您的 composer.json 文件的 require 部分。

"beastbytes/schema-dot-org": "^2.0"

使用

生成模式

// In the view
use BeastBytes\SchemaDotOrg\SchemaDotOrg;

$mapping = [
    // define mapping
];
$model = [
    // model can be an array or an object
];
$schema = SchemaDotOrg::generate($model, $mapping);
// Multiple schemas can be generated

生成的模式可以直接渲染

echo SchemaDotOrg::generate($model, $mapping);

或与视图注册

$this->registerJs(SchemaDotOrg::generate($model, $mapping));

定义模式映射

模式映射是一个数组，它定义了模型属性到 Schema.org 属性的映射；其形式为

$mapping = [
    'Type' => [
        'schemaDotOrgProperty' => 'model.property', // or
        'model.property' // if the Schema.org and property names are the same
    ]
];

其中，Schema.org 属性定义为 Schema.org 类型，类型是一个嵌套数组

[
    'Type' => [
        'schemaDotOrgProperty' => [
            'NestedType' => [
                // ...
            ]
        ]
    ]
]

如果 Schema.org 属性是字符串字面量，请在其前面添加 SchemaDotOrg::STRING_LITERAL

[
    'Type' => [
        'schemaDotOrgProperty' => SchemaDotOrg::STRING_LITERAL . 'Literal value'
    ]
]

如果 Schema.org 属性是 SchemaDotOrg 枚举值，请在其前面添加 SchemaDotOrg::ENUMERATION

[
    'Type' => [
        'schemaDotOrgProperty' => SchemaDotOrg::ENUMERATION . 'EnumerationName'
    ]
]

如果 Schema.org 属性是值数组 -通常是嵌套类型-指定映射为数组。键必须是或以 SchemaDotOrg::ARRAY 开头。如果是 SchemaDotOrg::ARRAY，则映射父键是模型属性，否则模型属性是键的其余部分；以下显示了两种形式

[
    'EducationalOrganization' => [
        'name',
        'alumni' => [
            SchemaDotOrg::ARRAY => [ // the model property is 'alumni'
                'Person' => [
                    'familyName',
                    'givenName'
                ]
            ]
        ]
    ]
]

[
    'EducationalOrganization' => [
        'name',
        'alumni' => [
            SchemaDotOrg::ARRAY . 'pastPupils' => [ // the model property is 'pastPupils'
                'Person' => [
                    'familyName',
                    'givenName'
                ]
            ]
        ]
    ]
]

示例模式映射定义

[
    'LocalBusiness' => [ // @type always begins with an uppercase letter
        'name' => 'org', // maps the 'org' property of the model to the Schema.org 'name' property
        'address' => [ // the Schema.org 'address' property is a PostalAddress type
            'PostalAddress' => [ // @type
                'adr.streetAddress', // no need for mapping if the Schema.org and model property names are the same
                'addressLocality' => 'adr.locality', // define the mapping if different property names 
                'addressRegion' => 'adr.region',
                'adr.postalCode'
            ]
        ],
        'location' => [
            'Place' => [
                'additionalProperty' => [
                    'PropertyValue' => [
                        'propertyID' => SchemaDotOrg::STRING_LITERAL . 'what3words',
                        'value' => 'adr.what3words',
                    ],           
                ],
                'latitude',
                'longitude',
            ],
        ],
        'email',
        'telephone' => 'tel.cell.value',
        'currenciesAccepted' => SchemaDotOrg::STRING_LITERAL . 'GBP',
        'image' => SchemaDotOrg::STRING_LITERAL . 'https://example.com/images/logo.svg',
        'makesOffer' => [
            'Offer' => [
                'name',
                'description',
                'price',
                'priceCurrency' => SchemaDotOrg::STRING_LITERAL . 'GBP',
                'availability' => SchemaDotOrg::ENUMERATION . 'InStock'
            ]
        ]
    ]
]

使用上述模式映射生成的示例 JSON-LD

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Business Name",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "99 Fencott Road",
    addressLocality: "Fencott",
    addressRegion: "Oxon",
    postalCode: "OX5 2RD"    
  }
  "location": {
    "@type": "Place",
    "additionalProperty": {
      "@type": "PropertyValue",
      "propertyID": "what3words",
      "value": "tangent.migrate.commander"
    },
    "latitude": 51.84095049377005,
    "longitude": -1.1709238113995422,
  },
  "email": "getintouch@example.com",
  "telephone": "01865 369248",
  "currenciesAccepted": "GBP",
  "image": "https://example.com/images/logo.svg",
  "makesOffer": {
    "@type": "Offer",
    "name": "Awesome Product",
    "description": "The ony product you will ever need",
    "price": 999.99,
    "priceCurrency": "GBP",
    "availability": "https://schema.org/InStock"
  }  
}
</script>

Twig 模板

要在 Twig 模板中使用此辅助工具，要么将其包含在 CommonViewInjection 中（在示例中分配给 schemaDotOrg 变量），要么在模板中包含它

{% set schemaDotOrg = get('BeastBytes\\SchemaDotOrg\\SchemaDotOrg') %}

然后在模板中，要么

立即输出模式

{{ schemaDotOrg.generate(model, mapping) }}

或将模式与视图注册

{% do this.registerJs(schemaDotOrg.generate(model, mapping)) %}

定义映射

在 Twig 模板中，映射必须定义 SchemaDotOrg 属性和模型属性，即使它们具有相同的名称。
要使用 SchemaDotOrg 类常量，请使用 Twig 的 constant() 函数并连接字符串

例如

{
    Offer: {
        name: 'name',
        description: 'description',
        price: 'price',
        priceCurrency: constant('STRING_LITERAL', schemaDotOrg) ~ 'GBP',
        availability: constant('ENUMERATION', schemaDotOrg) ~ 'InStock'
    }
}

测试

所有测试都在根目录中执行。

单元测试

该包使用 PHPUnit 进行测试。要运行测试：composer test

突变测试

该包测试使用 Infection 突变框架和 Infection 静态分析插件进行检查。要运行它：composer infection

静态分析

使用 Psalm 对代码进行静态分析。要运行静态分析：composer psalm

许可证

Schema.org 辅助工具是免费软件。它在 BSD 许可证的条款下发布。有关更多信息，请参阅 LICENSE。

beastbytes / schema-dot-org-helper

维护者

详细信息