Download the PHP package romanko/object-graph without Composer

Object Graph

Introduction

Object Graph wraps a plain PHP object (e.g., JSON object) and exposes a value object (a GraphNode instance) with a predefined set of properties.

Object Graph can also be used to introduce compatibility between different versions of a JSON payload and produce a GraphNode with the common set of properties which suits both payloads.

This library a is written-from-the-ground version of a project initially developed for the NewsCorp Australia. Kudos to Juan Zapata (@juankk), Salvatore Balzano (@salvo1404) and Michael Chan (@michaelChanNews) for their time and contribution to this library.

Table of Contents

• Walk through
  • Model
  • Schema
  • Strict Schema
  • A word on nested objects and field resolvers
  • Resolver
  • Context

Walk through

Let's jump straight to the business. Imaging that we have two versions of a payload from our User API:

/v1/user/123:

/v2/user/123:

Let's create a User model with this set of properties, build a Schema for each payload version and, finally, build a resolver which will automatically apply corresponding Schema to a particular payload version and produce us a User mode.

• Model: a instance of a GraphNode, that represents a plain PHP object, where the object fields are defined as Model properties;
• Schema: contains a list of Model properties / fields; resolvers, default values, PHP type casting configuration for each field and more;
• Resolver: performs magic and builds a Model from a plain PHP object;
• Context: allows to share variables between feilds resolvers.

These are the main components of the ObjectGraph library.

Model

First we start with modeling what properties our Model should have:

A Model class must extend GraphNode and list properties in the class header docblock. This will enabled IDE auto-suggestion as well.

Note that in this release, Model is immutable and an attempt to set or unset a value on the Model will throw an exception.

Your Model class can extend another Model class, also contain API, constants as a normal PHP class, which it really is.

Model properties can be accessed as PHP object properties $user->dateOfBirth or as array elements $article['heraldsun.com.au']->titleOverride.

Model API:

• Model::getData(), returns original underlying plain PHP object
• Model::asArray(), transforms model to an array, according to the fields defined on a Schema;
• Model::asObject(), transforms model to an object, according to the fields defined on a Schema;

Schema

Next step, we are going to define a schema for each of the payload version. A schema class must extend Schema.

There are a few useful methods in a Schema you can or may wish to override:

• Schema::getGraphNodeClassName(), this method must return a model class name, in our case it is User.
• Schema::isStrict(), must return a boolean flag which indicates whether this schema is strict or not. See below.
• Schema::build(), adding schema fields and potentially other configuration work must happen inside this method, which acts as a custom class __constructor for the Schema class.

Strict Schema

When a schema is strict, then you can only access Model fields defined on a Scheme instance. Trying to access a field which exists on a data source, but not defined on a schema, will give you NULL.

When transforming a Model to an array or an object, the resulting data will contain only fields defined on a strict schema. If schema is not strict then the resulting data will contain a combination of all fields defined on the source object and schema.

By default the Schema is not strict.

Version 1

Version 2

A word on nested objects and field resolvers

The first argument a field resolver function receives is always a parent object the field belongs to.

As an example, there is a source PHP object:

• social field resolver function will receive the root object;
• facebook field resolver function will receive the object assigned to social

Each nested object can have its own Schema, which can define a custom Model class to use.

Resolver

We can atually start using the above right away:

However, it is not fun, because we still need to decide which schema to use with the data. Let's automate it:

And try now:

Context

Context is used to pass external variables to field resolvers:

• the Root object will receive a copy of the global Context; and
• its nested objects will receive a copy of the Root object Context

Note: Context is designed to contain scalar variables and does not support deep cloning. If there is an object stored in the Context, then when Context is cloned, both cloned and original Contexts will retain references to each other.

There is a JSON with language specific greetings and in our Object Graph Model we'd like to use Australian English where it is possible:

The desired locale can be set on the Context and then accessed in the field resolver:

and within the "sayHi" field resolver: