playfinder/openactive-models

用于处理 Openactive 规范的库

维护者

详细信息

github.com/playfinder/models-php

源代码

安装次数: 26,431

依赖项: 0

建议者: 0

安全: 0

星级: 0

关注者: 0

分支: 8

v0.2.0 2023-10-06 10:29 UTC

Requires

Requires (Dev)

MIT 5c80f5b8078a76b108db90f3b756c967484ee85e

This package is auto-updated.

Last update: 2024-09-06 12:20:59 UTC

README

OpenActive 机会和预订规范的 PHP 模型

OpenActive 旨在为 PHP、Ruby 和 .NET 语言中定义的所有类提供模型文件，旨在跨 PHP、Ruby 和 .NET 语言提供模型文件。此存储库用于 PHP 文件；另请参阅 Ruby 和 .NET 实现。

目录

需求

本项目需要 PHP >=5.6。

安装

要使用 Composer 安装，请在终端运行

composer require openactive/models

使用方法

此软件包提供 OpenActive 规范的 PHP 模型。

它还提供一组 schema.org 规范的模型。

最后，它提供了一组用于处理 OpenActive 的 RPDE 数据馈送的字节。

模型

模型包含在 \OpenActive\Models 命名空间下。

您可以传递一个关联数组来实例化一个新模型，其中键是属性名，值是属性值。

例如，从您的 PHP 应用程序中运行

// Make sure you use the right namespace for your models
use OpenActive\Models\OA\SessionSeries;
use OpenActive\Models\OA\Place;
use OpenActive\Models\OA\GeoCoordinates;
use OpenActive\Models\OA\Concept;
use OpenActive\Models\OA\Organization;
use OpenActive\Models\OA\Offer;

$sessionSeries = new SessionSeries([
    "name" => "Virtual BODYPUMP",
    "description" => "This is the virtual version of the original barbell class, which will help you get lean, toned and fit - fast",
    "startDate" => "2017-04-24T19:30:00-08:00",
    "endDate" => "2017-04-24T23:00:00-08:00",
    "location" => new Place([
        "name" => "Raynes Park High School, 46A West Barnes Lane",
        "geo" => new GeoCoordinates([
            "latitude" => 51.4034423828125,
            "longitude" => -0.2369088977575302,
        ])
    ]),
    "activity" => [new Concept([
        "id" => "https://openactive.io/activity-list#5e78bcbe-36db-425a-9064-bf96d09cc351",
        "prefLabel" => "Bodypump™",
        "inScheme" => "https://openactive.io/activity-list"
    ])],
    "organizer" => new Organization([
        "name" => "Central Speedball Association",
        "url" => "http://www.speedball-world.com"
    ]),
    "offers" => [new Offer([
        "identifier" => "OX-AD",
        "name" => "Adult",
        "price" => 3.3,
        "priceCurrency" => "GBP",
        "url" => "https://profile.everyoneactive.com/booking?Site=0140&Activities=1402CBP20150217&Culture=en-GB"
    ])],
]);

请注意，在创建新模型时始终进行类型强制。

例如，在上面的示例中为 target 属性提供 string 将导致抛出 \OpenActive\Exception\InvalidArgumentException。

提供了一组用于所有属性的获取器和设置器。设置器也进行了类型强制。

OpenActive

OpenActive 模型包含在 \OpenActive\Models\OA 命名空间下。

要实例化一个新对象，请参阅 模型 部分，确保您正在使用模型中的正确命名空间。

Schema.org

Schema.org 模型包含在 \OpenActive\Models\SchemaOrg 命名空间下。

要实例化一个新对象，请参阅 模型 部分，确保您正在使用模型中的正确命名空间。

RPDE

RpdeItem & RpdeBody 是生成 RPDE 馈送页面时要使用的两个主要类。

馈送项

RpdeItem 用于创建页面上的每个单独的项目。它包括一个数据属性，该属性应该是 OA 模型的一个实例，以及元数据（id、modified、state 和 kind）。生成这些模型和元数据的工作留给每个应用程序开发者。

例如，一个会话系列集合

use OpenActive\Rpde\RpdeItem;

$feedItems = [
    new RpdeItem([
        "id" => "2",
        "modified" => 4,
        "state" => RpdeState::UPDATED,
        "kind" => RpdeKind::SESSION_SERIES,
        "data" => $sessionSeries2,
    ]),
    new RpdeItem([
        "id" => "1",
        "modified" => 5,
        "state" => RpdeState::DELETED,
        "kind" => RpdeKind::SESSION_SERIES,
    ]),
];

馈送页面

然后使用 RpdeBody 来包装一组项并提供 RPDE 页面预期的许可和下一个条目。为了帮助保持页面有效并创建正确的下一个链接，使用 RpdeBody::createFromNextChangeNumber 或 RpdeBody::createFromModifiedId 从 RpdeItem 的数组（构造函数已被设置为私有）创建 RPDE 页面馈送。

RpdeBody::createFromNextChangeNumber 将检查所有馈送项是否确实位于提供的 $changeNumber 参数之后。它将根据最新馈送项的修改值和提供的 $feedBaseUrl 参数构造下一个链接。

例如。

use OpenActive\Rpde\RpdeBody;

$feedPage = RpdeBody::createFromNextChangeNumber(
    'https://www.example.com/rpde-feeds/session-series', # $feedBaseUrl
    0, # $changeNumber,
    $feedItems
);

$feedPage->getNext(); # 'https://www.example.com/rpde-feeds/session-series?afterTimestamp=5&afterId=2'

RpdeBody::createFromModifiedId 将检查所有馈送项是否确实在提供的 $id 和 $modified 参数之后。它将根据最新馈送项的 id 和修改值以及提供的 $feedBaseUrl 参数来构建下一个链接。

例如。

use OpenActive\Rpde\RpdeBody;

$feedPage = RpdeBody::createFromModifiedId(
    'https://www.example.com/rpde-feeds/session-series', # $feedBaseUrl
    0, # $modified,
    0, # $id
    $feedItems
);

$feedPage->getNext(); # 'https://www.example.com/rpde-feeds/session-series?afterChangeNumber=5'

覆盖默认许可证

$feedPage->setLicense('https://www.example.com/my-licence/v2.0');

序列化馈送页面

最后，可以使用 Serialize RpdeBody::serialize($feedPage) 来序列化馈送页面，这将还会处理将每个馈送项的数据属性序列化为 JSON-LD。

$jsonFeedPage = RpdeBody::serialize($feedPage);

有关 RPDE 馈送的更多详细信息，请参阅 OpenActive 发布数据指南 和 RPDE 规范。

枚举

每个枚举值由一个包含每个可用值的常量的类表示。

例如，向计划中添加星期几

use OpenActive\Models\OA\Schedule;
use OpenActive\Enums\SchemaOrg\DayOfWeek;

new Schedule([
    "scheduledEventType" => "Event",
    "startTime" => "12:00:00",
    "endTime" => "14:00:00",
    "byDay" => [
        new DayOfWeek\Monday,
        new DayOfWeek\Wednesday,
        new DayOfWeek\Friday
    ],
    ...
]);

序列化

此包提供对 模型 和 \OpenActive\Rpde\RpdeBody 对象的 JSON-LD 序列化/反序列化支持。

serialize($obj, $prettyPrint = false, $schema = false, $modifiers = [])

返回给定对象 $obj 的 JSON-LD 字符串表示。

一个额外的参数 $prettyPrint 可用于返回人类可读格式的 JSON-LD 字符串。

以下是一个示例，使用上面定义的 \OpenActive\Models\OA\SessionSeries

use OpenActive\Models\OA\SessionSeries;

echo SessionSeries::serialize($sessionSeries, true);

将输出

{
    "@context": [
        "https:\/\/openactive.io\/",
        "https:\/\/openactive.io\/ns-beta"
    ],
    "type": "SessionSeries",
    "name": "Virtual BODYPUMP",
    "description": "This is the virtual version of the original barbell class, which will help you get lean, toned and fit - fast.",
    "startDate": "2017-04-24T19:30:00-08:00",
    "endDate": "2017-04-24T23:00:00-08:00",
    "location": {...},
    "activity": {...},
    "organizer": {...},
    "offers": [...]
}

请注意：目前默认情况下，仅渲染 OpenActive @context。您可以提供 $schema 标志以添加 Schema.org @context。

deserialize($data)

从给定的 JSON-LD 表示中返回一个对象。

$data 参数可以是 JSON-LD 字符串，或关联数组，例如 json_encode($string, true) 的结果。

例如

use OpenActive\Models\OA\Action;

$jsonLd = '{"@context": ["https:\/\/openactive.io\/","https:\/\/openactive.io\/ns-beta"],"type": "Action","name": "Book","target": {"type": "EntryPoint","encodingType": "application\/vnd.openactive.v1.0+json","httpMethod": "POST","type": "EntryPoint","url": "https:\/\/example.com\/orders"}}';

$action = Action::deserialize($jsonLd);

var_dump($action);

将得到

