byrcsc/laravel-assignment · 1.x

API reference.

This page lists every public method, model reader, enum, and contract that the 1.x versioning promise covers.

The versioning promise covers everything on this page. Nothing listed here breaks within 1.x. Anything in the package that is not listed here is internal and may change in a patch release.

Assignable trait

ByRcsc\LaravelAssignment\Concerns\Assignable

Method	Returns
`autoAssign(?string $role = null)`	`?Assignment`
`assign(Model $assignee, ?string $role = null, ?Model $by = null)`	`Assignment`
`offer(Model $assignee, ?string $role = null, ?Model $by = null, ?int $ttlSeconds = null)`	`Assignment`
`reassign(Model $newAssignee, ?string $role = null, ?Model $by = null)`	`Assignment`
`unassign(?string $role = null, ?Model $by = null)`	`Assignment`
`assignment(?string $role = null)`	`?Assignment`
`openAssignment(?string $role = null)`	`?Assignment`
`assignee(?string $role = null)`	`?Model`
`isAssigned(?string $role = null)`	`bool`
`queuedAssignment(?string $role = null)`	`?QueuedAssignment`
`assignments()`	`MorphMany`

assignment() and openAssignment() return the same row. assignments() returns rows oldest first.

Assignee trait

ByRcsc\LaravelAssignment\Concerns\Assignee

Method	Returns
`accept(Assignment $assignment)`	`Assignment`
`decline(Assignment $assignment)`	`Assignment`
`workload(?string $assignableType = null)`	`int`
`assignments()`	`MorphMany`
`activeAssignments()`	`MorphMany`
`openAssignments()`	`MorphMany`

Facade

ByRcsc\LaravelAssignment\Facades\Assignment

Method	Returns
`for(Model $assignable)`	`PendingAssignment`
`autoAssign(Model $assignable, ?string $role = null)`	`?Assignment`
`flushQueue(?string $assignableType = null)`	`int`

flushQueue() returns how many queued entries it assigned.

Builder

ByRcsc\LaravelAssignment\PendingAssignment, returned by Assignment::for().

Method	Returns
`among(iterable\|Closure $candidates)`	`self`
`role(?string $role)`	`self`
`scope(?string $scope)`	`self`
`using(string\|SelectionPolicy\|Closure $policy)`	`self`
`by(?Model $actor)`	`self`
`expiresIn(?int $seconds)`	`self`
`assign()`	`?Assignment`
`offer()`	`?Assignment`
`queue(int $priority = 0)`	`QueuedAssignment`

among() accepts a collection, an array, or a closure receiving the assignable and returning either. Candidates must be persisted Eloquent models. Anything else raises an UnexpectedValueException.

expiresIn() throws InvalidArgumentException for a value below 1. An empty string passed to role() throws the same exception when the builder writes. Pass null for no role or for an offer that never expires.

assign() and offer() return null when the candidate list is empty or the policy selects nobody. Every other failure throws.

Omitting scope() derives one from the assignable class and the role. Omitting using() selects at random.

Assignment model

ByRcsc\LaravelAssignment\Models\Assignment

Relations

Relation	Points at
`assignable()`	The model being assigned
`assignee()`	The model holding it
`assignedBy()`	The actor, null when the engine created the row

Attributes

Attribute	Type
`role`	`?string`
`status`	`AssignmentStatus`
`ended_reason`	`?EndReason`
`scope`	`?string`
`offered_at`	`?CarbonImmutable`
`accepted_at`	`?CarbonImmutable`
`expires_at`	`?CarbonImmutable`
`ended_at`	`?CarbonImmutable`

Predicates and actions

Method	Returns
`isOpen()`	`bool`
`isActive()`	`bool`
`isOffered()`	`bool`
`isEnded()`	`bool`
`isExpired()`	`bool`
`complete(?Model $by = null)`	`self`

Query scopes

Scope	Matches
`open()`	Active, or offered and not past expiry
`active()`	Status is active
`offered()`	Status is offered
`ended()`	Status is ended
`expired()`	Offered, with an expiry that has passed

QueuedAssignment model

ByRcsc\LaravelAssignment\Models\QueuedAssignment

Member	Type
`assignable()`	`MorphTo`
`role`	`?string`
`priority`	`int`
`queued_at`	`CarbonImmutable`

Profiles

ByRcsc\LaravelAssignment\AssignmentProfile, abstract.

