SlotFlow API Documentation

SlotSpace
in package

FinalYes

Defines the slot space, its dimensions, the slots that exist within it, and the edges and flows that operate on it.

Tags
psalm-type

TDimensionName = non-empty-string the name and value of a dimension must be non-empty strings

psalm-type

TDimensionValue = non-empty-string dimension values must be non-empty strings, and each dimension must have at least one value

psalm-type

TSlotKey = non-empty-string the serialized representation of a slot, used as a unique identifier, can be used as a slot pattern that matches exactly one slot

psalm-type

TSlotTuple = list<TDimensionValue> a tuple of dimension values in the order of dimension names, used as an alternative way to specify a slot

psalm-type

TSlotPartial array<TDimensionName, TDimensionValue> a partial associative specification of concrete dimension values; dimensions may be omitted, but provided values are concrete; used as a slot pattern that can match multiple slots

psalm-type

TSlotValues array<TDimensionName, TDimensionValue> a full associative specification of concrete dimension values; all dimensions must be present and all values must be concrete; used as a slot pattern that matches exactly one slot

psalm-type

TDimensionValuePattern ?non-empty-string a null or string pattern to match dimension values. Used in slot patterns. String may contain wildcards as allowed by codec. Null is equivaldent to the match-all wildcard.

psalm-type

TSlotTuplePattern list<TDimensionValuePattern> a tuple of dimension value patterns in the order of dimension names, used as an alternative way to specify a slot pattern.

psalm-type

TSlotArrayPattern array<TDimensionName, TDimensionValuePattern> a pattern specified as an associative array of dimension name to dimension value pattern, where missing or null values are treated as wildcards that match any value for the dimension. Used as a slot pattern that can match multiple slots.

psalm-type

TSlotPattern TSlotTuplePattern|TSlotArrayPattern|TSlotKey|null a slot pattern can be:

  • a string slot pattern (e.g. "sup.*.foo|bar") that is deserialized using the codec
  • an tuple: array value pattern in the exact order and number of dimensions defined in the slot space, where each value can be a specific value or a wildcard (null or wildcard string as defined by codec)
  • an array of dimension name to value patterns where missing or null values are treated as wildcards
  • null, to match the nil slot (for source/sink slots in edges)
psalm-type

TEdgePattern array{from: TSlotPattern, to: TSlotPattern}|array{TSlotPattern, TSlotPattern} a pattern to define an edge between slots, consisting of a from pattern and a to pattern. Can be used in cascade step definitions.

Table of Contents

Properties

$cascades  : array<non-empty-string, Flow>
$codec  : SlotCodec
$flows  : array<non-empty-string, Flow>
$dimensionNames  : array<int, TDimensionName>
$dimensions  : array<non-empty-string, array<int, non-empty-string>>
$edgeRulesByOriginSlot  : array<non-empty-string, array<int, EdgeRule>>
Per slot key => the list of rules needed to generate the valid edges from that slot to other slots.
$nilSlot  : Slot
$outgoingEdgeByOriginSlot  : array<non-empty-string, array<non-empty-string, MovementEdge>>
$slotsByKey  : array<non-empty-string, Slot>
$slotsByPattern  : array<non-empty-string, array<int, Slot>>

Methods

