ProductStatistics extends Statistics uses HasTradingMeasures, HasTradingMeasuresTrait
What one article traded over one year.
A Statistics record whose subject is a Product, carrying the same ten measures as every other family (HasTradingMeasures). Read on the sale side it answers what an article brings in and at which margin ; on the purchase side, what it costs to keep in stock — the same record, told by Statistics::$direction.
🔑 This is the one family where quantity is worth its total. Elsewhere a
quantity spanning several articles adds square metres to cubic metres to
pieces ; here every figure counts the same article in the same unit, and the
run and its total both mean something.
It carries no dimension of its own : what an article belongs to — its family, its category — lives on the article, and stays there. The company the figures were measured for is on the record already, as Statistics::$assignedCompany.
Tags
Table of Contents
Constants
- ABOUT : string = 'about'
- ASSIGNED_COMPANY : string = 'assignedCompany'
- AVERAGE_COST : string = 'averageCost'
- AVERAGE_MARGIN : string = 'averageMargin'
- CONTEXT : string = \xyz\oihana\schema\constants\Oihana::SCHEMA
- The @context of the json-ld representation of the thing.
- COST_PRICE : string = 'costPrice'
- DIRECTION : string = 'direction'
- GROSS_MARGIN : string = 'grossMargin'
- 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.
- OBSERVATION_PERIOD : string = 'observationPeriod'
- PURCHASE_COST : string = 'purchaseCost'
- PURCHASE_MARGIN : string = 'purchaseMargin'
- QUANTITY : string = 'quantity'
- REVENUE : string = 'revenue'
- VOLUME : string = 'volume'
- WEIGHT : string = 'weight'
- YEAR : string = 'year'
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.
- $about : null|int|string|array<string|int, mixed>|Thing
- The article these figures are about.
- $active : bool|null
- The visibility flag.
- $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.
- $assignedCompany : null|int|string|array<string|int, mixed>|Organization
- The company these figures were measured for.
- $averageCost : null|array<string|int, mixed>|ObservationSeries
- The trade valued at the weighted average cost of what was sold.
- $averageMargin : null|array<string|int, mixed>|ObservationSeries
- The margin over {@see HasTradingMeasures::$averageCost}.
- $costPrice : null|array<string|int, mixed>|ObservationSeries
- The trade valued at cost price — the purchase price with the charges that ride along with it loaded on.
- $created : null|string
- Date of creation of the resource.
- $description : string|object|array<string|int, mixed>|null
- A short description of the item.
- $direction : null|string|BusinessDocumentDirection
- Which side of the trade these figures were measured on — sales or purchases, from the operator's point of view.
- $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.
- $grossMargin : null|array<string|int, mixed>|ObservationSeries
- The margin over {@see HasTradingMeasures::$costPrice} — the gross margin.
- $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.
- $modified : null|string
- Date on which the resource was changed.
- $name : int|string|null
- The name of the item.
- $observationPeriod : null|string
- The step the series inside this record are cut at, as an ISO 8601 duration — `P1M` for one value a month, `P1W` a week, `P1D` a day.
- $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.
- $purchaseCost : null|array<string|int, mixed>|ObservationSeries
- The trade valued at the price paid for the goods.
- $purchaseMargin : null|array<string|int, mixed>|ObservationSeries
- The margin over {@see HasTradingMeasures::$purchaseCost}.
- $quantity : null|array<string|int, mixed>|ObservationSeries
- How much was traded, in the units the items are counted in.
- $revenue : null|array<string|int, mixed>|ObservationSeries
- What the trade earned — the amount invoiced.
- $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.
- $url : int|string|null
- URL of the item.
- $volume : null|array<string|int, mixed>|ObservationSeries
- The space the traded goods took up.
- $weight : null|array<string|int, mixed>|ObservationSeries
- What the traded goods weighed.
- $year : null|int
- The calendar year these figures cover.
- $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
ABOUT
public
string
ABOUT
= 'about'
ASSIGNED_COMPANY
public
string
ASSIGNED_COMPANY
= 'assignedCompany'
AVERAGE_COST
public
string
AVERAGE_COST
= 'averageCost'
AVERAGE_MARGIN
public
string
AVERAGE_MARGIN
= 'averageMargin'
CONTEXT
The @context of the json-ld representation of the thing.
public
string
CONTEXT
= \xyz\oihana\schema\constants\Oihana::SCHEMA
COST_PRICE
public
string
COST_PRICE
= 'costPrice'
DIRECTION
public
string
DIRECTION
= 'direction'
GROSS_MARGIN
public
string
GROSS_MARGIN
= 'grossMargin'
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.
OBSERVATION_PERIOD
public
string
OBSERVATION_PERIOD
= 'observationPeriod'
PURCHASE_COST
public
string
PURCHASE_COST
= 'purchaseCost'
PURCHASE_MARGIN
public
string
PURCHASE_MARGIN
= 'purchaseMargin'
QUANTITY
public
string
QUANTITY
= 'quantity'
REVENUE
public
string
REVENUE
= 'revenue'
VOLUME
public
string
VOLUME
= 'volume'
WEIGHT
public
string
WEIGHT
= 'weight'
YEAR
public
string
YEAR
= 'year'
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
$about
The article these figures are about.
public
null|int|string|array<string|int, mixed>|Thing
$about
Redeclares Statistics::$about with the same union, to name the subject : a stored row is read back as a Product, a bare code is left as read.
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\products\Product::class
$active
The visibility flag.
public
bool|null
$active
$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
$assignedCompany
The company these figures were measured for.
public
null|int|string|array<string|int, mixed>|Organization
$assignedCompany
A code, or the resolved organization. Statistics are commonly kept per legal entity as well as consolidated over all of them ; keeping the entity on the record is what lets a reader tell one from the other, and what a consumer scopes a reader's perimeter by.
Reuses the name, the shape and the meaning Customer::$assignedCompany already carries.
Tags
$averageCost
The trade valued at the weighted average cost of what was sold.
public
null|array<string|int, mixed>|ObservationSeries
$averageCost
The middle of the three costs : what the goods stood at in inventory when they left it, rather than what the last purchase order paid (HasTradingMeasures::$purchaseCost) or what they end up costing once the charges around them are loaded on (HasTradingMeasures::$costPrice).
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$averageMargin
The margin over {@see HasTradingMeasures::$averageCost}.
public
null|array<string|int, mixed>|ObservationSeries
$averageMargin
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$costPrice
The trade valued at cost price — the purchase price with the charges that ride along with it loaded on.
public
null|array<string|int, mixed>|ObservationSeries
$costPrice
The cost a margin is read against when the question is whether the trade paid for itself, rather than whether it was bought well.
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$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
$direction
Which side of the trade these figures were measured on — sales or purchases, from the operator's point of view.
public
null|string|BusinessDocumentDirection
$direction
The same enumeration, the same name and the same meaning as BusinessDocument::$direction : a figure and the document it was computed from say it the same way.
Tags
$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
$grossMargin
The margin over {@see HasTradingMeasures::$costPrice} — the gross margin.
public
null|array<string|int, mixed>|ObservationSeries
$grossMargin
The one a trading business steers by : what the trade earned once the goods it consumed are counted at what they truly cost.
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$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
$image
The image reference of this resource.
public
string|ImageObject|array<string|int, ImageObject|string>|null
$image
$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
$modified
Date on which the resource was changed.
public
null|string
$modified
$name
The name of the item.
public
int|string|null
$name
$observationPeriod
The step the series inside this record are cut at, as an ISO 8601 duration — `P1M` for one value a month, `P1W` a week, `P1D` a day.
public
null|string
$observationPeriod
Stated on the record rather than on each measure : every series of a given record is cut the same way, and saying it twelve times is twelve chances to disagree. Same term, same format as Observation::$observationPeriod.
Tags
$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
$publisher
The publisher of the resource.
public
string|array<string|int, string|Person|Organization>|Person|Organization|null
$publisher
$purchaseCost
The trade valued at the price paid for the goods.
public
null|array<string|int, mixed>|ObservationSeries
$purchaseCost
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$purchaseMargin
The margin over {@see HasTradingMeasures::$purchaseCost}.
public
null|array<string|int, mixed>|ObservationSeries
$purchaseMargin
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$quantity
How much was traded, in the units the items are counted in.
public
null|array<string|int, mixed>|ObservationSeries
$quantity
⚠️ Homogeneous only within one item. A figure spanning several items adds square metres to cubic metres to pieces ; it is worth reading per article, and worth distrusting as a total. HasTradingMeasures::$volume and HasTradingMeasures::$weight are the two that add up whatever was sold.
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$revenue
What the trade earned — the amount invoiced.
public
null|array<string|int, mixed>|ObservationSeries
$revenue
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$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
$url
URL of the item.
public
int|string|null
$url
$volume
The space the traded goods took up.
public
null|array<string|int, mixed>|ObservationSeries
$volume
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$weight
What the traded goods weighed.
public
null|array<string|int, mixed>|ObservationSeries
$weight
Tags
Attributes
- #[HydrateAs]
- \xyz\oihana\schema\statistics\ObservationSeries::class
$year
The calendar year these figures cover.
public
null|int
$year
An integer : a year is compared, sorted and grouped far more often than it
is printed, and 2025 does all three without a cast. The wider period a
record covers, when it is not a plain year, belongs to temporalCoverage
on whatever publishes it — not here.
Tags
$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
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
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
$thiswithAtType()
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
$thiswithJSONLDMeta()
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