Pionia Core

GenericService extends Service
in package
Uses EventsContract, CrudContract, JoinContract, UploadsContract

AbstractYes

Base Service for generic services

Table of Contents

Properties

$cachePrefix  : string
The cache prefix to use for caching.
$cacheTtl  : int
The cache ttl to use for caching.
$connection  : string|null
$createColumns  : array<string|int, mixed>|null
$defaultJoinType  : JoinType
$fileColumns  : array<string|int, mixed>|null
Define columns that should be received as files in this array.
$joinAliases  : array<string|int, mixed>|null
$joins  : array<string|int, mixed>|null
$joinTypes  : array<string|int, mixed>|null
$limit  : int
$listColumns  : array<string|int, mixed>|null
$offset  : int
$pk_field  : string
$table  : string
$updateColumns  : array<string|int, mixed>|null
$cacheInstance  : PioniaCache|null
The cache instance to use for caching.
$dontRelate  : bool
Can be mutated by the frontend to turn off relationships and go back to querying the base table again.

Methods

__construct()  : mixed
cache()  : bool|mixed
Caches the value if the value is not null.
ClearByKeys()  : bool
Clear the cache.
deleteCache()  : bool
Delete the cache for the key.
getCache()  : mixed
getCacheInstance()  : PioniaCache|null
getItem()  : null|object
Override this in your service to define the basis to return single item details
getItems()  : null|object
Override this in your service to define the basis to return multiple items from the database
getJoinQuery()  : null|object
Override this in your service to define the basis to return multiple items from the database
handleUpload()  : mixed
Provides the default upload behaviour for the service.
hasCache()  : bool
Check if the cache has the key.
postCreate()  : object|array<string|int, mixed>|null
This method is post create action, use it to perform any action after saving.
postDelete()  : mixed
This method is called before the delete action. Use it to perform any action before deleting.
postUpdate()  : object|array<string|int, mixed>|null
This method is post create action, use it to perform any action after saving.
preCreate()  : array<string|int, mixed>|bool|null
This method is called before the create action, use it to transform the data before saving.
preDelete()  : array<string|int, mixed>|null|object|bool
This method is called before the delete action. Use it to perform any action before deleting.
preUpdate()  : array<string|int, mixed>|bool|null
This method is called before the create action, use it to transform the data before saving.
setCache()  : bool
setCacheInstance()  : void
Set the cache instance to use for caching.
updateCache()  : void
_checkPaginationInternal()  : bool
Detects if we have pagination params anywhere in the request.
allItems()  : array<string|int, mixed>|null
Retrieve all in CRUD
checkIfFieldPassesAllValidations()  : mixed
createItem()  : object|null
Create in CRUD Saves in transactions, runs pre and post create events
defaultUpload()  : string
This hook will receive every file found in your request and you can handle it as you wish.
deleteItem()  : mixed
Delete in CRUD Handles both post and pre delete events Deletes in joined mode if defined too, but will delete only from the main table
detectPagination()  : bool
Detect if our pagination params are defined anywhere in the request.
getAllWithPagination()  : array<string|int, mixed>|null
Retrieve all with pagination
getOne()  : object|null
Retrieve in CRUD, returns on Item at a time.
hasLimit()  : mixed
hasOffset()  : mixed
isInJoinMode()  : bool
paginate()  : array<string|int, mixed>|null
randomItem()  : mixed
updateItem()  : object|array<string|int, mixed>|null
Updated an item in the db.
attachJoins()  : Join
Attaches all defined joins to the base query.
cleanCacheKey()  : string
cleanRelationColumns()  : void
If the fields are already in the format of relationships, this method reverses that including removing duplicates.
detectAndAddColumns()  : void
Checks if the frontend has defined columns we should query by.
getAllItemsJoined()  : array<string|int, mixed>
Will be used when we are listing everything.
getFieldValue()  : mixed|UploadedFile|null
Picks the value of a field from the request data
getKeyName()  : string
Converts the key to snake case and appends the current class prefix if it does not exist.
getListColumns()  : array<string|int, mixed>|string
Returns the columns we shall query from the db while querying
getOneInternal()  : null|array<string|int, mixed>|object
Gets one item from the database. Can be overridden by defining a getOne method in the service
getOneJoined()  : object|null
Will be used when we are getting a single item.
joinQuery()  : Join
Resolve the base query to base on to start joining.
logger()  : LoggerInterface|null
primaryKey()  : bool|string
Returns the primary key field
switchJoin()  : Join
weShouldJoin()  : bool
Detects whether to enter to enter the join mode or stay in the normal mode.