object(OpenActive\Models\OA\Action)#3 (24) {
  ["name":protected]=>
  string(4) "Book"
  ["target":protected]=>
  object(OpenActive\Models\OA\EntryPoint)#2 (20) {
    ["encodingType":protected]=>
    string(36) "application/vnd.openactive.v1.0+json"
    ["httpMethod":protected]=>
    string(4) "POST"
    ["urlTemplate":protected]=>
    NULL
    ["actionApplication":protected]=>
    NULL
    ["application":protected]=>
    NULL
    ["actionPlatform":protected]=>
    NULL
    ["contentType":protected]=>
    NULL
    ["identifier":protected]=>
    NULL
    ["name":protected]=>
    NULL
    ["description":protected]=>
    NULL
    ["sameAs":protected]=>
    NULL
    ["url":protected]=>
    string(26) "https://example.com/orders"
    ["image":protected]=>
    NULL
    ["additionalType":protected]=>
    NULL
    ["subjectOf":protected]=>
    NULL
    ["mainEntityOfPage":protected]=>
    NULL
    ["potentialAction":protected]=>
    NULL
    ["disambiguatingDescription":protected]=>
    NULL
    ["alternateName":protected]=>
    NULL
    ["id":protected]=>
    NULL
  }
  ["result":protected]=>
  NULL
  ["startTime":protected]=>
  NULL
  ["actionStatus":protected]=>
  NULL
  ["agent":protected]=>
  NULL
  ["endTime":protected]=>
  NULL
  ["instrument":protected]=>
  NULL
  ["participant":protected]=>
  NULL
  ["object":protected]=>
  NULL
  ["error":protected]=>
  NULL
  ["location":protected]=>
  NULL
  ["identifier":protected]=>
  NULL
  ["description":protected]=>
  NULL
  ["sameAs":protected]=>
  NULL
  ["url":protected]=>
  NULL
  ["image":protected]=>
  NULL
  ["additionalType":protected]=>
  NULL
  ["subjectOf":protected]=>
  NULL
  ["mainEntityOfPage":protected]=>
  NULL
  ["potentialAction":protected]=>
  NULL
  ["disambiguatingDescription":protected]=>
  NULL
  ["alternateName":protected]=>
  NULL
  ["id":protected]=>
  NULL
}

修饰符

修改器允许您在库进行规范化后更改序列化的上下文。一个用例是如果您正在与不完全遵守规范或具有其他实现细节的第三方合作，这些细节需要非标准的序列化。例如，如果第三方需要一个不同的日期格式，您可以这样做

use OpenActive\Models\OA\SessionSeries;

echo SessionSeries::serialize($sessionSeries, true, false, [
    function ($class, $key, $value, $object) {
      if (!in_array($key, ['startDate', 'endDate'])) {
        return $value;
      }
      return (new \DateTime($value))->format('Y.m.d.H:i:s');
    }
]);

提供的修改器 必须 遵守此方法签名

function (string $class, string $key, mixed $value, mixed $object): mixed

每个修改器 必须 总是响应，因为修改器总是应用的。如果它不返回值，则在序列化期间将清除对象中的所有数据。您 应该 使用 $class 和 $key 参数来确定修改器是否应该适用于参数，如果不必要，则简单地返回 $value。对于需要从父对象获取更多信息的情况，也提供了 $object 参数。

修改器还可以添加到反序列化过程中，并在属性设置之前应用。这可以在库中发生变化时处理迁移路径或修复来自不兼容卖家的数据。在上面的示例中，如果第三方发送的日期格式很奇怪，您可以这样做

use OpenActive\Models\OA\SessionSeries;

$session = SessionSeries::deserialize('{...}', [
    function ($class, $key, $value, $object) {
      if (!in_array($key, ['startDate', 'endDate'])) {
        return $value;
      }
      return \DateTime::createFromFormat('Y.m.d.H:i:s', $value, new \DateTimeZone('Europe/London'));
    }
]);

示例和辅助修改器可以在 src/Modifiers 目录中找到。

贡献

安装

请注意：需要 Composer 来进行依赖管理。

git clone https://github.com/openactive/models-php.git
cd models-php
composer install

运行测试

使用 PHPUnit 运行测试。

要运行整个测试套件

./vendor/bin/phpunit

如果您想要在详细模式下运行整个测试套件

./vendor/bin/phpunit --verbose

您还可以通过指定要对其进行测试的类的相对路径来运行测试套件的一部分

./vendor/bin/phpunit --verbose tests/Unit/RpdeTest.php

有关PHPUnit可用的命令的更多信息，请参阅他们的文档

更新模型

在UPDATING.md中提供了指南

实现API

这些模型可以在实现数据API的上下文中使用。在IMPLEMENTING_APIS.md中提供了指南