oihana / php-schema
The Oihana PHP Schema library
Requires
- php: >=8.4
- oihana/php-core: dev-main
- oihana/php-system: dev-main
Requires (Dev)
- nunomaduro/collision: ^8.8
- phpdocumentor/shim: ^3.8
- phpunit/phpunit: ^12
This package is auto-updated.
Last update: 2025-07-23 14:15:55 UTC
README
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
- Author : Marc ALCARAZ (aka eKameleon)
- Mail : marc@ooop.fr
- Website : http://www.ooop.fr
๐ ๏ธ Generate the Documentation
We use phpDocumentor to generate the documentation into the ./docs folder.
Usage
Run the command :
composer doc