Menu

## UniversalGenericService extends GenericService
in package
Uses CreateMixin, RetrieveMixin, DeleteMixin, UpdateMixin, RandomMixin, ListMixin

AbstractYes
UniversalGenericService.php : 17

Adds the retrieve/details, create, list, update, random and delete actions to the service.

### 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.
createAction() : BaseResponse
  Create a new item in the table You can use `save` as an alias for this method
deleteAction() : BaseResponse
  Delete an item in the table
deleteCache() : bool
  Delete the cache for the key.
detailsAction() : BaseResponse
  Alias for the `retrieve` action
editAction() : BaseResponse
  Alias for the `update` action
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
  This hook will receive every file found in your request and you can handle it as you wish.
hasCache() : bool
  Check if the cache has the key.
listAction() : BaseResponse
  List all items in the table that match the given criteria
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.
randomAction() : BaseResponse
  Get a random item or items from the table
retrieveAction() : BaseResponse
  Retrieve a single item from the table You can use `details` as an alias for this method
saveAction() : BaseResponse
  Alias for the `create` action
setCache() : bool
setCacheInstance() : void
  Set the cache instance to use for caching.
updateAction() : BaseResponse
  Update an item in the table You can use `edit` as an alias for this method
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

Cacheable.php : 24

The cache prefix to use for caching.

`public string $cachePrefix = __CLASS__`

#### $cacheTtl

Cacheable.php : 30

The cache ttl to use for caching.

`public int $cacheTtl = 60`

Defaults to 60 seconds.

#### $connection

GenericService.php : 45
`public string|null $connection = null`

The connection to use. Default is `db`.

#### $createColumns

GenericService.php : 56
`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

JoinContract.php : 72
`public JoinType $defaultJoinType = \Pionia\Http\Services\JoinType::INNER`

The default join type to use when joining tables.

#### $fileColumns

GenericService.php : 68

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

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

#### $joinAliases

JoinContract.php : 51
`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

JoinContract.php : 23
`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

JoinContract.php : 37
`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

GenericService.php : 30
`public int $limit = 10`

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

#### $listColumns

GenericService.php : 50
`public array<string|int, mixed>|null $listColumns = null`

The columns to return in all requests returning data.

#### $offset

GenericService.php : 35
`public int $offset = 0`

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

#### $pk_field

GenericService.php : 40
`public string $pk_field = 'id'`

The primary key field name. Default is `id`.

#### $table

GenericService.php : 19
`public string $table`

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

#### $updateColumns

GenericService.php : 62
`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

Cacheable.php : 19

The cache instance to use for caching.

`private PioniaCache|null $cacheInstance = null`

#### $dontRelate

GenericService.php : 25

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

`private bool $dontRelate = false`

### Methods

#### __construct()

GenericService.php : 85
`public __construct(PioniaApplication $app, Request $request) : mixed`

##### Parameters

$app : PioniaApplication
$request : Request

#### cache()

Cacheable.php : 53

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

Cacheable.php : 205

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

#### createAction()

CreateMixin.php : 19

Create a new item in the table You can use `save` as an alias for this method

`public createAction() : BaseResponse`

##### Tags

throws
  Exception

##### Return values

BaseResponse

#### deleteAction()

DeleteMixin.php : 18

Delete an item in the table

`public deleteAction() : BaseResponse`

##### Tags

throws
  Exception

##### Return values

BaseResponse

#### deleteCache()

Cacheable.php : 130

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

#### detailsAction()

RetrieveMixin.php : 29

Alias for the `retrieve` action

`public detailsAction() : BaseResponse`

##### Tags

throws
  Exception

##### Return values

BaseResponse

#### editAction()

UpdateMixin.php : 28

Alias for the `update` action

`public editAction() : BaseResponse`

##### Tags

throws
  Exception

##### Return values

BaseResponse

#### getCache()

Cacheable.php : 84
`public getCache( $key[, bool|null $exact = false ]) : mixed`

##### Parameters

$key :
$exact : bool|null = false

#### getCacheInstance()

Cacheable.php : 221
`public getCacheInstance() : PioniaCache|null`

##### Return values

PioniaCache|null

#### getItem()

EventsContract.php : 100

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

`public getItem() : null|object`

##### Return values

null|object

#### getItems()

EventsContract.php : 109

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

EventsContract.php : 118

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

UploadsContract.php : 22

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

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

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.

##### Return values

mixed —

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

#### hasCache()

Cacheable.php : 183

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

#### listAction()

ListMixin.php : 20

List all items in the table that match the given criteria

`public listAction() : BaseResponse`

##### Tags

throws
  Exception

##### Return values

BaseResponse

#### postCreate()

EventsContract.php : 63

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

EventsContract.php : 90

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

EventsContract.php : 75

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

EventsContract.php : 39

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

EventsContract.php : 51

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

EventsContract.php : 26

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

#### randomAction()

RandomMixin.php : 19

Get a random item or items from the table

`public randomAction() : BaseResponse`

##### Tags

throws
  BaseDatabaseException
throws
  Exception

##### Return values

BaseResponse

#### retrieveAction()

RetrieveMixin.php : 20

Retrieve a single item from the table You can use `details` as an alias for this method

`public retrieveAction() : BaseResponse`

##### Tags

throws
  Exception

##### Return values

BaseResponse

#### saveAction()

CreateMixin.php : 28

Alias for the `create` action

`public saveAction() : BaseResponse`

##### Tags

throws
  Exception

##### Return values

BaseResponse

#### setCache()

Cacheable.php : 102
`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()

