Download the PHP package playfinder/openactive-models without Composer

models-php

PHP Models for the OpenActive Opportunity and Booking Specifications

OpenActive aims to provide model files for all classes defined in its Opportunity and Booking specifications across the PHP, Ruby, and .NET languages. This repository is intended for the PHP files; see also the Ruby and .NET implementations.

Table of Contents

• Requirements
• Installation

• Usage

  • Models

    • OpenActive
    • Schema.org
  • RPDE
  • Enums
  • Serialization
    • serialize($obj, $prettyPrint = false)
    • deserialize($data)
    • Modifiers
• Contributing

Requirements

This project requires PHP >=5.6.

Installation

To install via Composer, from terminal, run:

Usage

This package provides PHP models for the OpenActive specifications.

It also provide a set of models for the schema.org specifications.

Finally it provides a set of classes to handle OpenActive's RPDE data feeds.

Models

The models are included under the \OpenActive\Models namespace.

You can instantiate a new model, passing an associative array, where the key is the attribute name, and the value is the attribute value.

For example, from your PHP application, run:

Please note that type enforcement is in place whenever creating a new model.

For example, providing a string to the target attribute in the example above will result in an \OpenActive\Exception\InvalidArgumentException being thrown.

A set of getters and setters for all the attributes is provided. Type enforcement is in place for setters too.

OpenActive

The OpenActive models are included under the \OpenActive\Models\OA namespace.

To instantiate a new one, see the models section, making sure you are using the right namespace from your model.

Schema.org

The Schema.org models are included under the \OpenActive\Models\SchemaOrg namespace.

To instantiate a new one, see the models section, making sure you are using the right namespace from your model.

RPDE

RpdeItem & RpdeBody are the main classes to use when generating a page for an RPDE feed.

Feed items

RpdeItem is used to create each individual item for a page. It includes a data attribute to which should be an instance of an OA Model along with metadata (id, modified, state and kind). It is left to each application developer to generate these models and metadata.

e.g. a session series collection

Feed page

RpdeBody is then used to wrap a collection of items and provide the licence and next entries expected from an RPDE page. To help keep pages valid and create an correct next link, use RpdeBody::createFromNextChangeNumber or RpdeBody::createFromModifiedId to create an RPDE page feed out of an array of RpdeItems (the constructor has been made private).

RpdeBody::createFromNextChangeNumber will check that all feed items do indeed come after the $changeNumber argument provided. It will contruct the next link based on the modified value of the newest feed item and the provided $feedBaseUrl argument.

e.g.

RpdeBody::createFromModifiedId will check that all feed items do indeed come after the $id and $modified arguments provided. It will contruct the next link based on the id and modified value of the newest feed item and the provided $feedBaseUrl argument.

e.g.

To override the default licence:

Serializing the feed page

Finally the feed page can then be serialized with Serialize RpdeBody::serialize($feedPage) which will also take care of serializing the each feed item's data attribute as JSON-LD.

See the OpenActive's guide to publishing data and the RPDE specification for more details about RPDE feeds.

Enums

Each enum is represented by a class which contains a constant for each available value.

e.g. Adding days of the week to a Schedule:

Serialization

This package provides support for JSON-LD serialization/deserialization of models and and for the \OpenActive\Rpde\RpdeBody object.

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

Returns the JSON-LD string representation of the given object $obj.

An additional parameter $prettyPrint is available to return a JSON-LD string in a human-readable format.

An example, using the \OpenActive\Models\OA\SessionSeries defined above:

Will output:

Please note: at the moment by default, only the OpenActive @context is rendered in the serialization output. You may supply the $schema flag to add the Schema.org @context.

deserialize($data)

Returns an object from a given JSON-LD representation.

The $data argument can be a JSON-LD string, or an associative array, for example as a result of json_encode($string, true).

For example:

Will result in:

Modifiers

Modifiers allow you to change the serialized context after it has been normalized by the library. An example use-case for this is if you are working with a third party who does not completely adhere to the specification, or has other implementation details which require non-standard serialization. For example, if the third party requires a different date format you could do this:

The given modifiers MUST adhere to this method signature:

Each modifier MUST always respond with a value, as the modifiers are always applied. If it does not return a value all the data in your object will be wiped during serialization. You SHOULD use the $class and $key parameters to determine if the modifier should run for the parameter, and simply return the $value if it is not necessary. The $object parameter is also available for modifiers which require further information from the parent object.

Modifiers can also be added to the Deserialization process, and are applied before the property is set. This can be useful when having to handle migration paths as changes happen in the library, or to fix data coming from an incompatible seller. Building on the previous example, if the third party in this case is sending dates in an odd format you could do this:

Example & helper modifiers can be found in the src/Modifiers directory.

Contributing

Installation

Please note: Composer is required for dependency management.

Running Tests

PHPUnit is used to run tests.

To run the whole suite:

If you want to run the whole suite in verbose mode:

You can also run a section of the suite by specifying the class's relative path on which you want to perform tests:

For additional information on the commands available for PHPUnit, consult their documentation

Updating models

A guide is provided in UPDATING.md

Implementing APIs

These models can be used in the context of implementing an data API. A guide is provided in IMPLEMENTING_APIS.md