Method	Returns	Default
`candidates(Model $assignable, ?string $role)`	`iterable`	abstract
`policy(Model $assignable, ?string $role)`	`string\|SelectionPolicy\|Closure`	abstract
`scope(Model $assignable, ?string $role)`	`?string`	`null`
`mode(Model $assignable, ?string $role)`	`Mode`	`Mode::Assign`
`offerTtl(Model $assignable, ?string $role)`	`?int`	`null`
`queueWhenEmpty(Model $assignable, ?string $role)`	`bool`	`true`
`queuePriority(Model $assignable, ?string $role)`	`int`	`0`

Selection

ByRcsc\LaravelAssignment\Contracts\SelectionPolicy

public function select(
    Model $assignable,
    Collection $candidates,
    ScopeState $state,
): ?Model;

Shipped implementations:

Class	Constructor
`Policies\RoundRobin`	none
`Policies\LeastWorkload`	`__construct(?string $assignableType = null)`, or `LeastWorkload::of(string $assignableType)`
`Policies\Random`	none
`Policies\FirstAvailable`	none

ByRcsc\LaravelAssignment\ScopeState

Method	Returns
`get(string $key, mixed $default = null)`	`mixed`
`put(string $key, mixed $value)`	`self`
`persist()`	`void`

Keys accept dot notation. The engine calls persist() after a successful write, so a policy does not need to.

Enums

Enums\AssignmentStatus: Offered, Active, Ended.

Enums\EndReason: Unassigned, Reassigned, Declined, Expired, Completed.

Enums\Mode: Assign, Offer.

Each enum is string backed, and the case values are the lowercase names.

Events

Events\Assigned, AssignmentOffered, AssignmentAccepted, AssignmentDeclined, OfferExpired, Unassigned each carry $assignment. Reassigned carries $oldAssignment and $newAssignment. AssignableQueued carries $entry. OffersExhausted carries $lastOffer.

See events and listeners.

Notifications

Notifications\AssignmentNotification, abstract, with OfferReceived, OfferExpired, AssignmentReceived, and AssignmentRemoved extending it.

Method	Returns
`via(object $notifiable)`	`array`
`toMail(object $notifiable)`	`MailMessage`
`toArray(object $notifiable)`	`array`

The constructor takes the assignment as assignment.

Exceptions

Every exception extends Exceptions\AssignmentException. See exceptions.

Console

assignment:tick. See console commands.

API reference.

This page lists every public method, model reader, enum, and contract that the 1.x versioning promise covers.

The versioning promise covers everything on this page. Nothing listed here breaks within 1.x. Anything in the package that is not listed here is internal and may change in a patch release.

Assignable trait

ByRcsc\LaravelAssignment\Concerns\Assignable

Method	Returns
`autoAssign(?string $role = null)`	`?Assignment`
`assign(Model $assignee, ?string $role = null, ?Model $by = null)`	`Assignment`
`offer(Model $assignee, ?string $role = null, ?Model $by = null, ?int $ttlSeconds = null)`	`Assignment`
`reassign(Model $newAssignee, ?string $role = null, ?Model $by = null)`	`Assignment`
`unassign(?string $role = null, ?Model $by = null)`	`Assignment`
`assignment(?string $role = null)`	`?Assignment`
`openAssignment(?string $role = null)`	`?Assignment`
`assignee(?string $role = null)`	`?Model`
`isAssigned(?string $role = null)`	`bool`
`queuedAssignment(?string $role = null)`	`?QueuedAssignment`
`assignments()`	`MorphMany`

assignment() and openAssignment() return the same row. assignments() returns rows oldest first.

Assignee trait

ByRcsc\LaravelAssignment\Concerns\Assignee

Method	Returns
`accept(Assignment $assignment)`	`Assignment`
`decline(Assignment $assignment)`	`Assignment`
`workload(?string $assignableType = null)`	`int`
`assignments()`	`MorphMany`
`activeAssignments()`	`MorphMany`
`openAssignments()`	`MorphMany`

Facade

ByRcsc\LaravelAssignment\Facades\Assignment

Method	Returns
`for(Model $assignable)`	`PendingAssignment`
`autoAssign(Model $assignable, ?string $role = null)`	`?Assignment`
`flushQueue(?string $assignableType = null)`	`int`

flushQueue() returns how many queued entries it assigned.

Builder

ByRcsc\LaravelAssignment\PendingAssignment, returned by Assignment::for().

Method	Returns
`among(iterable\|Closure $candidates)`	`self`
`role(?string $role)`	`self`
`scope(?string $scope)`	`self`
`using(string\|SelectionPolicy\|Closure $policy)`	`self`
`by(?Model $actor)`	`self`
`expiresIn(?int $seconds)`	`self`
`assign()`	`?Assignment`
`offer()`	`?Assignment`
`queue(int $priority = 0)`	`QueuedAssignment`