__construct()  : mixed
cascade()  : self
Register a named cascade definition.
define()  : self
dimensionNames()  : array<int, non-empty-string>
dimensions()  : array<non-empty-string, array<int, non-empty-string>>
dimensionValues()  : array<int, non-empty-string>
Get the list of all possible valid values for a specific dimension.
edgeRules()  : self
This is used to generate the valid edges between slots, after the valid slots have been determined by the slot rules.
edgesBetween()  : array<string|int, MovementEdge>
Generate edges using pattern expansion Both wildcard and missing values are supported, with the same semantics.
edgesByLabels()  : array<int, MovementEdge>
Return all currently valid edges generated from rules matching any of the given labels.
expandSlotPattern()  : array<int, array<non-empty-string, non-empty-string>|null>
Expand a string or array of Slot pattern into a list of partials.
flow()  : self
Register a named flow definition.
getCascade()  : Cascade
getEdgesFrom()  : array<non-empty-string, MovementEdge>
Apply edge rules in sequence to generate a list of edges Cache edge list by slot key at $this->outgoingEdgeByOriginSlot.
getFlow()  : Flow
matchPartial()  : array<int, Slot>
Finds all slots matching the given partial pattern, where the pattern can contain specific values, and '*' can be used as a wildcard expression to match any value for a dimension.
matchPattern()  : array<int, Slot>
Resolve a slot pattern directly to matching slots.
nilSlot()  : Slot
slot()  : Slot
Finds the slot corresponding to the given key or values. The input can be either a serialized key string or an array of dimension values, which will be serialized using the defined serializer.
slotRules()  : self
This function is to be used after the SlotSpace is constructed and applies provided inclusion/exclusion rules in sequential order, to shape the slot space into a shape meaningful for the application domain.
trySlot()  : Slot|null
Finds the slot corresponding to the given key or values. The input can be either a serialized key string or an array of dimension values, which will be serialized using the defined serializer.
validateKnownDimensionNames()  : void
cartesian()  : array<int, array<non-empty-string, non-empty-string>>
Generate the cartesian product of the given dimensions, where the input is an array of dimension name to list of values, and the output is a list of all combinations of dimension values, where each combination is represented as an array of dimension name to value.

Properties

$dimensionNames

private array<int, TDimensionName> $dimensionNames = []

$dimensions

private array<non-empty-string, array<int, non-empty-string>> $dimensions = []
Tags
psalm-var

array<TDimensionName, list<TDimensionValue>>

$edgeRulesByOriginSlot

Per slot key => the list of rules needed to generate the valid edges from that slot to other slots.

private array<non-empty-string, array<int, EdgeRule>> $edgeRulesByOriginSlot = []
Tags
psalm-var

array<TSlotKey, list<EdgeRule>>

$outgoingEdgeByOriginSlot

private array<non-empty-string, array<non-empty-string, MovementEdge>> $outgoingEdgeByOriginSlot = []
Tags
psalm-var

array<TSlotKey, array<TSlotKey, MovementEdge>>

$slotsByKey

private array<non-empty-string, Slot> $slotsByKey = []
Tags
psalm-var

array<TSlotKey, Slot>

$slotsByPattern

private array<non-empty-string, array<int, Slot>> $slotsByPattern = []

Methods

__construct()

public __construct(array<non-empty-string, array<int, non-empty-string>> $dimensions[, SlotCodec>|null $codecClass = null ]) : mixed
Parameters
$dimensions : array<non-empty-string, array<int, non-empty-string>>
$codecClass : SlotCodec>|null = null
Tags
psalm-param

array<TDimensionName, list<TDimensionValue>> $dimensions

cascade()

Register a named cascade definition.

public cascade(non-empty-string $name, callable(Cascade): mixed|array<int, array{0?: array|string|null, 1?: array|string|null, from?: array|string|null, to?: array|string|null}> $builder) : self

use flow() instead

Parameters
$name : non-empty-string
$builder : callable(Cascade): mixed|array<int, array{0?: array|string|null, 1?: array|string|null, from?: array|string|null, to?: array|string|null}>
Tags
psalm-suppress

DeprecatedClass

psalm-param

\Closure(Cascade):mixed|list<TEdgePattern> $builder

Return values
self

define()

public static define(array<non-empty-string, array<int, non-empty-string>> $dimensions[, SlotCodec>|null $codecClass = null ]) : self
Parameters
$dimensions : array<non-empty-string, array<int, non-empty-string>>
$codecClass : SlotCodec>|null = null
Tags
psalm-param

array<TDimensionName, list<TDimensionValue>> $dimensions

Return values
self

dimensionNames()

public dimensionNames() : array<int, non-empty-string>
Tags
psalm-return

list<TDimensionName>

Return values
array<int, non-empty-string>

dimensions()

public dimensions() : array<non-empty-string, array<int, non-empty-string>>
APIYes
Tags
psalm-return

array<TDimensionName, list<TDimensionValue>>

Return values
array<non-empty-string, array<int, non-empty-string>>

