Documentation

PdbReturn extends DataObject
in package
implements PdbReturnInterface

Configuration for query return types.

  • type (string) - 'pdo' or a format type Pdb::formatRs
  • class (string) - a class name to wrap results (for 'row', 'arr', 'map-arr')
  • cache_ttl (int|bool) - cache expiry in seconds, true to use global config, false to disable
  • cache_key (string) - an override cache key, providing a user with invalidation powers
  • map_key (string|null) - a column for 'map-arr' or null for the first column
  • throw (bool) - throw an exception if the row is missing (default true)

This class can be overridden if one wants to customize the formatting behaviour. By default this base class uses the Pdb::formatRs helper.

Table of Contents

Interfaces

PdbReturnInterface
Configuration for query return types.

Properties

$cache_key  : string|null
The key for a query is generated as a shasum of the query + parameters.
$cache_ttl  : int|bool
A Time-to-live for the caching layer.
$class  : string|null
A class name.
$map_key  : string|null
Used for the return type: `map-arr`.
$throw  : bool
Whether RowMissingException should be thrown if the row is missing.
$type  : string
A return type is one support by the `format()` method of this class.

Methods

__construct()  : mixed
buildClass()  : array<string|int, object>|object|null
Format a result into class instance.
format()  : string|int|null|array<string|int, mixed>
Format the result set.
getCacheKey()  : string
The uniqueness for this return config.
getCacheTtl()  : int
Determine an appropriate TTL between the return config and pdb config.
hasFormatting()  : bool
Should this return config perform formatting?
parse()  : PdbReturn
Parse a return type config.
parseType()  : array<string|int, mixed>
A return type string may contain a few additional indicators.
update()  : void

Properties

$cache_key

The key for a query is generated as a shasum of the query + parameters.

public string|null $cache_key = null

However, one is able to override this if they wish to manually invalidate the cache before the TTL expires.

$cache_ttl

A Time-to-live for the caching layer.

public int|bool $cache_ttl = false

This enables query caching with the configured caching adapter.

If set to true this uses the Pdb ttl config.

seconds

Tags
see
PdbCache

$class

A class name.

public string|null $class = null

Wrap results in a class instance, passing the object into the constructor.

Supported types:

  • row
  • arr
  • map-arr

$map_key

Used for the return type: `map-arr`.

public string|null $map_key = null

This specifies the column to use as the key for the map.

If null, it uses the first column returned in the query.

$throw

Whether RowMissingException should be thrown if the row is missing.

public bool $throw = true

This only applies for the following return types:

  • val
  • row
  • row-num

This is also inferred by the shorthand val? style return-types when using the parse() helper.

$type

A return type is one support by the `format()` method of this class.

public string $type

The default set of return types are specified in the Pdb::RETURN enum.

This class can be extended and thus support more return types.

Methods

__construct()

public __construct([iterable<string|int, mixed> $config = [] ]) : mixed
Parameters
$config : iterable<string|int, mixed> = []

buildClass()

Format a result into class instance.

public buildClass(array<string|int, mixed> $result) : array<string|int, object>|object|null
Parameters
$result : array<string|int, mixed>
Tags
inheritdoc
Return values
array<string|int, object>|object|null

format()

Format the result set.

public format(PDOStatement $rs) : string|int|null|array<string|int, mixed>
Parameters
$rs : PDOStatement
Tags
inheritdoc
Return values
string|int|null|array<string|int, mixed>

getCacheKey()

The uniqueness for this return config.

public getCacheKey() : string
Tags
inheritdoc
Return values
string

getCacheTtl()

Determine an appropriate TTL between the return config and pdb config.

public getCacheTtl() : int
Tags
inheritdoc
Return values
int

hasFormatting()

Should this return config perform formatting?

public hasFormatting() : bool
Tags
inheritdoc
Return values
bool

parse()

Parse a return type config.

public static parse(string|array<string|int, mixed> $config) : PdbReturn

This converts string-style 'return types' as documented in Pdb::resultRs.

The object/array syntax permits class building, cache controls, nullables, and more.

Parameters
$config : string|array<string|int, mixed>
Tags
throws
InvalidArgumentException
Return values
PdbReturn

parseType()

A return type string may contain a few additional indicators.

public static parseType(string $type) : array<string|int, mixed>
  • '*:null' or '*?' will set 'throw' to false
  • 'map-arr:{column}' will set 'map_key'

The result 'type' will be cleaned of these 'arguments'.

Parameters
$type : string
Return values
array<string|int, mixed> —

[ type, throw, map_key ]

update()

public update(iterable<string|int, mixed> $config) : void
Parameters
$config : iterable<string|int, mixed>
On this page

Search results