among() accepts a collection, an array, or a closure receiving the assignable and returning either. Candidates must be persisted Eloquent models. Anything else raises an UnexpectedValueException.

assign() and offer() return null when the candidate list is empty or the policy selects nobody. Every other failure throws.

Omitting scope() derives one from the assignable class and the role. Omitting using() selects at random.

Assignment model

ByRcsc\LaravelAssignment\Models\Assignment

Relations

Relation	Points at
`assignable()`	The model being assigned
`assignee()`	The model holding it
`assignedBy()`	The actor, null when the engine created the row

Attributes

Attribute	Type
`role`	`?string`
`status`	`AssignmentStatus`
`ended_reason`	`?EndReason`
`scope`	`?string`
`offered_at`	`?CarbonImmutable`
`accepted_at`	`?CarbonImmutable`
`expires_at`	`?CarbonImmutable`
`ended_at`	`?CarbonImmutable`

Predicates and actions

Method	Returns
`isOpen()`	`bool`
`isActive()`	`bool`
`isOffered()`	`bool`
`isEnded()`	`bool`
`isExpired()`	`bool`
`complete(?Model $by = null)`	`self`

Query scopes

Scope	Matches
`open()`	Active, or offered and not past expiry
`active()`	Status is active
`offered()`	Status is offered
`ended()`	Status is ended
`expired()`	Offered, with an expiry that has passed

QueuedAssignment model

ByRcsc\LaravelAssignment\Models\QueuedAssignment

Member	Type
`assignable()`	`MorphTo`
`role`	`?string`
`priority`	`int`
`queued_at`	`CarbonImmutable`

Profiles

ByRcsc\LaravelAssignment\AssignmentProfile, abstract.

Method	Returns	Default
`candidates(Model $assignable, ?string $role)`	`iterable`	abstract
`policy(Model $assignable, ?string $role)`	`string\|SelectionPolicy\|Closure`	abstract
`scope(Model $assignable, ?string $role)`	`?string`	`null`
`mode(Model $assignable, ?string $role)`	`Mode`	`Mode::Assign`
`offerTtl(Model $assignable, ?string $role)`	`?int`	`null`
`queueWhenEmpty(Model $assignable, ?string $role)`	`bool`	`true`
`queuePriority(Model $assignable, ?string $role)`	`int`	`0`

Selection

ByRcsc\LaravelAssignment\Contracts\SelectionPolicy

public function select(
    Model $assignable,
    Collection $candidates,
    ScopeState $state,
): ?Model;

Shipped implementations:

Class	Constructor
`Policies\RoundRobin`	none
`Policies\LeastWorkload`	`__construct(?string $assignableType = null)`, or `LeastWorkload::of(string $assignableType)`
`Policies\Random`	none
`Policies\FirstAvailable`	none

ByRcsc\LaravelAssignment\ScopeState

Method	Returns
`get(string $key, mixed $default = null)`	`mixed`
`put(string $key, mixed $value)`	`self`
`persist()`	`void`

Keys accept dot notation. The engine calls persist() after a successful write, so a policy does not need to.

Enums

Enums\AssignmentStatus: Offered, Active, Ended.

Enums\EndReason: Unassigned, Reassigned, Declined, Expired, Completed.

Enums\Mode: Assign, Offer.

Each enum is string backed, and the case values are the lowercase names.

Events

See events and listeners.

Notifications

Notifications\AssignmentNotification, abstract, with OfferReceived, OfferExpired, AssignmentReceived, and AssignmentRemoved extending it.

Method	Returns
`via(object $notifiable)`	`array`
`toMail(object $notifiable)`	`MailMessage`
`toArray(object $notifiable)`	`array`

The constructor takes the assignment as assignment.

Exceptions

Every exception extends Exceptions\AssignmentException. See exceptions.

Console

assignment:tick. See console commands.

API reference.

Assignable trait

Assignee trait

Facade

Builder

Assignment model

Relations

Attributes

Predicates and actions

Query scopes

QueuedAssignment model

Profiles

Selection

Enums

Events

Notifications

Exceptions

Console

What to read next

API reference.

Assignable trait

Assignee trait

Facade

Builder

Assignment model

Relations

Attributes

Predicates and actions

Query scopes

QueuedAssignment model

Profiles

Selection

Enums

Events

Notifications

Exceptions

Console

What to read next