dimensionValues()

Get the list of all possible valid values for a specific dimension.

public dimensionValues(non-empty-string $dimension) : array<int, non-empty-string>
Parameters
$dimension : non-empty-string
Tags
psalm-param

TDimensionName $dimension

psalm-return

list<TDimensionValue>

Return values
array<int, non-empty-string>

edgeRules()

This is used to generate the valid edges between slots, after the valid slots have been determined by the slot rules.

public edgeRules(RuleSet<string|int, EdgeRule>|array<int, EdgeRule|RuleSet<string|int, EdgeRule>> $rules) : self

The starting point is always an empty set of edges, and the rules are applied sequentially to add edges between slots matching the from and to patterns.

Edge rules are stored at origin slot level, to be lazily evaluated into actual edges when needed.

Parameters
$rules : RuleSet<string|int, EdgeRule>|array<int, EdgeRule|RuleSet<string|int, EdgeRule>>
Return values
self

edgesBetween()

Generate edges using pattern expansion Both wildcard and missing values are supported, with the same semantics.

public edgesBetween(non-empty-string|array<non-empty-string, string|null>|null $fromPattern, non-empty-string|array<non-empty-string, string|null>|null $toPattern) : array<string|int, MovementEdge>
Parameters
$fromPattern : non-empty-string|array<non-empty-string, string|null>|null

Specified values match with equality, wildcard/missing match with anything

$toPattern : non-empty-string|array<non-empty-string, string|null>|null

Specified values are kept, wildcard/missing are filled in from the $fromPattern match

Tags
psalm-param

TSlotPattern $fromPattern Specified values match with equality, wildcard/missing match with anything

psalm-param

TSlotPattern $toPattern Specified values are kept, wildcard/missing are filled in from the $fromPattern match

Return values
array<string|int, MovementEdge>

edgesByLabels()

Return all currently valid edges generated from rules matching any of the given labels.

public edgesByLabels(array<int, non-empty-string> $labels) : array<int, MovementEdge>
Parameters
$labels : array<int, non-empty-string>
Return values
array<int, MovementEdge>

expandSlotPattern()

Expand a string or array of Slot pattern into a list of partials.

public expandSlotPattern(string|array<non-empty-string, string|null>|null $pattern) : array<int, array<non-empty-string, non-empty-string>|null>
Parameters
$pattern : string|array<non-empty-string, string|null>|null
Tags
psalm-param

TSlotPattern $pattern

psalm-return

list<TSlotPartial>|list

throws
SlotFlowInvalidArgumentException

if the pattern is invalid or contains unknown dimensions or values

Return values
array<int, array<non-empty-string, non-empty-string>|null>

flow()

Register a named flow definition.

public flow(non-empty-string $name, callable(Flow): mixed|array<int, array{0?: array|string|null, 1?: array|string|null, from?: array|string|null, to?: array|string|null}> $builder) : self
Parameters
$name : non-empty-string
$builder : callable(Flow): mixed|array<int, array{0?: array|string|null, 1?: array|string|null, from?: array|string|null, to?: array|string|null}>
Tags
psalm-param

\Closure(Flow):mixed|list<TEdgePattern> $builder

Return values
self

getCascade()

public getCascade(string $name) : Cascade

use getFlow() instead

Parameters
$name : string
Tags
psalm-suppress

DeprecatedClass

Return values
Cascade

getEdgesFrom()

Apply edge rules in sequence to generate a list of edges Cache edge list by slot key at $this->outgoingEdgeByOriginSlot.

public getEdgesFrom(Slot $from) : array<non-empty-string, MovementEdge>
Parameters
$from : Slot
Tags
psalm-return

array<TSlotKey, MovementEdge>

Return values
array<non-empty-string, MovementEdge>

getFlow()

public getFlow(string $name) : Flow
Parameters
$name : string
Return values
Flow

matchPartial()

Finds all slots matching the given partial pattern, where the pattern can contain specific values, and '*' can be used as a wildcard expression to match any value for a dimension.

public matchPartial(array<non-empty-string, string|null> $partial) : array<int, Slot>

