Oihana PHP System

PhysicalQuantity extends QuantitativeValue

A quantity that also says what it weighs and what space it takes.

A QuantitativeValue states how much of something there is — one pallet, one box, one square meter. It does not state what that amount weighs, and a packaging chain needs it at every step : a product sold by the box does not weigh what the same product weighs by the piece.

Hence this specialization, meant for the nodes of a packaging chain such as Product::$eligibleQuantity, where each level — unit, package, parcel — carries its own mass and its own bulk :

eligibleQuantity : 1 parcel — weight 15.419 kg
  └ valueReference : 1.403 m² — weight 10.99 kg

🔑 The ratio between two levels restates the packaging chain — how many pieces fit a box, how many boxes fit a pallet — without any of it being stored twice.

It stays a QuantitativeValue : anything typed on the mirror class, such as Offer::$eligibleQuantity, accepts it unchanged, and a consumer reading only value and unitCode never notices the difference.

⚠️ Distinct from Product::$weight, the plain weight inherited from the Schema.org mirror : that one is the weight of the billed unit, with no unit stated and no level attached. This class is what lets a weight name the level it describes, which is exactly what a flat list of weights beside the chain could never guarantee.

Tags
author

Marc Alcaraz (eKameleon)

since
1.4.0

Table of Contents

Constants

