CoolCMS API

RegionManager extends Manager
in package

Abstract front manager generic over the entity type and its service.

Tags
extends

Table of Contents

Constants

SEARCH_MIN_LEVEL  : int = 1
Location search (hero box): the country too; if it had `name_ascii`, the suggest would offer it.
SEARCH_LIMIT  : int = 5
An exact match is always in the first suggest sort group, so no more items are needed.

Properties

$service  : RegionService
$appContext  : AppContext
$cacheTagInvalidator  : CacheTagInvalidator|null
Post-commit invalidator of the wire-payload query cache (tag bump per entity class).
$languageContext  : LanguageContext|null
$paramsConfig  : Config|null
Neon parameters (`%params%`: server paths and directories), set by the decorator (`decorators.neon`) like `setAppContext()`.
$presenterContext  : PresenterContext
$settingContext  : SettingContext
$suggestableRegions  : bool|null
Result of {@see hasSuggestableRegions()} for this request (the SearchBox can be on the page several times).

Methods

__construct()  : mixed
find()  : SingleQuery<string|int, T>
Finds one entity by ID and returns a `SingleQuery` object.
findAll()  : Query<string|int, T>
Finds all entities and returns a `Query` object.
findBy()  : SingleQuery<string|int, T>
Finds one entity by filters and returns a `SingleQuery` object.
findLocality()  : RegionLocality|null
Region node for validating a municipality choice and the label of the stored value; `null` = does not exist.
geocode()  : GeocodingLookup
Point of a free text unknown to the dataset ("within X km" filter): cache then Google run in the Api (`:Api:System:Region:geocode`). Empty text is not sent to the Api.
getAppContext()  : AppContext
getLanguageContext()  : LanguageContext|null
getPresenterContext()  : PresenterContext
getSettingContext()  : SettingContext
getSettings()  : array<int, array<string, mixed>>
getTotalCount()  : int|null
Returns the total count of the last `findAll()` of this manager's service, computed only when the query asked for it (`findAll(..., computeTotalCount: true)`); otherwise the last stored value.
hasSuggestableRegions()  : bool
Does the website have data for the suggester? Below the countries there must be an active node with `country_code` and `name_ascii` (municipality/region import). A website with countries only (no import) keeps the `<select>`; the data state decides, not a switch.
initializeAllContexts()  : void
resolveRouteRegionId()  : int|null
Region id from the `regionId` route parameter: the router returns it translated to the translation `href` (`RegionNameTranslator`), a link built in code may carry it as a number.
resolveSearchRegionId()  : int|null
Search region from the location field (hero box), by source order: 1. the id chosen in the suggester when it is active and the text still contains its name (without JS the hidden value from the URL is sent again with a different text, as in `GeocodingManager`); 2. a suggest over the text: an exact match of the name or the whole postcode, otherwise the only offered item (a city name plus Enter without a pick gives that city); 3. `null` = the location cannot be determined (empty text, nothing found, rate limit).
setAppContext()  : $this
setCacheTagInvalidator()  : static
setLanguageContext()  : $this
setParamsConfig()  : static
setPresenterContext()  : $this
setSettingContext()  : $this
suggest()  : RegionSuggestResult
Municipality/postcode suggester through the Api. An empty query (short input) is not sent to the Api at all.
bumpCacheTags()  : void
Bumps cache tags for the entity after commit: its class, the owned-cascade classes from metadata and the optional `additionalCacheTags()` of the manager.
bumpCacheTagsExplicit()  : void
Bumps the given classes explicitly (raw-DBAL paths with a cross-entity effect).
bumpCacheTagsForClass()  : void
Bumps cache tags by class name when there is no instance (bulk delete, `updateColumns()`, raw DBAL, tree operations).
classCacheTags()  : array<string|int, string>
Returns extra tags for a bump that has no entity, typically tree operations ({@see \App\Core\Traits\Api\Models\Managers\TreeTrait::treeTransaction()}) that rewrite `lft`/`rgt` on many rows.
getService()  : TService
Returns the service for the traits.