Properties

$cachePrefix

The cache prefix to use for caching.

public string $cachePrefix = __CLASS__

$cacheTtl

The cache ttl to use for caching.

public int $cacheTtl = 60

Defaults to 60 seconds.

$connection

public string|null $connection = null

The connection to use. Default is db.

$createColumns

public array<string|int, mixed>|null $createColumns = null

The columns to return in the create request. Only these columns will be populated from the request and saved

$defaultJoinType

public JoinType $defaultJoinType = \Pionia\Http\Services\JoinType::INNER

The default join type to use when joining tables.

$fileColumns

Define columns that should be received as files in this array.

public array<string|int, mixed>|null $fileColumns = null

$joinAliases

public array<string|int, mixed>|null $joinAliases = null

An associative array of aliases to be used for joins with the table in the service. The key is the table name and the value is the alias.

Tags
example 
[
   'student' => 's',
]

This will join the student table using the alias s.

$joins

public array<string|int, mixed>|null $joins = null

An associative array of tables to be used for joins with the table in the service. The key is the table name and the value is an array of the columns to join on.

Tags
example 
[
   'student' => ['id' => 'student_id'],
]

This will join the student table on the id column of the current table and the student_id column of the student table.

$joinTypes

public array<string|int, mixed>|null $joinTypes = null

An associative array of join types to be used for joins with the table in the service. The key is the table name and the value is the join type.

Tags
example 
[
   'student' => JoinType::INNER,
]

This will join the student table using an inner join.

$limit

public int $limit = 10

The initial number of items to return per list request can de overridden in the request.

$listColumns

public array<string|int, mixed>|null $listColumns = null

The columns to return in all requests returning data.

$offset

public int $offset = 0

The initial index to start from, can de overridden in the request.

$pk_field

public string $pk_field = 'id'

The primary key field name. Default is id.

$table

public string $table

The base table to be used in the service. This is required when in joins or not

$updateColumns

public array<string|int, mixed>|null $updateColumns = null

The columns to return in the update request. Only these columns will be populated from the request and saved. If left null, all columns defined in the request object will be updated.

$cacheInstance

The cache instance to use for caching.

private PioniaCache|null $cacheInstance = null

$dontRelate

Can be mutated by the frontend to turn off relationships and go back to querying the base table again.

private bool $dontRelate = false

Methods

cache()

Caches the value if the value is not null.

public cache(string $key[, mixed $value = null ][, mixed $ttl = null ][, bool|null $exact = false ]) : bool|mixed
Parameters
$key : string

The key to cache

$value : mixed = null

The value to cache

$ttl : mixed = null

The time to live for the cache

$exact : bool|null = false

If passed, the key won't be parsed at all, it will be cached as is.

Return values
bool|mixed

ClearByKeys()

Clear the cache.

public ClearByKeys(array<string|int, mixed> $keys[, bool|null $exact = false ]) : bool
Parameters
$keys : array<string|int, mixed>

The keys to clear

$exact : bool|null = false

If passed, the keys won't be parsed at all

Return values
bool

deleteCache()

Delete the cache for the key.

public deleteCache(string $key[, bool $exact = false ]) : bool
Parameters
$key : string

The key to delete

$exact : bool = false

If passed, the key won't be parsed at all

Return values
bool

getCache()

public getCache( $key[, bool|null $exact = false ]) : mixed
Parameters
$key :
$exact : bool|null = false

getItem()

Override this in your service to define the basis to return single item details

public getItem() : null|object
Return values
null|object

getItems()

Override this in your service to define the basis to return multiple items from the database

public getItems() : null|object
Return values
null|object

getJoinQuery()

Override this in your service to define the basis to return multiple items from the database

public getJoinQuery() : null|object
Return values
null|object

handleUpload()

Provides the default upload behaviour for the service.

public handleUpload(UploadedFile $file, string $fileName) : mixed

You can override this method in your service to provide custom upload behaviour.

Parameters
$file : UploadedFile

The file to upload

$fileName : string

The name to save the file as

Tags
throws
Exception

hasCache()

Check if the cache has the key.

public hasCache( $key[, bool|null $exact = false ]) : bool

Will not throw an exception if the key is not set or the cache is not activated.

Parameters
$key :
$exact : bool|null = false
Return values
bool

postCreate()

This method is post create action, use it to perform any action after saving.

public postCreate([array<string|int, mixed>|object|null $createdItem = null ]) : object|array<string|int, mixed>|null

You have access to the data being created in the $this->request->getData() method