The pattern can be either a serialized key string or an array of dimension values, where missing or null values are treated as '*' wildcards.

Parameters
$partial : array<non-empty-string, string|null>
Tags
psalm-param

array<TDimensionName, TDimensionValuePattern> $partial

Return values
array<int, Slot>

matchPattern()

Resolve a slot pattern directly to matching slots.

public matchPattern(array<string|int, mixed>|string|null $pattern) : array<int, Slot>

Exact string keys are short-circuited through the slot registry. General string patterns are cached after expansion so repeated lookups can reuse the resolved slot list without re-running pattern deserialization and matching.

Parameters
$pattern : array<string|int, mixed>|string|null
Tags
psalm-param

TSlotPattern $pattern

Return values
array<int, Slot>

slot()

Finds the slot corresponding to the given key or values. The input can be either a serialized key string or an array of dimension values, which will be serialized using the defined serializer.

public slot(string|array<string|int, string>|null $keyOrValues) : Slot

All dimensions must be specified in the input, and wildcards are not allowed.

Parameters
$keyOrValues : string|array<string|int, string>|null
Tags
see
SlotPattern::from

for more flexible pattern matching with support for wildcards and missing values.

psalm-param

TSlotPattern $keyOrValues

throws
SlotFlowInvalidArgumentException

if the resulting key does not correspond to any defined slot

Return values
Slot

slotRules()

This function is to be used after the SlotSpace is constructed and applies provided inclusion/exclusion rules in sequential order, to shape the slot space into a shape meaningful for the application domain.

public slotRules(RuleSet<string|int, SlotRule>|array<int, SlotRule|RuleSet<string|int, SlotRule>> $rules) : self

A "full slot space" is defined by the cartesian product of all dimensions and their values, and contains all possible combinations of dimension values. Inclusion rules add matching slots to the valid set, while exclusion rules remove remove them.

Since the rules are applied sequentially, later rules may override earlier ones. The starting slot space is determined by the first rule in the list: If it is an exclusion rule, then we start with a full slot space. If it is an inclusion rule, then we start with an empty slot space.

Parameters
$rules : RuleSet<string|int, SlotRule>|array<int, SlotRule|RuleSet<string|int, SlotRule>>

list of patterns to include or exclude certain slots. If the list is empty, all combinations of dimensions are included. Exclusion patterns start with '-', inclusion patterns start with '+' or have no prefix. Patterns are applied in order, so later patterns override earlier ones. If the first pattern starts with '-', it is treated as an exclusion pattern and all slots are included by default. If the first pattern starts with '+', it is treated as an inclusion pattern and no slots are included by default.

Return values
self

trySlot()

Finds the slot corresponding to the given key or values. The input can be either a serialized key string or an array of dimension values, which will be serialized using the defined serializer.

public trySlot(string|array<string|int, string>|null $keyOrValues[, bool $throwOnInvalidDimensionValues = false ]) : Slot|null

All dimensions must be specified in the input, and wildcards are not allowed.

Parameters
$keyOrValues : string|array<string|int, string>|null
$throwOnInvalidDimensionValues : bool = false
Tags
see
SlotPattern::from

for more flexible pattern matching with support for wildcards and missing values.

psalm-param

TSlotPattern $keyOrValues

Return values
Slot|null —

Returns the SlotKey if found, or null if no matching slot exists

validateKnownDimensionNames()

public validateKnownDimensionNames(array<string|int, mixed> $names) : void
Parameters
$names : array<string|int, mixed>

list of dimension names that must all exist in the slot space

Tags
psalm-param

array $names

throws
SlotFlowInvalidArgumentException

cartesian()

Generate the cartesian product of the given dimensions, where the input is an array of dimension name to list of values, and the output is a list of all combinations of dimension values, where each combination is represented as an array of dimension name to value.

private cartesian(array<non-empty-string, array<int, non-empty-string>> $dimensions) : array<int, array<non-empty-string, non-empty-string>>

Dimensions with empty value lists are ignored.

Parameters
$dimensions : array<non-empty-string, array<int, non-empty-string>>
Return values
array<int, array<non-empty-string, non-empty-string>> 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results