Constants

SEARCH_MIN_LEVEL

Location search (hero box): the country too; if it had `name_ascii`, the suggest would offer it.

public int SEARCH_MIN_LEVEL = 1

SEARCH_LIMIT

An exact match is always in the first suggest sort group, so no more items are needed.

private int SEARCH_LIMIT = 5

Properties

$cacheTagInvalidator

Post-commit invalidator of the wire-payload query cache (tag bump per entity class).

protected CacheTagInvalidator|null $cacheTagInvalidator = null

Set by the decorator (decorators.neon) like setParamsConfig(). Nullable and fail-open: without wiring (or without Redis) a bump is a no-op.

$paramsConfig

Neon parameters (`%params%`: server paths and directories), set by the decorator (`decorators.neon`) like `setAppContext()`.

protected Config|null $paramsConfig = null

Write logic (asset directories) reads paths from here, not from getSettings() or the setting context, which may be filled by the client without server paths. The property cannot be named $config: it collides with the promoted $config in some managers.

$suggestableRegions

Result of {@see hasSuggestableRegions()} for this request (the SearchBox can be on the page several times).

private bool|null $suggestableRegions = null

Methods

find()

Finds one entity by ID and returns a `SingleQuery` object.

public find(int $id[, string|array<string|int, mixed> $includes = [] ]) : SingleQuery<string|int, T>

Usage:

$query = $manager->find(1, ['translations']);
$entity = $query->include(['routes'])->execute(); // or ->get()
$title = $query->getTitle(); // magic call, forwarded to the entity
Parameters
$id : int

entity ID

$includes : string|array<string|int, mixed> = []

relations to load ['translations', 'routes'], or '*' for all

Return values
SingleQuery<string|int, T>

findAll()

Finds all entities and returns a `Query` object.

public findAll([array<string|int, mixed>|null $filters = [] ][, array<string|int, mixed>|null $orderBy = null ][, int|null $offset = null ][, int|null $limit = null ][, array<string|int, mixed>|null $columns = null ][, string|array<string|int, mixed> $includes = [] ][, bool $computeTotalCount = false ]) : Query<string|int, T>

Usage:

$query = $manager->findAll(['active' => true], ['created' => 'desc']);
$items = $query->include(['translations'])->limit(10)->execute();
foreach ($query as $item) { ... } // the query runs lazily on iteration
Parameters
$filters : array<string|int, mixed>|null = []

filters for the where conditions

$orderBy : array<string|int, mixed>|null = null

ordering ['column' => 'ASC/DESC']

$offset : int|null = null

offset for pagination

$limit : int|null = null

result limit

$columns : array<string|int, mixed>|null = null

specific columns to load

$includes : string|array<string|int, mixed> = []

relations to load ['translations', 'routes.translations'], or '*' for all

$computeTotalCount : bool = false

whether to compute the total count for pagination

Return values
Query<string|int, T>

findBy()

Finds one entity by filters and returns a `SingleQuery` object.

public findBy([array<string|int, mixed> $filters = [] ][, string|array<string|int, mixed> $includes = [] ]) : SingleQuery<string|int, T>

Usage:

$query = $manager->findBy(['slug' => 'my-page'], ['translations']);
$entity = $query->include(['routes'])->execute(); // or ->get()
$title = $query->getTitle(); // magic call, forwarded to the entity
Parameters
$filters : array<string|int, mixed> = []

filters for the where conditions

$includes : string|array<string|int, mixed> = []

relations to load ['translations', 'routes'], or '*' for all

Return values
SingleQuery<string|int, T>

findLocality()

Region node for validating a municipality choice and the label of the stored value; `null` = does not exist.

public findLocality(int $id, int $languageId) : RegionLocality|null
Parameters
$id : int
$languageId : int
Return values
RegionLocality|null

geocode()