Whatever is returned here is what is returned to the user

Parameters
$createdItem : array<string|int, mixed>|object|null = null
Return values
object|array<string|int, mixed>|null

postDelete()

This method is called before the delete action. Use it to perform any action before deleting.

public postDelete(PDOStatement $deleteInstance[, array<string|int, mixed>|null|object $deletedItem = null ]) : mixed

You have access to the data being updated in the $this->request->getData() method

This has no effect on the delete action. Since it is called after the delete action.

Whatever is returned here is what is returned to the user

Parameters
$deleteInstance : PDOStatement
$deletedItem : array<string|int, mixed>|null|object = null

postUpdate()

This method is post create action, use it to perform any action after saving.

public postUpdate([array<string|int, mixed>|object|null $updatedItem = null ]) : object|array<string|int, mixed>|null

You have access to the data being created in the $this->request->getData() method

Whatever is returned here is what is returned to the user

Parameters
$updatedItem : array<string|int, mixed>|object|null = null
Return values
object|array<string|int, mixed>|null

preCreate()

This method is called before the create action, use it to transform the data before saving.

public preCreate([array<string|int, mixed>|null $createItem = null ]) : array<string|int, mixed>|bool|null

You have access to the data being created in the $this->request->getData() method

Return false, null or throw an exception to stop the create action.

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

The data being created - You can modify this data before saving. Return false or null to stop the create action

Return values
array<string|int, mixed>|bool|null

preDelete()

This method is called before the delete action. Use it to perform any action before deleting.

public preDelete([array<string|int, mixed>|null|object $itemToDelete = null ]) : array<string|int, mixed>|null|object|bool

You have access to the data being updated in the $this->request->getData() method

Return false, null or throw an exception to stop the delete action.

Parameters
$itemToDelete : array<string|int, mixed>|null|object = null
Return values
array<string|int, mixed>|null|object|bool

preUpdate()

This method is called before the create action, use it to transform the data before saving.

public preUpdate([array<string|int, mixed>|null $updateItem = null ]) : array<string|int, mixed>|bool|null

You have access to the object being updated $updateItem

Return false, null or raise any exception to stop the update action.

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

The data being updated - You can modify this data before saving

Return values
array<string|int, mixed>|bool|null —

The return data is what is saved to the database, if false or null, the update action is aborted

setCache()

public setCache(string $key, mixed $value[, mixed $ttl = null ][, bool|null $exact = false ]) : bool
Parameters
$key : string
$value : mixed
$ttl : mixed = null
$exact : bool|null = false
Return values
bool

setCacheInstance()

Set the cache instance to use for caching.

public setCacheInstance(PioniaCache|null $cache) : void
Parameters
$cache : PioniaCache|null

updateCache()

public updateCache(mixed $key, mixed $newValue[, mixed $exact = false ][, int|null $ttl = null ]) : void
Parameters
$key : mixed
$newValue : mixed
$exact : mixed = false
$ttl : int|null = null

_checkPaginationInternal()

Detects if we have pagination params anywhere in the request.

protected _checkPaginationInternal(array<string|int, mixed> $data) : bool

For pagination to kick-in, both offset and limit must be defined at any of the levels defined by $this->detectPagination()

Parameters
$data : array<string|int, mixed>
Tags
see

$this->detectPagination()

Return values
bool

allItems()

Retrieve all in CRUD

protected allItems() : array<string|int, mixed>|null

Can be overridden by defining a getItems method in the service

Tags
throws
BaseDatabaseException
throws
Exception
Return values
array<string|int, mixed>|null

checkIfFieldPassesAllValidations()

protected checkIfFieldPassesAllValidations(mixed $field) : mixed
Parameters
$field : mixed
Tags
throws
Exception

createItem()

Create in CRUD Saves in transactions, runs pre and post create events

protected createItem() : object|null
Tags
throws
Exception
Return values
object|null

defaultUpload()

This hook will receive every file found in your request and you can handle it as you wish.

protected defaultUpload(UploadedFile $file, string $fileName) : string

Whatever you return here is what we shall send to the db. Returning null or false will skip the file in the entire request from being saved in the db.

Parameters
$file : UploadedFile

The file object that was uploaded.

$fileName : string

The name as defined in the request.

Tags
throws
Exception
Return values
string —

The value to be saved in the db, null or false to skip the file, or an exception to stop the entire request

deleteItem()

Delete in CRUD Handles both post and pre delete events Deletes in joined mode if defined too, but will delete only from the main table

protected deleteItem() : mixed
Tags
throws
Exception

detectPagination()

