Oihana Php Schema

StatisticsSummary extends Statistics uses HasTradingMeasures, HasTradingMeasuresTrait, StatisticsSummaryTrait

Several records, added together.

A Statistics whose figures are not one counterparty's but the sum of a selection — a portfolio over a year, a branch, a range of goods. It carries the same ten measures as any record (HasTradingMeasures), each summed term by term : the January of the summary is the sum of the Januaries, the February the sum of the Februaries, and so on over the twelve positions. That is what lets a reader draw the monthly curve of a set.

🔑 One class for every family, because a summary loses the only thing that told them apart. CustomerStatistics and ProviderStatistics differ by their subject and by the dimensions a subject carries ; the ten measures are the same on both sides, and three of the six families add nothing at all. Writing one summary class per family would produce classes identical down to the last property.

And the reader still knows which side of the trade is being read : Statistics::$direction is inherited and stays true — a sum of sales is a sale.

🚨 about has two states, and the difference is the whole contract.

Absent when the summary answers for a plain selection : it is about no one, and saying null would claim the subject is unknown where the truth is that the question does not apply. The property is inherited and simply never assigned — declared without a default, it stays uninitialized, and the serialization skips it.
Set to the grouping key when the selection was grouped by a dimension : a summary grouped by point of sale is « the figures of warehouse 400 », and that warehouse is its subject. The inherited union already accepts it.

⚠️ There is only one about, so a grouping over two dimensions at once has nowhere to say so. That is a design question the day it is needed, not an oversight.

⚠️ This class stores a result ; it computes nothing. The summing belongs to whoever reads the records — the library only models the shape, as it does for AgingSummary.

$summary = new StatisticsSummary
([
    StatisticsSummary::YEAR            => 2024 ,
    StatisticsSummary::DIRECTION       => BusinessDocumentDirection::SALE ,
    StatisticsSummary::NUMBER_OF_ITEMS => 128 ,
    StatisticsSummary::REVENUE         => new ObservationSeries
    ([
        Oihana::UNIT_CODE => 'EUR' ,
        Oihana::VALUE     => 4820.50 ,                 // the total of the summed totals
        Oihana::VALUES    => [ 401.20 , 388.00 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 ] ,
    ]) ,
]) ;

$summary->about ?? null ; // null — a summary of a plain selection is about no one

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.
NUMBER_OF_ITEMS : string = 'numberOfItems'
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 entity 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.
$numberOfItems : int|null: How many records were summed to produce this line.
$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`.

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.

NUMBER_OF_ITEMS


    public
        string
    NUMBER_OF_ITEMS
    = 'numberOfItems'

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'

$_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 entity these figures are about.


        public
            null|int|string|array<string|int, mixed>|Thing
    $about

Holds the raw reference as read from the source (a business code), or the resolved subject. Left untyped beyond Thing on purpose : each family names its own subject by redeclaring the property with the same union and its own #[HydrateAs], which is what lets Reflection::hydrate() read a joined row back as the right class while a bare code is left as read.

$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.

$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).

$averageMargin

The margin over {@see HasTradingMeasures::$averageCost}.


        public
            null|array<string|int, mixed>|ObservationSeries
    $averageMargin

$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.

$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.

$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.

$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

$numberOfItems

How many records were summed to produce this line.


        public
            int|null
    $numberOfItems

🚨 It counts records, not counterparties. A source that writes one record per counterparty per year and per operating company makes a counterparty traded with by two companies weigh two records — and this property counts it twice. A reader captioning it « customers » rather than « records » states a number that was never measured.

Reuses the name schema.org gives the same idea on ItemList::$numberOfItems, without the list itself : a summary has melted its members, it does not enumerate them.

$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.

$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

$purchaseMargin

The margin over {@see HasTradingMeasures::$purchaseCost}.


        public
            null|array<string|int, mixed>|ObservationSeries
    $purchaseMargin

$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.

$revenue

What the trade earned — the amount invoiced.


        public
            null|array<string|int, mixed>|ObservationSeries
    $revenue

$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

$weight

What the traded goods weighed.


        public
            null|array<string|int, mixed>|ObservationSeries
    $weight

$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.

$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
     = []

__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.

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.

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

StatisticsSummary extends Statistics uses HasTradingMeasures, HasTradingMeasuresTrait, StatisticsSummaryTrait

Tags

Table of Contents

Constants

Properties

Methods

Constants

ABOUT

ASSIGNED_COMPANY

AVERAGE_COST

AVERAGE_MARGIN

CONTEXT

COST_PRICE

DIRECTION

GROSS_MARGIN

JSON_PRIORITY_KEYS

NUMBER_OF_ITEMS

OBSERVATION_PERIOD

PURCHASE_COST

PURCHASE_MARGIN

QUANTITY

REVENUE

VOLUME

WEIGHT

YEAR

Properties

$_from

$_id

$_key

$_rev

$_to

$about

Tags

$active

$additionalType

$alternateName

$assignedCompany

Tags

$averageCost

Tags

Attributes

$averageMargin

Tags

Attributes

$costPrice

Tags

Attributes

$created

$description

$direction

Tags

$disambiguatingDescription

$grossMargin

Tags

Attributes

$hasPart

$id

$identifier

$image

$isPartOf

$license

$mainEntityOfPage

$modified

$name

$numberOfItems

Tags

$observationPeriod

Tags

$owner

$potentialAction

$publisher

$purchaseCost

Tags

Attributes

$purchaseMargin

Tags

Attributes

$quantity

Tags

Attributes