CONTEXT  : string = \xyz\oihana\schema\constants\Oihana::SCHEMA
The @context of the json-ld representation of the thing.
JSON_PRIORITY_KEYS  : array<string|int, mixed> = [\org\schema\constants\Schema::AT_TYPE, \org\sc...
Defines the priority order of keys when serializing the object to JSON-LD.

Properties

$_from  : string|null
The metadata to indicates the edge 'from' identifier.
$_id  : null|string
The metadata identifier of the item.
$_key  : null|string
The metadata unique key identifier of the thing.
$_rev  : null|string
The metadata revision value of the thing.
$_to  : string|null
The metadata to indicates the edge 'to' identifier.
$active  : bool|null
The visibility flag.
$additionalProperty  : array<string|int, mixed>|null|object
A property-value pair representing an additional characteristic of the entity, e.g. a product feature or another characteristic for which there is no matching property in schema.org.
$additionalType  : array<string|int, mixed>|string|null|object
An additionalType for the item.
$alternateName  : string|object|array<string|int, mixed>|null
An alias for the item.
$created  : null|string
Date of creation of the resource.
$description  : string|object|array<string|int, mixed>|null
A short description of the item.
$disambiguatingDescription  : string|null
A sub property of description. A short description of the item used to disambiguate from other, similar items. Information from other properties (in particular, name) may be necessary for the description to be useful for disambiguation.
$hasPart  : string|Thing|array<string|int, Thing>|null
Indicates an item that this part of this item.
$id  : null|int|string
The unique identifier of the item.
$identifier  : string|null
The identifier of the item.
$image  : string|ImageObject|array<string|int, ImageObject|string>|null
The image reference of this resource.
$isPartOf  : string|Thing|array<string|int, Thing>|null
Indicates an item that this item is part of.
$license  : string|object|null
A legal document giving official permission to do something with the resource.
$mainEntityOfPage  : string|null
Indicates a page (or other CreativeWork) for which this thing is the main entity being described.
$maxValue  : null|float|int
The upper value of some characteristic or property.
$minValue  : null|float|int
The lower value of some characteristic or property.
$modified  : null|string
Date on which the resource was changed.
$name  : int|string|null
The name of the item.
$owner  : null|string|Thing
The owner of this Thing.
$potentialAction  : array<string|int, mixed>|Action|null
Indicates a potential Action, which describes an idealized action in which this thing would play an 'object' role.
$publisher  : string|array<string|int, string|Person|Organization>|Person|Organization|null
The publisher of the resource.
$sameAs  : string|array<string|int, mixed>|null
URL of a reference Web page that unambiguously indicates the item's identity.
$subjectOf  : null|string|array<string|int, mixed>|CreativeWork|Event
A CreativeWork or Event about this Thing.
$unitCode  : null|string
The unit of measurement given using the UN/CEFACT Common Code (3 characters) or a URL.
$unitText  : null|string
A string or text indicating the unit of measurement.
$url  : int|string|null
URL of the item.
$value  : mixed
The value of a QuantitativeValue or property value node.
$valueReference  : mixed
The next level of the chain — what one package holds of this level, what one pallet holds of packages.
$volume  : null|array<string|int, mixed>|int|float|QuantitativeValue
The space this quantity takes.
$weight  : null|array<string|int, mixed>|int|float|QuantitativeValue|Mass
What this quantity weighs.
$atContext  : string|null
The JSON-LD `@context` value.
$atType  : string|null
The JSON-LD `@type` value.
$DEFAULT_JSON_SERIALIZE_OPTIONS  : array<string|int, mixed>
The default static jsonSerialize options (class-level configuration).
$schemaTypeCache  : array<string, string>
Internal cache for resolved schema types.

Methods

__construct()  : mixed
Constructor to hydrate public properties from an array or stdClass.
getJsonSerializeOptions()  : array<string|int, mixed>
Returns the default JSON serialization options.
getSchemaType()  : string
Returns the fully qualified URI of the schema type.
jsonSerialize()  : array<string|int, mixed>
Serializes the current object into a JSON-LD array.
withAtContext()  : $this
Sets the internal JSON-LD `@context` attribute.
withAtType()  : $this
Sets the internal JSON-LD `@type` attribute.
withJSONLDMeta()  : $this
Initializes both JSON-LD metadata: `@type` and `@context`.

Constants

CONTEXT

The @context of the json-ld representation of the thing.

public string CONTEXT = \xyz\oihana\schema\constants\Oihana::SCHEMA

JSON_PRIORITY_KEYS

Defines the priority order of keys when serializing the object to JSON-LD.

public array<string|int, mixed> JSON_PRIORITY_KEYS = [\org\schema\constants\Schema::AT_TYPE, \org\schema\constants\Schema::AT_CONTEXT, \org\schema\constants\Schema::_KEY, \org\schema\constants\Schema::_FROM, \org\schema\constants\Schema::_TO, \org\schema\constants\Schema::ID, \org\schema\constants\Schema::NAME, \org\schema\constants\Schema::URL, \org\schema\constants\Schema::CREATED, \org\schema\constants\Schema::MODIFIED]

Keys listed here will always appear first in the serialized array, in the order specified. All remaining public properties will be sorted alphabetically after these priority keys.

This ensures that important JSON-LD metadata and system fields (like @type, @context, _key, id, url, created, modified, etc.) appear at the top of the output for consistency and readability.

Usage:

$orderedKeys = self::JSON_PRIORITY_KEYS;

Notes:

  • Can be overridden in a subclass by redefining the constant.
  • Late static binding (static::JSON_PRIORITY_KEYS) allows child classes to modify the serialization order.

List of JSON-LD keys in priority order.

Properties

$_from

The metadata to indicates the edge 'from' identifier.

public string|null $_from

$_id

The metadata identifier of the item.

public null|string $_id

$_key

The metadata unique key identifier of the thing.

public null|string $_key

$_rev

The metadata revision value of the thing.

public null|string $_rev

$_to

The metadata to indicates the edge 'to' identifier.

public string|null $_to

$active

The visibility flag.

public bool|null $active

$additionalProperty

A property-value pair representing an additional characteristic of the entity, e.g. a product feature or another characteristic for which there is no matching property in schema.org.

public array<string|int, mixed>|null|object $additionalProperty

$additionalType

An additionalType for the item.

public array<string|int, mixed>|string|null|object $additionalType

$alternateName

An alias for the item.

public string|object|array<string|int, mixed>|null $alternateName

$created

Date of creation of the resource.

public null|string $created

$description

A short description of the item.

public string|object|array<string|int, mixed>|null $description

$disambiguatingDescription

A sub property of description. A short description of the item used to disambiguate from other, similar items. Information from other properties (in particular, name) may be necessary for the description to be useful for disambiguation.

public string|null $disambiguatingDescription

$hasPart

Indicates an item that this part of this item.

public string|Thing|array<string|int, Thing>|null $hasPart

$id

The unique identifier of the item.

public null|int|string $id

$identifier

The identifier of the item.

public string|null $identifier

$isPartOf

Indicates an item that this item is part of.

public string|Thing|array<string|int, Thing>|null $isPartOf

$license

A legal document giving official permission to do something with the resource.

public string|object|null $license

$mainEntityOfPage

Indicates a page (or other CreativeWork) for which this thing is the main entity being described.

public string|null $mainEntityOfPage

$maxValue

The upper value of some characteristic or property.

public null|float|int $maxValue

$minValue

The lower value of some characteristic or property.

public null|float|int $minValue

$modified

Date on which the resource was changed.

public null|string $modified

$name

The name of the item.

public int|string|null $name

$owner

The owner of this Thing.

public null|string|Thing $owner

Represents any entity (person, organization, system, or other object) that can be considered the possessor of this Thing.

$potentialAction

Indicates a potential Action, which describes an idealized action in which this thing would play an 'object' role.

public array<string|int, mixed>|Action|null $potentialAction

$sameAs

URL of a reference Web page that unambiguously indicates the item's identity.

public string|array<string|int, mixed>|null $sameAs

E.g. the URL of the item's Wikipedia page, Wikidata entry, or official website.

$subjectOf

A CreativeWork or Event about this Thing.

public null|string|array<string|int, mixed>|CreativeWork|Event $subjectOf

$unitCode

The unit of measurement given using the UN/CEFACT Common Code (3 characters) or a URL.

public null|string $unitCode

Other codes than the UN/CEFACT Common Code may be used with a prefix followed by a colon.

$unitText

A string or text indicating the unit of measurement.

public null|string $unitText

Useful if you cannot provide a standard unit code for unitCode.

$url

URL of the item.

public int|string|null $url

$value

The value of a QuantitativeValue or property value node.

public mixed $value

$valueReference

The next level of the chain — what one package holds of this level, what one pallet holds of packages.

public mixed $valueReference

Redeclared from ValueTrait for the sole purpose of the attribute : without it Reflection::hydrate() types the head of the chain and leaves everything below it a raw array, so a consumer would read ->weight at the first level and ['weight'] at the second — on a structure whose whole point is the ratio between two levels. The type is left as mixed, exactly as inherited.

⚠️ A decision, stated plainly : Schema.org lets valueReference hold things that are not quantities at all — an enumeration, a qualitative value. On this class it is the next packaging level, and nothing else. That is what the class exists for.

⚠️ The constructor assigns raw and honours no attribute : use hydratePhysicalQuantity() on that path.

Tags
since
1.4.0
Attributes
#[HydrateAs]
\xyz\oihana\schema\products\PhysicalQuantity::class

$volume

The space this quantity takes.

public null|array<string|int, mixed>|int|float|QuantitativeValue $volume

A plain number when the unit is implicit, a QuantitativeValue when it is stated ({ value: 0.0312, unitCode: "MTQ" }) ; an array is hydrated as the latter, and sits there untouched until it is — the constructor assigns raw, #[HydrateAs] acting through Reflection::hydrate() alone.

Tags
since
1.4.0
Attributes
#[HydrateAs]
\org\schema\QuantitativeValue::class

$weight

What this quantity weighs.

public null|array<string|int, mixed>|int|float|QuantitativeValue|Mass $weight

The same union as BusinessDocument::$weight, so a weight reads the same wherever it is met : a plain number when the unit is implicit, a QuantitativeValue when it is stated ({ value: 15.419, unitCode: "KGM" }) ; an array is hydrated as the latter, and sits there untouched until it is.

Tags
since
1.4.0
Attributes
#[HydrateAs]
\org\schema\QuantitativeValue::class

$atContext

The JSON-LD `@context` value.

protected string|null $atContext = null

Default is https://schema.org.

$atType

The JSON-LD `@type` value.

protected string|null $atType = null

This can be manually set or automatically inferred from the class name.

$DEFAULT_JSON_SERIALIZE_OPTIONS

The default static jsonSerialize options (class-level configuration).

protected static array<string|int, mixed> $DEFAULT_JSON_SERIALIZE_OPTIONS = []

$schemaTypeCache

Internal cache for resolved schema types.

private static array<string, string> $schemaTypeCache = []

Methods

__construct()

Constructor to hydrate public properties from an array or stdClass.

public __construct([array<string|int, mixed>|object|null $init = null ]) : mixed

This allows objects to be quickly populated with associative data without manually setting each property.

Parameters
$init : array<string|int, mixed>|object|null = null

A data array or object used to initialize the instance. Keys must match public property names.

Tags
throws
ReflectionException
example 
use org\schema\Person;
use org\schema\constants\Prop;

$person = new Person
([
    Prop::NAME => 'Jane Doe',
    Prop::URL  => 'https://example.com/janedoe'
]);

echo $person->name; // Outputs: Jane Doe

getJsonSerializeOptions()

Returns the default JSON serialization options.

public getJsonSerializeOptions() : array<string|int, mixed>

This method determines how the jsonSerialize() output is reduced or compressed, etc. It can be overridden in child classes to customize serialization behavior.

Return values
array<string|int, mixed> —

Returns the reduction/compression options for JSON serialization.

getSchemaType()

Returns the fully qualified URI of the schema type.

public static getSchemaType() : string

This method combines the class's CONTEXT constant with its short name to produce a globally unique identifier for the entity type.

  • It uses Late Static Binding to ensure the correct context is retrieved even when called from an inherited class (e.g., Corporation vs. Affiliate).
  • Performance Optimization: Results are stored in a static cache ($schemaTypeCache) to avoid redundant Reflection calls during the same execution lifecycle.
Return values
string —

The absolute URI of the type (e.g., "https://schema.org/Thing"). ** @example

echo Thing::getSchemaType();      // https://schema.org/Thing
echo Affiliate::getSchemaType();  // https://schema.oihana.xyz/Pagination

jsonSerialize()

Serializes the current object into a JSON-LD array.

public jsonSerialize() : array<string|int, mixed>

Includes public properties, the JSON-LD @context and @type. Null values are automatically removed.

Tags
throws
ReflectionException

If reflection fails when accessing properties.

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

$person = new Person
([
    Prop::NAME => 'John Smith',
    Prop::ID   => 'jsmith-001'
]);

echo json_encode($person, JSON_PRETTY_PRINT);

Output:

{
   "@type": "Person",
   "@context": "https://schema.org",
   "id": "jsmith-001",
   "name": "John Smith"
}
Return values
array<string|int, mixed> —

JSON-LD representation of the object.

withAtContext()

Sets the internal JSON-LD `@context` attribute.

public withAtContext(string $context) : $this

Useful if you need a custom JSON-LD context.

Parameters
$context : string

Optional JSON-LD context.

Return values
$this

withAtType()

Sets the internal JSON-LD `@type` attribute.

public withAtType(string $type) : $this

Allows overriding the default type inferred from the class.

Parameters
$type : string

Optional JSON-LD type

Return values
$this

withJSONLDMeta()

Initializes both JSON-LD metadata: `@type` and `@context`.

public withJSONLDMeta([string|null $atType = null ][, string|null $atContext = null ]) : $this

Can be called from constructor or later to override default values.

Parameters
$atType : string|null = null

Optional JSON-LD type

$atContext : string|null = null

Optional JSON-LD context

Return values
$this
On this page

Search results