classUpsertExpression

packages/ztd-query-core/src/Shadow/Mutation/UpsertExpression.php:28

final class UpsertExpression

A scalar expression from an UPSERT assignment, in no particular dialect.

Every dialect writes "the value that was already there" and "the value that

was coming in" differently, so a parser reads its own spelling and builds one

of these; what the expression means is then worked out here, once, for all of them. What each operator means is left to the collaborator that owns it, so this is only the tree and the walk over it.

Type Aliases§

Row = import from TableDefinition

RowValue = import from TableDefinition

Methods§

public function __construct(
    private UpsertExpressionKind $kind,
    private UpsertLiteralSource $literal = new \ZtdQuery\Shadow\Mutation\Upsert\UpsertLiteral(null),
    private UpsertColumnSource|null $columnSource = null,
    private string|null $column = null,
    private list<self> $operands = [],
    private UpsertColumn $columns = new \ZtdQuery\Shadow\Mutation\Upsert\UpsertColumn(),
    private UpsertTruth $truth = new \ZtdQuery\Shadow\Mutation\Upsert\UpsertTruth(),
    private UpsertOperator $operators = new \ZtdQuery\Shadow\Mutation\Upsert\UpsertOperator(),
)

source §

Parameters

`$kind`	`UpsertExpressionKind`	What this node is
`$literal`	`UpsertLiteralSource`	Value a literal stands for
`$columnSource`	`UpsertColumnSource\|null`	Which row a column is read from
`$column`	`string\|null`	Column a column node names
`$operands`	`list<self>`	Nodes this one is written over
`$columns`	`UpsertColumn`	Reads a column off a row
`$truth`	`UpsertTruth`	Answers what counts as true
`$operators`	`UpsertOperator`	Says what an operator stands for

Calls 4

public static function literal(mixed $value): self

source §

Builds an expression standing for a value written into the statement.

Parameters

$value mixed Value as the statement wrote it

Returns

self The expression

Test cases 30

Called from 12

Calls 3

new self line 61
class-const UpsertExpressionKind::Literal() line 61
new UpsertLiteral line 61

public static function column(UpsertColumnSource $source, string $column): self

source §

Builds an expression standing for a column of one of the two rows.

Parameters

`$source`	`UpsertColumnSource`	Whether the column is read from the existing row or the incoming one
`$column`	`string`	Column as the statement named it

Returns

self The expression

Throws

InvalidDefinitionException When no column was named

Test cases 22

Called from 7

Calls 3

new InvalidDefinitionException line 77
new self line 80
class-const UpsertExpressionKind::Column() line 80

public static function unary(UpsertExpressionKind $kind, self $operand): self

source §

Builds an expression written over one other.

Parameters

`$kind`	`UpsertExpressionKind`	Operator to apply
`$operand`	`self`	Expression it is applied to

Returns

self The expression

Throws

InvalidDefinitionException When the operator is not one written over a single operand

Test cases 3

Called from 6

Calls 6

function-call in_array line 95
class-const UpsertExpressionKind::UnaryPlus() line 96
class-const UpsertExpressionKind::UnaryMinus() line 97
class-const UpsertExpressionKind::Not() line 98
new InvalidDefinitionException line 100
new self line 103

public static function binary(UpsertExpressionKind $kind, self $left, self $right): self

source §

Builds an expression written between two others.

Parameters

`$kind`	`UpsertExpressionKind`	Operator to apply
`$left`	`self`	Expression on its left
`$right`	`self`	Expression on its right

Returns

self The expression

Throws

InvalidDefinitionException When the operator is not one written between two operands

Test cases 28

Called from 15

Calls 8

function-call in_array line 119
class-const UpsertExpressionKind::Literal() line 120
class-const UpsertExpressionKind::Column() line 121
class-const UpsertExpressionKind::UnaryPlus() line 122
class-const UpsertExpressionKind::UnaryMinus() line 123
class-const UpsertExpressionKind::Not() line 124
new InvalidDefinitionException line 126
new self line 129

public function evaluate(Row $existingRow, Row $incomingRow, string $tableName): mixed

source §

Answers what the expression stands for, against the two rows in play.

Parameters

`$existingRow`	`Row`	Row the conflict was found on
`$incomingRow`	`Row`	Row the statement was trying to write
`$tableName`	`string`	Table being written to

Returns

mixed The value the expression stands for

Throws

UnsupportedSqlException When an operand is not something the operator can be applied to

Test cases 1

UpsertLiteralSourceTest::testValueFlowsIntoAnExpressionWithoutCoercion calls

Called from 1

method-call ZtdQuery\Shadow\Mutation\UpsertExpression::matches() packages/ztd-query-core/src/Shadow/Mutation/UpsertExpression.php:178

Calls 8

class-const UpsertExpressionKind::Literal() line 145
method-call UpsertLiteralSource::value() line 146
class-const UpsertExpressionKind::Column() line 148
method-call UpsertColumn::of() line 149
class-const UpsertColumnSource::Incoming() line 150
method-call UpsertOperator::apply() line 155
method-call UpsertExpression::operand() line 157
function-call count line 158

public function matches(Row $existingRow, Row $incomingRow, string $tableName): bool

source §

Reports whether the expression holds, as a condition would have to.

Unknown is not enough: a WHERE that cannot be shown to hold does not select the row, so only a definite true counts.

Parameters

`$existingRow`	`Row`	Row the conflict was found on
`$incomingRow`	`Row`	Row the statement was trying to write
`$tableName`	`string`	Table being written to

Returns

bool True when the expression is definitely true

Throws

UnsupportedSqlException When an operand is not something the operator can be applied to

Calls 2

method-call UpsertTruth::of() line 178
method-call UpsertExpression::evaluate() line 178

public function operand(
    int $index,
    Row $existingRow,
    Row $incomingRow,
    string $tableName,
): mixed

source §

Answers what one of the operands stands for.

Parameters

`$index`	`int`	Which operand
`$existingRow`	`Row`	Row the conflict was found on
`$incomingRow`	`Row`	Row the statement was trying to write
`$tableName`	`string`	Table being written to

Returns

mixed The value that operand stands for

Throws

UnsupportedSqlException When an operand is not something the operator can be applied to

Called from 2

Private surface 8§

Implementation details, listed for orientation only.

private UpsertExpressionKind $kind

private UpsertLiteralSource $literal = new \ZtdQuery\Shadow\Mutation\Upsert\UpsertLiteral(null)

private UpsertColumnSource|null $columnSource = null

private string|null $column = null

private list<self> $operands = []

private UpsertColumn $columns = new \ZtdQuery\Shadow\Mutation\Upsert\UpsertColumn()

private UpsertTruth $truth = new \ZtdQuery\Shadow\Mutation\Upsert\UpsertTruth()

private UpsertOperator $operators = new \ZtdQuery\Shadow\Mutation\Upsert\UpsertOperator()

Test cases 41§

Test cases that cover or call this symbol, from the coverage report and from the analyzed test sources.

Dedicated tests 18

Other tests reaching this symbol 23

Relations§

Static calls 40

Type declarations 41