CoolCMS API

RatingRepository extends ApiRepository
in package
uses SaveTrait

FinalYes

Front repository that reads through the Api bridge and uses the query cache when the service has it enabled (`cache.config.enabledServices`).

This is the deliberate opposite of ApiRepository: the front end only displays data, so a 5 minute old number is at most cosmetic, whereas the admin reads it into a form that is written back to the DB.

->useCache(false) on the query object overrides the policy for one query; it travels to the payload as ApiBridge::PARAM_USE_CACHE.

IMPORTANT: null is passed on as null (no opinion), not as true. If this layer substituted true, it would override QueryCacheContext, and reads through a front manager inside an admin request (AssetManager, ThemeManager, UserManager) would still be served from the cache. The true default therefore lives in the bridge.

Table of Contents

Properties

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

Methods

__construct()  : mixed
canRespondTo()  : bool
Tells whether the caller may reply to the review. A read check (not a mutation); the same call works internally (reflection returns the array directly) and externally (JSON).
find()  : array<string|int, mixed>
findAll()  : array<string|int, mixed>
findBy()  : array<string|int, mixed>
myVotes()  : array<int, bool>
Returns how this visitor voted on the displayed ratings (batch for the whole page); the UI highlights their choice and does not offer it again.
report()  : Result
Reports an inappropriate review to the administrator. Response handling is the same as in `vote()`; the caller supplies `userId`/`ip` from the server identity.
save()  : Result
saveReply()  : Result
Writes the reply to a rating via the dedicated action `save-reply` (`:Api:Base:Rating:saveReply`), not the generic `save`.
updateColumns()  : Result
vote()  : Result
Votes on the helpfulness of one rating ("was this review helpful?").
failSoftRead()  : array<string|int, mixed>
Normalizes a bridge response to plain data; a failed envelope or a non-array gives `[]`.
getApiCallSource()  : string
Returns the caller branch ({@see \App\Core\Bridge\ApiBridge::PARAM_SOURCE}); implemented by the Front and Admin base `ApiRepository`.

Properties

$apiEndpoint

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

protected string $apiEndpoint = 'api/base/rating'

Methods

canRespondTo()

Tells whether the caller may reply to the review. A read check (not a mutation); the same call works internally (reflection returns the array directly) and externally (JSON).

public canRespondTo(int $ratingId, int $userId) : bool

The endpoint returns a Result envelope with the payload in a subfield (data.canRespond), not a bare bool. It is read fail-closed: anything other than success=true with data.canRespond === true (including a guard PERMISSION_DENIED, a bridge outage or a foreign shape) yields false.

Parameters
$ratingId : int
$userId : int
Return values
bool

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>

myVotes()

Returns how this visitor voted on the displayed ratings (batch for the whole page); the UI highlights their choice and does not offer it again.

public myVotes(array<int, int> $ratingIds, int|null $userId, string $ip) : array<int, bool>

NOTE: $ratingIds goes through the bridge as a comma-separated string (like UserRepository::findPublicProfiles()), not as an array.

Fail-closed: anything other than success === true with an array in data.votes yields an empty array.

Parameters
$ratingIds : array<int, int>
$userId : int|null
$ip : string
Return values
array<int, bool> —

map ratingId => voted for (true) / against (false)

report()

Reports an inappropriate review to the administrator. Response handling is the same as in `vote()`; the caller supplies `userId`/`ip` from the server identity.

public report(int $ratingId, int|null $userId, string $ip) : Result
Parameters
$ratingId : int
$userId : int|null
$ip : string
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

saveReply()

Writes the reply to a rating via the dedicated action `save-reply` (`:Api:Base:Rating:saveReply`), not the generic `save`.

public saveReply(int $ratingId, string|null $response) : Result

The reason is authorization, not cosmetics: :Api:Base:Rating:save has an owner grant held by the review author, while the owner of the rated object may reply. The Api guard verifies ownership from the DB; this repository sends only the record address and the text.

Parameters
$ratingId : int
$response : 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

vote()

Votes on the helpfulness of one rating ("was this review helpful?").

public vote(int $ratingId, bool $up, int|null $userId, string $ip) : Result

userId/ip must come from the caller's identity (session, getRemoteAddress()), never from a form; dedup and the anonymous voting policy are handled by RatingVoteManager::vote().

Parameters
$ratingId : int
$up : bool
$userId : int|null
$ip : string
Return values
Result

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()

Returns the caller branch ({@see \App\Core\Bridge\ApiBridge::PARAM_SOURCE}); implemented by the Front and Admin base `ApiRepository`.

protected abstract getApiCallSource() : string
Return values
string
On this page

Search results