UserFrosting API

Sprunje

Sprunje.

Implements a versatile API for sorting, filtering, and paginating an Eloquent query builder.

Tags
author

Alex Weissman (https://alexanderweissman.com)

Table of Contents

$classMapper ClassMapper
$name Name of this Sprunje, used when generating output files. string
$query The base (unfiltered) query. Builder|Builder|Relation
$options Default HTTP request parameters.
$filterable Fields to allow filtering upon.
$listable Fields to allow listing (enumeration) upon.
$sortable Fields to allow sorting upon.
$excludeForAll List of fields to exclude when processing an "_all" filter.
$orSeparator Separator to use when splitting filter values to treat them as ORs. string
$countKey Array key for the total unfiltered object count. string
$countFilteredKey Array key for the filtered object count. string
$rowsKey Array key for the actual result set. string
$listableKey Array key for the list of enumerated columns and their enumerations. string
__construct() Constructor. mixed
extendQuery() Extend the query by providing a callback. self
toResponse() Execute the query and build the results, and append them in the appropriate format to the response. ResponseInterface
getArray() Executes the sprunje query, applying all sorts, filters, and pagination. array
getCsv() Run the query and build a CSV object by flattening the resulting collection. Ignores any pagination. SplTempFileObject
getModels() Executes the sprunje query, applying all sorts, filters, and pagination. array
getListable() Get lists of values for specified fields in 'lists' option, calling a custom lister callback when appropriate. array
getQuery() Get the underlying queriable object in its current state. Builder
setQuery() Set the underlying QueryBuilder object. self
applyFilters() Apply any filters from the options, calling a custom filter callback when appropriate. self
applySorts() Apply any sorts from the options, calling a custom sorter callback when appropriate. self
applyPagination() Apply pagination based on the `page` and `size` options. self
filterAll() Match any filter in `filterable`. self
buildFilterQuery() Build the filter query for a single field. self
buildFilterDefaultFieldQuery() Perform a 'like' query on a single field, separating the value string on the or separator and matching any of the supplied values. self
applyTransformations() Set any transformations you wish to apply to the collection, after the query is executed. Collection
baseQuery() Set the initial query used by your Sprunje. Builder|Relation|Model
getColumnValues() Returns a list of distinct values for a specified column. array
count() Get the unpaginated count of items (before filtering) in this query. int
countFiltered() Get the unpaginated count of items (after filtering) in this query. int
getResults() Executes the sprunje query, applying all sorts, filters, and pagination. array

Properties

$name

Name of this Sprunje, used when generating output files.

protected string $name = ''

$query

The base (unfiltered) query.

protected Builder|Builder|Relation $query

$options

Default HTTP request parameters.

protected mixed $options = ['sorts' => [], 'filters' => [], 'lists' => [], 'size' => 'all', 'page' => null, 'format' => 'json']

$filterable

Fields to allow filtering upon.

protected mixed $filterable = []

$listable

Fields to allow listing (enumeration) upon.

protected mixed $listable = []

$sortable

Fields to allow sorting upon.

protected mixed $sortable = []

$excludeForAll

List of fields to exclude when processing an "_all" filter.

protected mixed $excludeForAll = []

$orSeparator

Separator to use when splitting filter values to treat them as ORs.

protected string $orSeparator = '||'

$countKey

Array key for the total unfiltered object count.

protected string $countKey = 'count'

$countFilteredKey

Array key for the filtered object count.

protected string $countFilteredKey = 'count_filtered'

$rowsKey

Array key for the actual result set.

protected string $rowsKey = 'rows'

$listableKey

Array key for the list of enumerated columns and their enumerations.

protected string $listableKey = 'listable'

Methods

__construct()

Constructor.

public __construct( $classMapper : ClassMapper , $options : array ) : mixed
Parameters
$classMapper : ClassMapper
$options : array
Return values
mixed

extendQuery()

Extend the query by providing a callback.

public extendQuery( $callback : callable ) : self
Parameters
$callback : callable

A callback which accepts and returns a Builder instance.

Return values
self

toResponse()

Execute the query and build the results, and append them in the appropriate format to the response.

public toResponse( $response : ResponseInterface ) : ResponseInterface
Parameters
$response : ResponseInterface
Return values
ResponseInterface

getArray()

Executes the sprunje query, applying all sorts, filters, and pagination.

public getArray( ) : array

Returns an array containing count (the total number of rows, before filtering), count_filtered (the total number of rows after filtering), and rows (the filtered result set).

Return values
array

getCsv()

Run the query and build a CSV object by flattening the resulting collection. Ignores any pagination.

public getCsv( ) : SplTempFileObject
Return values
SplTempFileObject

getModels()

Executes the sprunje query, applying all sorts, filters, and pagination.

public getModels( ) : array

Returns the filtered, paginated result set and the counts.

Return values
array

getListable()

Get lists of values for specified fields in 'lists' option, calling a custom lister callback when appropriate.

public getListable( ) : array
Return values
array

getQuery()

Get the underlying queriable object in its current state.

public getQuery( ) : Builder
Return values
Builder

setQuery()

Set the underlying QueryBuilder object.

public setQuery( $query : Builder ) : self
Parameters
$query : Builder
Return values
self

applyFilters()

Apply any filters from the options, calling a custom filter callback when appropriate.

public applyFilters( $query : Builder ) : self
Parameters
$query : Builder
Return values
self

applySorts()

Apply any sorts from the options, calling a custom sorter callback when appropriate.

public applySorts( $query : Builder ) : self
Parameters
$query : Builder
Return values
self

applyPagination()

Apply pagination based on the `page` and `size` options.

public applyPagination( $query : Builder ) : self
Parameters
$query : Builder
Return values
self

filterAll()

Match any filter in `filterable`.

protected filterAll( $query : Builder , $value : mixed ) : self
Parameters
$query : Builder
$value : mixed
Return values
self

buildFilterQuery()

Build the filter query for a single field.

protected buildFilterQuery( $query : Builder , $name : string , $value : mixed ) : self
Parameters
$query : Builder
$name : string
$value : mixed
Return values
self

buildFilterDefaultFieldQuery()

Perform a 'like' query on a single field, separating the value string on the or separator and matching any of the supplied values.

protected buildFilterDefaultFieldQuery( $query : Builder , $name : string , $value : mixed ) : self
Parameters
$query : Builder
$name : string
$value : mixed
Return values
self

applyTransformations()

Set any transformations you wish to apply to the collection, after the query is executed.

protected applyTransformations( $collection : Collection ) : Collection
Parameters
$collection : Collection
Return values
Collection

baseQuery()

Set the initial query used by your Sprunje.

protected abstract baseQuery( ) : Builder|Relation|Model
Return values
Builder|Relation|Model

getColumnValues()

Returns a list of distinct values for a specified column.

protected getColumnValues( $column : string ) : array

Formats results to have a "value" and "text" attribute.

Parameters
$column : string
Return values
array

count()

Get the unpaginated count of items (before filtering) in this query.

protected count( $query : Builder ) : int
Parameters
$query : Builder
Return values
int

countFiltered()

Get the unpaginated count of items (after filtering) in this query.

protected countFiltered( $query : Builder ) : int
Parameters
$query : Builder
Return values
int

getResults()

Executes the sprunje query, applying all sorts, filters, and pagination.

public getResults( ) : array

Returns an array containing count (the total number of rows, before filtering), count_filtered (the total number of rows after filtering), and rows (the filtered result set).

Tags
deprecated

since 4.1.7 Use getArray() instead.

Return values
array

Search results