PHPackages oihana/php-schema - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. oihana/php-schema ActiveLibrary[Utility & Helpers](/categories/utility) oihana/php-schema ================= The Oihana PHP Schema library 1.0.1(6mo ago)02806MPL-2.0PHPPHP >=8.4CI passing Since Aug 13Pushed 3mo agoCompare [ Source](https://github.com/BcommeBois/oihana-php-schema)[ Packagist](https://packagist.org/packages/oihana/php-schema)[ Docs](https://github.com/BcommeBois/oihana-php-schema)[ RSS](/packages/oihana-php-schema/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (5)Versions (3)Used By (6) Oihana PHP - Schema =================== [](#oihana-php---schema) [![Oihana PHP Schema](https://raw.githubusercontent.com/BcommeBois/oihana-php-schema/refs/heads/main/assets/images/oihana-php-schema-logo-inline-512x160.png)](https://raw.githubusercontent.com/BcommeBois/oihana-php-schema/refs/heads/main/assets/images/oihana-php-schema-logo-inline-512x160.png) Oihana Schema is a PHP library that provides an object-oriented implementation of the [Schema.org](https://www.schema.org) vocabulary. It is designed to encapsulate structured data using strongly typed value objects, with automatic serialization and hydration features. [![Latest Version](https://camo.githubusercontent.com/bacf52d00f26dc8040e4940a11d57eb5e3ef6ccf962f11928e71199cc5ac32cf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f6968616e612f7068702d736368656d612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/oihana/php-schema) [![Total Downloads](https://camo.githubusercontent.com/17bf0a15dc8ca2643962eb95d25f90fb070881a0691b34abc5297e705712650a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f6968616e612f7068702d736368656d612e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/oihana/php-schema) [![License](https://camo.githubusercontent.com/f84ba0fdd281acf3683404005aae5bda4c3766b65ad948477c53dc13bf7e4ead/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6f6968616e612f7068702d736368656d612e7376673f7374796c653d666c61742d737175617265)](LICENSE) 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 -------------- [](#-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 -------------- [](#-installation) > **Requires [PHP 8.4+](https://php.net/releases/)** Install via [Composer](https://getcomposer.org): ``` composer require oihana/php-schema ``` ๐Ÿš€ Quick Example --------------- [](#-quick-example) Simple usage ``` use org\schema\Person; use org\schema\PostalAddress; use org\schema\constants\Schema; $person = new Person ([ Schema::ID => '2555', Schema::NAME => 'John Doe', Schema::ADDRESS => new PostalAddress ([ Schema::STREET_ADDRESS => '2 chemin des Vergers', Schema::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 ----------------------- [](#-internal-architecture) ### Base class: Thing [](#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 [](#recursive-hydration) The internal **[Reflection::hydrate()](https://github.com/BcommeBois/oihana-php-system/blob/00552f088022ee2af836b011d0efc0c69ffeab63/src/oihana/reflections/Reflection.php#L42)** 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 ---------------------- [](#-safe-property-access) The org\\schema\\constants\\Schema class contains constant names for every property in the **Schema.org** ontology and its extensions: ``` use org\schema\constants\Schema; use org\schema\Event; $event = new Event ([ Schema::NAME => 'Oihana Conf 2025', Schema::LOCATION => new Place([ Schema::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 --------------- [](#-documentation) Full project documentation is available at: ๐Ÿ‘‰ 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 ๐Ÿ‡ซ๐Ÿ‡ท xyz\\oihana Namespace (oihana.xyz extensions) ------------------------------------------------ [](#-xyzoihana-namespace-oihanaxyz-extensions) In addition to the Schema.org core under `org\\schema`, this library provides an extension namespace for Oihana-specific needs used in the ecosystem: `xyz\\oihana\\schema`. What you will find there: - Value objects for domain-specific concepts (e.g., `xyz\\oihana\\schema\\Pagination`). - A constants container `xyz\\oihana\\schema\\constants\\Oihana` exposing safe property names via traits (e.g., `Pagination` constants). Example: model pagination parameters with JSON-LD support ``` use xyz\oihana\schema\Pagination; use xyz\oihana\schema\constants\Oihana; $pagination = new Pagination ([ Oihana::LIMIT => 50, Oihana::PAGE => 2, ]); // JSON-LD with a dedicated context for Oihana extensions echo json_encode($pagination, JSON_UNESCAPED_SLASHES); // {"@type":"Pagination","@context":"https://schema.oihana.xyz","limit":50,"page":2} ``` Key points: - `Pagination` extends `org\schema\Intangible` and integrates seamlessly with the rest of the model. - `Pagination::CONTEXT` defaults to `https://schema.oihana.xyz` to distinguish Oihana extensions. - Use `xyz\oihana\schema\constants\Oihana` to reference property names safely: `Oihana::LIMIT`, `Oihana::OFFSET`, `Oihana::MAX_LIMIT`, `Oihana::MIN_LIMIT`, `Oihana::NUMBER_OF_PAGES`, `Oihana::PAGE`. โœ… Running Unit Tests -------------------- [](#-running-unit-tests) To run all tests: ``` composer test ``` To run a specific test file: ``` composer test ./tests/org/schema/ThingTest.php composer test ./tests/xyz/oihana/schema/PaginationTest.php ``` ๐Ÿงพ License --------- [](#-license) This project is licensed under the [Mozilla Public License 2.0 (MPL-2.0)](https://www.mozilla.org/en-US/MPL/2.0/). ๐Ÿ‘ค About the author ------------------ [](#-about-the-author) - Author : Marc ALCARAZ (aka eKameleon) - Mail : - Website : ๐Ÿ› ๏ธ Generate the Documentation ----------------------------- [](#๏ธ-generate-the-documentation) We use [phpDocumentor](https://phpdoc.org/) to generate the documentation into the ./docs folder. ### Usage [](#usage) Run the command : ``` composer doc ``` ๐Ÿงฉ Advanced Usage ---------------- [](#-advanced-usage) ### Union-typed properties [](#union-typed-properties) Some properties accept multiple types. For instance, `publisher` may be a `string`, a `Person`, or an `Organization`. ``` use org\schema\CreativeWork; use org\schema\Person; use org\schema\Organization; use org\schema\constants\Schema; $post = new CreativeWork ([ Schema::NAME => 'Release Notes', Schema::PUBLISHER => new Organization([ Schema::NAME => 'Oihana' ]) ]); ``` ### Arrays and nested entities [](#arrays-and-nested-entities) You can compose objects with arrays of other entities, leveraging the public-typed properties. ``` use org\schema\Thing; use org\schema\constants\Schema; $parent = new Thing ([ Schema::NAME => 'Bundle', Schema::HAS_PART => [ new Thing([ Schema::NAME => 'Part A' ]), new Thing([ Schema::NAME => 'Part B' ]), ], ]); ``` ### JSON-LD metadata for ArangoDB [](#json-ld-metadata-for-arangodb) Base `Thing` supports ArangoDB-style metadata fields to facilitate graph storage: `_key`, `_id`, `_rev`, `_from`, `_to`. ``` use org\schema\Thing; $edge = new Thing ([ '_from' => 'users/2555', '_to' => 'groups/42', ]); ``` ### Deep/recursive hydration [](#deeprecursive-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 ----------------------- [](#-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. ``` namespace app\domain; use org\schema\Thing; class CustomAsset extends Thing { public ?string $slug; public ?string $category; } ``` โš™๏ธ Installation Notes --------------------- [](#๏ธ-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 -------------- [](#-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: ``` composer install composer test composer doc ``` ๐Ÿ”’ Security ---------- [](#-security) If you discover a security vulnerability, please email `marc@ooop.fr`. Do not open a public issue for security reports. ๐Ÿ“œ Changelog ----------- [](#-changelog) See `CHANGELOG.md` for notable changes. ๐Ÿ”— Related Packages ------------------ [](#-related-packages) - [oihana/php-core](https://github.com/BcommeBois/oihana-php-core) โ€“ core helpers and utilities used by this library - [oihana/php-reflect](https://github.com/BcommeBois/oihana-php-reflect) โ€“ reflection and hydration utilities โ“ FAQ ----- [](#-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 ------------------------ [](#-json-schema-generation) Generate JSON Schemas from the typed public properties of your classes. - Single class (example: Place): ``` composer schema:place ``` - All classes under `src/org/schema`: ``` composer schemas:all ``` 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 [](#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 [](#array-unions-handling) When a property type includes `array` plus other types (e.g. `string|ImageObject|array|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`). ### Health Score 41 โ€” FairBetter than 89% of packages Maintenance74 Regular maintenance activity Popularity13 Limited adoption so far Community13 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits โ€” single point of failure How is this calculated?**Maintenance (25%)** โ€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** โ€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** โ€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** โ€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~77 days Total 2 Last Release 196d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/d234506e51778dd3d1d61b6c2af6f294ff963651b4aa509b595d3d2a77b7d89b?d=identicon)[ooop](/maintainers/ooop) --- Top Contributors [![ekameleon](https://avatars.githubusercontent.com/u/749032?v=4)](https://github.com/ekameleon "ekameleon (150 commits)") --- Tags phpschema ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/oihana-php-schema/health.svg) ``` [![Health](https://phpackages.com/badges/oihana-php-schema/health.svg)](https://phpackages.com/packages/oihana-php-schema) ``` ### Alternatives [imanghafoori/laravel-anypass A minimal yet powerful package to help you in development. 21421.6k](/packages/imanghafoori-laravel-anypass)[withcandour/aardvark-seo Save time and get your Statamic site to rank better with the SEO addon for Statamic. 13128.3k](/packages/withcandour-aardvark-seo) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)