Invocation

Rasuvaeff\Understudy\Invocation

Class — Package: rasuvaeff/understudy — Source — Version: v1.1.0-1-g6ed023f

One recorded call on an understudy.

Instances are handed to answers() callbacks while the call is still in flight, and read back afterwards through Understudy::calls(). The outcome is therefore filled in once, by the dispatcher, after the answer is known.

Constructor

__construct(
    non-empty-string $method,
    list $args,
    positive-int $sequence,
    ?object $double = NULL,
    list $liveArgs = [],
    list<int> $sensitiveArguments = [],
    array<int,non-empty-string> $parameterNames = [],
)

Parameter	Type	Default	Description
$method	non-empty-string	required
$args	list	required
$sequence	positive-int	required	position in this context's global call order
$double	?object	NULL
$liveArgs	list	[]	the arguments as the caller still holds them, references included — what delegation needs, where $args is a reading of them
$sensitiveArguments	list<int>	[]	positions the contract marked #[\SensitiveParameter]; carried on the call so a failure message and a transcript can redact the value the way PHP redacts it in its own traces
$parameterNames	array<int,non-empty-string>	[]	the contract's own name for each fixed parameter, so a call can be read by name

Methods

arg()

arg(int|string $parameter): mixed

One argument, by position or by the contract's own parameter name.

• $parameter — zero-based position, or the contract's own parameter name

Throws:

• Exception\InvalidSpecificationArgument — when the method declares no such parameter

$call->args[0] is opaque in a longer specification, and a library whose specifications are real calls should let a call be read the way it was written. A name that is not a fixed parameter of the method — a value the variadic tail absorbed, or a typo — is refused rather than answered with null, which is a value an argument can legitimately have.

argsAfter()

argsAfter(): ?array

What the arguments were once the call had been answered.

Only a method with a by-reference parameter has one: for every other method the answer cannot change what was passed, and taking the snapshot anyway would cost every call in the suite. Null means "same as $args".

recordFinalArguments()

recordFinalArguments(list $args): void

Stores the arguments after a by-reference call has returned.

belongsTo()

belongsTo(object $double): bool

Checks whether this invocation belongs to a given double.

callOriginal()

callOriginal(): mixed

Runs the real implementation of this call and returns what it answered — the answers() escape hatch for "behave normally, except here".

Throws:

• Exception\OriginalCallUnavailable

Where that implementation runs follows the double's own form. A class double that forwards runs the real body on itself, over the state forwarding() copied there; every other double delegates to the real instance it remembers, where the body's own self-calls stay inside that object.

Without a forwarding target it raises OriginalCallUnavailable rather than reaching for the real body anyway: nothing copied the state, so the body would work over properties the skipped constructor never filled.

recordOutcome()

recordOutcome(Outcome $outcome): void

Records an outcome wrapper for internal compatibility.

The wrapped form of recordReturned() and recordThrown(), kept for the callers that still hand over an Outcome; dispatch itself uses the scalar recorders because every call reaches them.

recordReturned()

recordReturned(mixed $value): void

Records a returned value without retaining an outcome wrapper.

Records a returned value without allocating an Outcome wrapper. The wrapper remains supported by recordOutcome() for internal compatibility; dispatch uses this scalar path because every call reaches it.

recordDiscardedReturn()

recordDiscardedReturn(): void

Records that the call returned but its value was discarded.

Records that the call returned without keeping what it returned — the lean double's reading of an outcome. The distinction from "threw" and from "returned null" is kept: didReturn() stays true, and returned() refuses by name instead of inventing a value.

isReturnDiscarded()

isReturnDiscarded(): bool

Reports whether the returned value was discarded.

recordThrown()

recordThrown(Throwable $thrown): void

Records the throwable produced by the call.

markAccounted()

markAccounted(): void

Marks this invocation as claimed by verification or an expectation.

Marks this call as accounted for: an expectation matched it, or a verification claimed it. nothingElse() is the question this answers.

isAccounted()

isAccounted(): bool

Reports whether verification or an expectation claimed this invocation.

didReturn()

didReturn(): bool

Whether the call answered with a value — null included, which is why this is asked rather than inferred from returned().

didThrow()

didThrow(): bool

Whether the call ended in a throwable, which thrown() then holds.

returned()

returned(): mixed

The value the call answered with.

Throws:

• Exception\OutcomeUnavailable — when the call threw instead, or when the understudy is lean and did not keep the value

thrown()

thrown(): ?Throwable

The throwable the call ended in, or null when it returned.