oihana/php-schema

The Oihana PHP Schema library

dev-main 2025-07-23 14:15 UTC

This package is auto-updated.

Last update: 2025-07-23 14:15:55 UTC


README

Oihana PHP Schema

Oihana Schema is a PHP library that provides an object-oriented implementation of the Schema.org vocabulary. It is designed to encapsulate structured data using strongly typed value objects, with automatic serialization and hydration features.

This library is ideal for representing database records or REST API resources in a structured, semantically rich way, compatible with JSON-LD and linked data ecosystems.

โœจ Key Features

  • โœ”๏ธ Full modeling of Schema.org entities
  • ๐Ÿงฉ Automatic JSON-LD serialization (JsonSerializable)
  • ๐Ÿช„ Recursive object hydration (including nested types and union types)
  • ๐Ÿง  Internal reflection system (oihana\reflections)
  • ๐ŸŽฏ Safe property access via constants (e.g. Prop::NAME)
  • ๐Ÿ“š Extensible architecture for custom ontologies
  • ๐Ÿ” Support for ArangoDB metadata (_id, _key, _rev, _from, _to)

๐Ÿ“ฆ Installation

Requires PHP 8.4+

Install via Composer:

composer require oihana/php-schema

๐Ÿš€ Quick Example

Simple usage

use org\schema\Person;
use org\schema\PostalAddress;
use org\schema\constants\Prop;

$person = new Person
([
    Prop::ID      => '2555',
    Prop::NAME    => 'John Doe',
    Prop::ADDRESS => new PostalAddress
    ([
        Prop::STREET_ADDRESS => '2 chemin des Vergers',
        Prop::POSTAL_CODE    => '49170'
    ])
]);

echo json_encode( $person , JSON_PRETTY_PRINT ) ;

JSON-LD output

{
  "@type": "Person",
  "@context": "https://schema.org",
  "id": "2555",
  "name": "John Doe",
  "address": {
    "@type": "PostalAddress",
    "@context": "https://schema.org",
    "streetAddress": "2 chemin des Vergers",
    "postalCode": "49170"
  }
}

๐Ÿง  Internal Architecture

Base class: Thing

All entities extend the base class org\schema\Thing, which includes common Schema.org and metadata properties, as well as serialization logic:

The ThingTrait handles:

  • Dynamic constructor from arrays or objects
  • JSON-LD serialization via jsonSerialize()
  • Reflection-based helpers from ReflectionTrait

Recursive Hydration

The internal Reflection::hydrate() method builds full object graphs from associative arrays, including nested value objects and union types:

$person = $reflection->hydrate
([
    'name'    => 'Alice',
    'address' => [ 'streetAddress' => '123 Lilac Street' ]
], Person::class ) ;

๐Ÿ” Safe Property Access

The org\schema\constants\Prop class contains constant names for every property in the Schema.org ontology and its extensions:

use org\schema\constants\Prop;

$event = new Event
([
    Prop::NAME     => 'Oihana Conf 2025',
    Prop::LOCATION => new Place([ Prop::NAME => 'Nantes' ])
]);

Properties are grouped by logical trait namespaces (e.g. Thing, Person, Event, etc.) for auto-completion and modularity:

trait Thing 
{
    const string NAME = 'name';
    const string URL  = 'url';
    const string ID   = 'id';
    // ...
}

๐Ÿ“š Documentation

Full project documentation is available at:
๐Ÿ‘‰ https://bcommebois.github.io/oihana-php-schema

A complete developer guide will be available soon, including:

  • UML diagrams
  • Object maps and relationships
  • Auto-generated property references

In the meantime, explore the following namespaces:

  • org\schema\ for value objects
  • org\schema\traits for logic traits
  • org\schema\constants for property constants

โœ… Running Unit Tests

To run all tests:

composer run-script test

To run a specific test file:

composer run test ./tests/schema/ThingTest.php

๐Ÿงพ Licence

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

๐Ÿ‘ค About the author

๐Ÿ› ๏ธ Generate the Documentation

We use phpDocumentor to generate the documentation into the ./docs folder.

Usage

Run the command :

composer doc