CoolCMS API

WorkListRepository extends ApiRepository
in package
uses BridgeFailureTrait

FinalYes

Bridge to the narrow Api actions of a job: invoicing the selected work sheets, its read-only preview, and archiving or restoring a job.

WorkList is a job (historical name); WorkSheet is a work sheet inside a job. The actions are bridge-only (no action*()), like confirm/cancel in ReservationRepository: money and lock operations must not go through the generic save()/updateColumns().

Every method builds a Result by hand from a flat Api JSON ({success, code, message, errorCode, ...}), not the standard five-key Result envelope; the presenter reads isSuccess() and the individual fields for flash and redirect.

Table of Contents

Properties

$apiEndpoint  : string
Api presenter path (e.g. `api/system/page`); set by each concrete repository.
$bridge  : ApiBridge

Methods

__construct()  : mixed
archive()  : Result
Archives a job: `open` to `archived`.
delete()  : Result
deleteAll()  : Result
find()  : array<string|int, mixed>
findAll()  : array<string|int, mixed>
findBy()  : array<string|int, mixed>
invoicePreview()  : Result
Returns the read-only invoice preview for the invoice modal, including the safeguard against work items without hours.
invoiceSheets()  : Result
Issues an invoice from the selected work sheets.
save()  : Result
unarchive()  : Result
Restores a job from the archive: `archived` to `open` (the modal asks for a reason).
updateColumns()  : Result
bridgeException()  : Result
Turns a caught bridge exception into `API_ERROR` without the exception text; the detail goes to the `admin.bridge` log channel.
bridgeMessage()  : string|null
Returns the message of a flat bridge response: null for a failure with a technical code (detail goes to the log), otherwise unchanged.
failSoftRead()  : array<string|int, mixed>
Normalizes a bridge response to plain data; a failed envelope or a non-array gives `[]`.
getApiCallSource()  : string
Branch marker for writes ({@see ApiBridge::PARAM_SOURCE}), read by the shared repository `SaveTrait`.
buildResult()  : Result
resultFromInvoiceResponse()  : Result
resultFromPreviewResponse()  : Result
resultFromTransitionResponse()  : Result

Properties

$apiEndpoint

Api presenter path (e.g. `api/system/page`); set by each concrete repository.

protected string $apiEndpoint = 'api/company/work-list'

Methods

delete()

public delete(int|array<string|int, mixed> $id) : Result
Parameters
$id : int|array<string|int, mixed>
Return values
Result

deleteAll()

public deleteAll([array<string|int, mixed> $filters = [] ]) : Result
Parameters
$filters : array<string|int, mixed> = []
Return values
Result

find()

public find(int $id[, string|array<string|int, mixed> $includes = [] ][, bool|null $useCache = null ]) : array<string|int, mixed>
Parameters
$id : int
$includes : string|array<string|int, mixed> = []
$useCache : bool|null = null
Return values
array<string|int, mixed>

findAll()

public findAll([array<string|int, mixed>|null $filters = [] ][, array<string|int, mixed>|null $orderBys = null ][, int|null $offset = null ][, int|null $limit = null ][, array<string|int, mixed>|null $columns = null ][, bool $computeTotalCount = false ][, string|array<string|int, mixed> $includes = [] ][, bool|null $useCache = null ]) : array<string|int, mixed>
Parameters
$filters : array<string|int, mixed>|null = []
$orderBys : array<string|int, mixed>|null = null
$offset : int|null = null
$limit : int|null = null
$columns : array<string|int, mixed>|null = null
$computeTotalCount : bool = false
$includes : string|array<string|int, mixed> = []
$useCache : bool|null = null
Return values
array<string|int, mixed>

findBy()

public findBy([array<string|int, mixed>|null $filters = [] ][, string|array<string|int, mixed> $includes = [] ][, bool|null $useCache = null ]) : array<string|int, mixed>
Parameters
$filters : array<string|int, mixed>|null = []
$includes : string|array<string|int, mixed> = []
$useCache : bool|null = null
Return values
array<string|int, mixed>

invoicePreview()

Returns the read-only invoice preview for the invoice modal, including the safeguard against work items without hours.

public invoicePreview(int $id, array<int, int> $sheetIds) : Result

IMPORTANT: not fail-soft. The response is fully flattened into Result::getData(), but on failure an empty sheets key is never presented as a valid result: isSuccess() is the only source of truth and the caller must not render the panel at all on failure. A failure is not an empty but valid selection.

Parameters
$id : int
$sheetIds : array<int, int>
Return values
Result

invoiceSheets()

Issues an invoice from the selected work sheets.

public invoiceSheets(int $id, array<int, int> $sheetIds, bool $createFollowUpSheet, string|null $followUpName) : Result
Parameters
$id : int
$sheetIds : array<int, int>
$createFollowUpSheet : bool
$followUpName : string|null
Return values
Result

save()

public save(array<string, mixed> $data[, array<string, mixed> $meta = [] ][, array<int, string> $skipFields = [] ]) : Result
Parameters
$data : array<string, mixed>

extracted entity payload

$meta : array<string, mixed> = []
$skipFields : array<int, string> = []
Return values
Result

unarchive()

Restores a job from the archive: `archived` to `open` (the modal asks for a reason).

public unarchive(int $id, string|null $reason) : Result
Parameters
$id : int
$reason : string|null
Return values
Result

updateColumns()

public updateColumns(array<string|int, mixed> $ids, array<string, mixed> $values) : Result
Parameters
$ids : array<string|int, mixed>

ids or composite-id arrays

$values : array<string, mixed>

property name => new value

Return values
Result

bridgeException()

Turns a caught bridge exception into `API_ERROR` without the exception text; the detail goes to the `admin.bridge` log channel.

protected bridgeException(Throwable $e, string $endpoint) : Result
Parameters
$e : Throwable
$endpoint : string
Return values
Result

bridgeMessage()

Returns the message of a flat bridge response: null for a failure with a technical code (detail goes to the log), otherwise unchanged.

protected bridgeMessage(array<string, mixed> $response, ResultCode $code, string $endpoint) : string|null
Parameters
$response : array<string, mixed>
$code : ResultCode
$endpoint : string
Return values
string|null

failSoftRead()

Normalizes a bridge response to plain data; a failed envelope or a non-array gives `[]`.

protected failSoftRead(mixed $response, string $endpoint) : array<string|int, mixed>

NOTE: it does not log on purpose. ApiBridge::call(), which sees both the endpoint and the caller, has already written the API_FAILSOFT source=bridge line; a second copy would turn one failure into three lines in auth.log.

Parameters
$response : mixed
$endpoint : string

only for call readability; the log takes the endpoint from the bridge

Return values
array<string|int, mixed>

getApiCallSource()

Branch marker for writes ({@see ApiBridge::PARAM_SOURCE}), read by the shared repository `SaveTrait`.

protected getApiCallSource() : string
Return values
string

buildResult()

private buildResult(array<string, mixed> $response, array<string, mixed> $data) : Result
Parameters
$response : array<string, mixed>
$data : array<string, mixed>
Return values
Result

resultFromTransitionResponse()

private resultFromTransitionResponse(mixed $response) : Result
Parameters
$response : mixed
Return values
Result
On this page

Search results