Cacheable.php : 36

Set the cache instance to use for caching.

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

##### Parameters

$cache : PioniaCache|null

#### updateAction()

UpdateMixin.php : 19

Update an item in the table You can use `edit` as an alias for this method

`public updateAction() : BaseResponse`

##### Tags

throws
  Exception

##### Return values

BaseResponse

#### updateCache()

Cacheable.php : 71
`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()

CrudContract.php : 92

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

CrudContract.php : 217

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

CrudContract.php : 283
`protected checkIfFieldPassesAllValidations(mixed $field) : mixed`

##### Parameters

$field : mixed

##### Tags

throws
  Exception

#### createItem()

CrudContract.php : 309

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

`protected createItem() : object|null`

##### Tags

throws
  Exception

##### Return values

object|null

#### defaultUpload()

UploadsContract.php : 34

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

CrudContract.php : 254

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

CrudContract.php : 145

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

CrudContract.php : 377

Retrieve all with pagination

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

##### Tags

throws
  Exception

##### Return values

array<string|int, mixed>|null

#### getOne()

CrudContract.php : 174

Retrieve in CRUD, returns on Item at a time.

`protected getOne() : object|null`

##### Tags

throws
  Exception

##### Return values

object|null

#### hasLimit()

CrudContract.php : 200
`protected hasLimit() : mixed`

#### hasOffset()

CrudContract.php : 205
`protected hasOffset() : mixed`

#### isInJoinMode()

CrudContract.php : 240
`protected isInJoinMode() : bool`

##### Return values

bool

#### paginate()

CrudContract.php : 353
`protected paginate() : array<string|int, mixed>|null`

##### Tags

throws
  BaseDatabaseException
throws
  Exception

##### Return values

array<string|int, mixed>|null

#### randomItem()

CrudContract.php : 390
`protected randomItem() : mixed`

##### Tags

throws
  Exception

#### updateItem()

CrudContract.php : 419

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

JoinContract.php : 157

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

Cacheable.php : 166
`private cleanCacheKey(string $key) : string`

##### Parameters

$key : string

##### Return values

string

#### cleanRelationColumns()

CrudContract.php : 47

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

CrudContract.php : 19

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

JoinContract.php : 141

Will be used when we are listing everything.

`private getAllItemsJoined() : array<string|int, mixed>`

##### Tags

throws
  Exception

##### Return values

array<string|int, mixed>

#### getFieldValue()

GenericService.php : 77

Picks the value of a field from the request data

`private getFieldValue( $name) : mixed|UploadedFile|null`

##### Parameters

$name :

##### Return values

mixed|UploadedFile|null

#### getKeyName()

Cacheable.php : 152

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

CrudContract.php : 79

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

CrudContract.php : 192

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

JoinContract.php : 125

Will be used when we are getting a single item.

`private getOneJoined() : object|null`

##### Tags

throws
  Exception

##### Return values

object|null

#### joinQuery()

JoinContract.php : 205

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

Cacheable.php : 226
`private logger() : LoggerInterface|null`

##### Return values

LoggerInterface|null

#### primaryKey()

CrudContract.php : 403

Returns the primary key field

`private primaryKey() : bool|string`

##### Tags

throws
  Exception

##### Return values

bool|string

#### switchJoin()

JoinContract.php : 180
`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()

JoinContract.php : 78

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

## Search results