Point of a free text unknown to the dataset ("within X km" filter): cache then Google run in the Api (`:Api:System:Region:geocode`). Empty text is not sent to the Api.

public geocode(string $text, int $languageId, int|null $preferRegionId) : GeocodingLookup
Parameters
$text : string
$languageId : int
$preferRegionId : int|null
Return values
GeocodingLookup

getSettings()

public getSettings() : array<int, array<string, mixed>>
Return values
array<int, array<string, mixed>>

getTotalCount()

Returns the total count of the last `findAll()` of this manager's service, computed only when the query asked for it (`findAll(..., computeTotalCount: true)`); otherwise the last stored value.

public getTotalCount() : int|null

Same value as Query::getTotalCount() of that query.

Return values
int|null

hasSuggestableRegions()

Does the website have data for the suggester? Below the countries there must be an active node with `country_code` and `name_ascii` (municipality/region import). A website with countries only (no import) keeps the `<select>`; the data state decides, not a switch.

public hasSuggestableRegions() : bool
Return values
bool

resolveRouteRegionId()

Region id from the `regionId` route parameter: the router returns it translated to the translation `href` (`RegionNameTranslator`), a link built in code may carry it as a number.

public resolveRouteRegionId(mixed $routeValue, int $languageId) : int|null
Parameters
$routeValue : mixed
$languageId : int
Return values
int|null

resolveSearchRegionId()

Search region from the location field (hero box), by source order: 1. the id chosen in the suggester when it is active and the text still contains its name (without JS the hidden value from the URL is sent again with a different text, as in `GeocodingManager`); 2. a suggest over the text: an exact match of the name or the whole postcode, otherwise the only offered item (a city name plus Enter without a pick gives that city); 3. `null` = the location cannot be determined (empty text, nothing found, rate limit).

public resolveSearchRegionId(int|null $regionId, string $text, int $languageId, int|null $preferRegionId) : int|null
Parameters
$regionId : int|null
$text : string
$languageId : int
$preferRegionId : int|null
Return values
int|null

setParamsConfig()

public setParamsConfig(Config $paramsConfig) : static
Parameters
$paramsConfig : Config
Return values
static

bumpCacheTags()

Bumps cache tags for the entity after commit: its class, the owned-cascade classes from metadata and the optional `additionalCacheTags()` of the manager.

protected bumpCacheTags(object $entity) : void

Fail-open (the invalidator swallows exceptions). Called from the manager Save/Delete/Tree traits after the commit.

Parameters
$entity : object

bumpCacheTagsExplicit()

Bumps the given classes explicitly (raw-DBAL paths with a cross-entity effect).

protected bumpCacheTagsExplicit(array<string|int, string> $classes) : void
Parameters
$classes : array<string|int, string>

bumpCacheTagsForClass()

Bumps cache tags by class name when there is no instance (bulk delete, `updateColumns()`, raw DBAL, tree operations).

protected bumpCacheTagsForClass(class-string $rootClass[, array<string|int, string> $extraTags = [] ]) : void

Bumps the root class and its owned-cascade classes.

Parameters
$rootClass : class-string
$extraTags : array<string|int, string> = []

classCacheTags()

Returns extra tags for a bump that has no entity, typically tree operations ({@see \App\Core\Traits\Api\Models\Managers\TreeTrait::treeTransaction()}) that rewrite `lft`/`rgt` on many rows.

protected classCacheTags() : array<string|int, string>

IMPORTANT: additionalCacheTags(object) receives an entity, so a class-level bump cannot use it; without this hook a delete would lose the cross-entity tag (Comment to CommentThread). A manager whose cross-entity tag does not depend on a particular entity returns it here.

NOTE: unlike additionalCacheTags(), this hook is declared (with an empty default) instead of being an opt-in through method_exists(); method_exists() is always true in a manager that has the method, which phpstan reports as alreadyNarrowedType.

Return values
array<string|int, string>

getService()

Returns the service for the traits.

protected getService() : TService
Return values
TService
On this page

Search results