Detect if our pagination params are defined anywhere in the request.

protected detectPagination(array<string|int, mixed> $reqData) : bool

Remember these can in defined in one of the following:-

On the request root level

Parameters
$reqData : array<string|int, mixed>
Tags
example 
{
    SERVICE: "ourService",
    ACTION: "ourAction",
    LIMIT: 10, // can also be `limit: 10`
    OFFSET: 5 // can also be `offset: 5`
}

Or they can be defined under the PAGINATION/pagination key
example 
{
    SERVICE: "ourService",
    ACTION: "ourAction",
    PAGINATION:{ // can also be `pagination`
         LIMIT: 10, // can also be `limit: 10`
         OFFSET: 5 // can also be `offset: 5`
     }
}

Or in the SEARCH/search param
example

{ SERVICE: "ourService", ACTION: "ourAction", SEARCH:{ // can also be search LIMIT: 10, // can also be limit: 10 OFFSET: 5 // can also be offset: 5 } } }

Return values
bool

getAllWithPagination()

Retrieve all with pagination

protected getAllWithPagination() : array<string|int, mixed>|null
Tags
throws
Exception
Return values
array<string|int, mixed>|null

getOne()

Retrieve in CRUD, returns on Item at a time.

protected getOne() : object|null
Tags
throws
Exception
Return values
object|null

isInJoinMode()

protected isInJoinMode() : bool
Return values
bool

randomItem()

protected randomItem() : mixed
Tags
throws
Exception

updateItem()

Updated an item in the db.

protected updateItem() : object|array<string|int, mixed>|null

If updateColumns are defined, it only updates those.

It also calls both preUpdate and postUpdate hooks if defined

Tags
throws
Exception
Return values
object|array<string|int, mixed>|null

attachJoins()

Attaches all defined joins to the base query.

private attachJoins([Join|null $join = null ]) : Join
Parameters
$join : Join|null = null
Tags
throws
Exception
Return values
Join

cleanCacheKey()

private cleanCacheKey(string $key) : string
Parameters
$key : string
Return values
string

cleanRelationColumns()

If the fields are already in the format of relationships, this method reverses that including removing duplicates.

private cleanRelationColumns() : void
Tags
example 
$this->listColumns = ["alias2.name", "alias1.name(category_name), "alias1.id"];
// this will become
$this->listColumns = ["name", "name(category_name), "id"];

by the time of querying name(category_name) will take precedence of name thus we shall end up with category_name and id in the response

detectAndAddColumns()

Checks if the frontend has defined columns we should query by.

private detectAndAddColumns() : void

Works for both joined and non-joined querying. It pays respect to aliases defined, so, don't forget to respect them too!

getAllItemsJoined()

Will be used when we are listing everything.

private getAllItemsJoined() : array<string|int, mixed>
Tags
throws
Exception
Return values
array<string|int, mixed>

getFieldValue()

Picks the value of a field from the request data

private getFieldValue( $name) : mixed|UploadedFile|null
Parameters
$name :
Return values
mixed|UploadedFile|null

getKeyName()

Converts the key to snake case and appends the current class prefix if it does not exist.

private getKeyName(string $key) : string
Parameters
$key : string
Return values
string

getListColumns()

Returns the columns we shall query from the db while querying

private getListColumns() : array<string|int, mixed>|string
Return values
array<string|int, mixed>|string

getOneInternal()

Gets one item from the database. Can be overridden by defining a getOne method in the service

private getOneInternal(mixed $id) : null|array<string|int, mixed>|object
Parameters
$id : mixed
Tags
throws
Exception
Return values
null|array<string|int, mixed>|object

getOneJoined()

Will be used when we are getting a single item.

private getOneJoined() : object|null
Tags
throws
Exception
Return values
object|null

joinQuery()

Resolve the base query to base on to start joining.

private joinQuery() : Join

If the developer has not yet defined any joins, we drop it and generate a new one.

Tags
throws
Exception
Return values
Join

logger()

private logger() : LoggerInterface|null
Return values
LoggerInterface|null

primaryKey()

Returns the primary key field

private primaryKey() : bool|string
Tags
throws
Exception
Return values
bool|string

switchJoin()

private switchJoin(JoinType $joinType, Join $query, string $table) : Join
Parameters
$joinType : JoinType

The type of join to use

$query : Join

The current query we are joining to

$table : string

The table to join

Return values
Join —

The query with the join added

weShouldJoin()

Detects whether to enter to enter the join mode or stay in the normal mode.

private weShouldJoin() : bool

Normal mode queries one table at a time.

Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results