Download the PHP package oihana/php-schema without Composer

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. Schema::NAME)
• 📚 Extensible architecture for custom ontologies
• 🔐 Support for ArangoDB metadata (_id, _key, _rev, _from, _to)

📦 Installation

Requires PHP 8.4+

Install via Composer:

🚀 Quick Example

Simple usage

JSON-LD output

🗂️ Schemas overview

The library exposes three top-level namespaces. Each row below links to a dedicated wiki guide (English / Français) that lists the classes, gives a code example and points to the source.

Every entity extends org\schema\Thing, so they all share the same JSON-LD serialization, hydration and ArangoDB metadata. Sub-namespaces override the CONTEXT constant so downstream consumers can tell them apart:

🧠 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:

`

🔐 Safe Property Access

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

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

📚 Documentation

Two complementary sets of documentation are available:

• 📖 Auto-generated API reference (every class, property and method) — published at https://bcommebois.github.io/oihana-php-schema. Regenerate it locally with composer doc.
• ✍️ Hand-written wiki (concepts, guides, walkthroughs) — bilingual EN/FR under wiki/:
  • 🇬🇧 Getting started)
  • 🇫🇷 Démarrage rapide)

While the wiki grows, you can also explore the following namespaces directly:

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

✅ Running Unit Tests

To run all tests:

To run a specific test file:

🧾 License

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

👤 About the author

• Author : Marc ALCARAZ (aka eKameleon)
• Mail : [email protected]
• Website : http://www.ooop.fr

🛠️ Generate the Documentation

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

Usage

Run the command :

🧩 Advanced Usage

Union-typed properties

Some properties accept multiple types. For instance, publisher may be a string, a Person, or an Organization.

Arrays and nested entities

You can compose objects with arrays of other entities, leveraging the public-typed properties.

JSON-LD metadata for ArangoDB

Base Thing supports ArangoDB-style metadata fields to facilitate graph storage: _key, _id, _rev, _from, _to.

Deep/recursive hydration

The constructor copies provided values into public properties.

For deep graphs and automatic casting, you can rely on the internal reflection utilities exposed by oihana/php-reflect (see developer docs). A typical approach is to call a reflection-based hydrate() to materialize nested arrays into value objects.

🧱 Extending the Library

Define your own types by extending org\schema\Thing or a more specific class, and add your public-typed properties. You can also define constants alongside org\schema\constants\Schema for safer access.

⚙️ Installation Notes

• This package requires PHP 8.4+.
• It depends on oihana/php-core and oihana/php-reflect. If your project enforces stable versions only, you may need to allow dev versions while these libraries are pre-release:
  • In your root composer.json: set "minimum-stability": "dev" and "prefer-stable": true if needed.

🤝 Contributing

Contributions are welcome! Please:

• Open an issue to discuss significant changes before submitting a PR.
• Add tests when fixing a bug or adding a feature.
• Keep code style consistent and types explicit.

Local setup:

🔒 Security

If you discover a security vulnerability, please email [email protected]. Do not open a public issue for security reports.

📜 Changelog

See CHANGELOG.md for notable changes.

🔗 Related Packages

• oihana/php-core – core helpers and utilities used by this library
• oihana/php-reflect – reflection and hydration utilities

❓ FAQ

• Why JSON-LD?
  It’s a web-native, schema-friendly format that plays well with linked data and search engines.
• Can I output plain arrays?
  Yes, jsonSerialize() returns arrays that you can pass to any JSON encoder.
• How to ignore nulls?
  Serialization automatically removes null values.

🧮 JSON Schema Generation

Generate JSON Schemas from the typed public properties of your classes.

Experimental — local tooling only. schemas/ is gitignored: the generated files are not committed and nothing in the library consumes them. Regenerate on demand. The generator is known to be incomplete (see Known limitations below) and its output should not be relied upon for validation yet.

• Single class (example: Place):

• All classes under src/org/schema:

Details:

• Schemas are written to schemas/*.schema.json.
• Union types are represented as oneOf; class types are emitted as $ref into local $defs.
• Requires Composer autoload (run composer dump-autoload -o if classes are not found).

Output layout and cleanup

• Namespaces map to folders under schemas/:
  • org\schema\... → schemas/org/schema/.../*.schema.json
  • xyz\oihana\schema\... → schemas/xyz/oihana/schema/.../*.schema.json
• Running composer schemas:all first deletes previous *.schema.json under schemas/ to avoid stale files, then regenerates everything.

Array unions handling

When a property type includes array plus other types (e.g. string|ImageObject|array<ImageObject|string>|null), the generator emits:

• direct options for string, ImageObject, null (if present)
• and an array variant whose items use a oneOf of the non-array types (here ImageObject and string).

Known limitations

The generator has not been finished; the following are known and unfixed:

• composer schemas:all aborts with a fatal error on the function-only files under helpers/hydrate/ (class_exists() re-includes them). Since the script deletes every *.schema.json before generating, an aborted run leaves the output directory half-empty.
• Generated schemas set additionalProperties: false but omit the @type and @context keys that jsonSerialize() always emits, so no document produced by this library validates against its own schema.
• Union types are emitted as oneOf, which requires exactly one matching branch. A union containing both int and float yields both an integer and a number branch, and can therefore never be satisfied — anyOf is the correct keyword here.
• Simple nullable types (e.g. ?bool) lose their null option through a dead condition, so null is rejected where the PHP type allows it.
• $defs entries are untyped stubs, and every $id uses https://schema.oihana.xyz/{ShortName}.json — including for org\schema types, and with collisions between identical short names in different namespaces.