\RedBeanPHPQueryWriter

QueryWriter Interface for QueryWriters.

Describes the API for a QueryWriter.

Terminology:

  • beautified property (a camelCased property, has to be converted first)
  • beautified type (a camelCased type, has to be converted first)
  • type (a bean type, corresponds directly to a table)
  • property (a bean property, corresponds directly to a column)
  • table (a checked and quoted type, ready for use in a query)
  • column (a checked and quoted property, ready for use in query)
  • tableNoQ (same as type, but in context of a database operation)
  • columnNoQ (same as property, but in context of a database operation)

Summary

Methods
Constants
writeJoin()
glueSQLCondition()
glueLimitOne()
getTables()
createTable()
getColumns()
scanType()
addColumn()
code()
widenColumn()
queryRecord()
queryRecordWithCursor()
queryRecordRelated()
queryRecordLink()
queryRecordCount()
queryRecordCountRelated()
queryTagged()
queryCountTagged()
queryRecursiveCommonTableExpression()
updateRecord()
deleteRecord()
deleteRelations()
addUniqueIndex()
addUniqueConstraint()
sqlStateIn()
wipe()
addFK()
addIndex()
esc()
wipeAll()
renameAssocTable()
getAssocTable()
inferFetchType()
C_SQLFILTER_READ
C_SQLFILTER_WRITE
C_SQLSTATE_NO_SUCH_TABLE
C_SQLSTATE_NO_SUCH_COLUMN
C_SQLSTATE_INTEGRITY_CONSTRAINT_VIOLATION
C_SQLSTATE_LOCK_TIMEOUT
C_DATATYPE_RANGE_SPECIAL
C_DATATYPE_RANGE_SPECIFIED
C_GLUE_WHERE
C_GLUE_AND
No protected methods found
N/A
No private methods found
N/A

Constants

C_SQLFILTER_READ

C_SQLFILTER_READ

SQL filter constants

C_SQLFILTER_WRITE

C_SQLFILTER_WRITE

C_SQLSTATE_NO_SUCH_TABLE

C_SQLSTATE_NO_SUCH_TABLE

Query Writer constants.

C_SQLSTATE_NO_SUCH_COLUMN

C_SQLSTATE_NO_SUCH_COLUMN

C_SQLSTATE_INTEGRITY_CONSTRAINT_VIOLATION

C_SQLSTATE_INTEGRITY_CONSTRAINT_VIOLATION

C_SQLSTATE_LOCK_TIMEOUT

C_SQLSTATE_LOCK_TIMEOUT

C_DATATYPE_RANGE_SPECIAL

C_DATATYPE_RANGE_SPECIAL

Define data type regions

00 - 80: normal data types 80 - 99: special data types, only scan/code if requested 99 : specified by user, don't change

C_DATATYPE_RANGE_SPECIFIED

C_DATATYPE_RANGE_SPECIFIED

C_GLUE_WHERE

C_GLUE_WHERE

Define GLUE types for use with glueSQLCondition methods.

Determines how to prefix a snippet of SQL before appending it to other SQL (or integrating it, mixing it otherwise).

WHERE - glue as WHERE condition AND - glue as AND condition

C_GLUE_AND

C_GLUE_AND

Methods

writeJoin()

writeJoin(string  $type, string  $targetType, string  $joinType) : string

Writes an SQL Snippet for a JOIN, returns the SQL snippet string.

Parameters

string $type

source type

string $targetType

target type (type to join)

string $joinType

type of join (possible: 'LEFT', 'RIGHT' or 'INNER').

Returns

string —

$joinSQLSnippet

glueSQLCondition()

glueSQLCondition(string  $sql, integer  $glue = NULL) : string

Glues an SQL snippet to the beginning of a WHERE clause.

This ensures users don't have to add WHERE to their query snippets.

The snippet gets prefixed with WHERE or AND if it starts with a condition.

If the snippet does NOT start with a condition (or this function thinks so) the snippet is returned as-is.

The GLUE type determines the prefix:

  • NONE prefixes with WHERE
  • WHERE prefixes with WHERE and replaces AND if snippets starts with AND
  • AND prefixes with AND

This method will never replace WHERE with AND since a snippet should never begin with WHERE in the first place. OR is not supported.

Only a limited set of clauses will be recognized as non-conditions. For instance beginning a snippet with complex statements like JOIN or UNION will not work. This is too complex for use in a snippet.

Parameters

string $sql

SQL Snippet

integer $glue

the GLUE type - how to glue (C_GLUE_WHERE or C_GLUE_AND)

Returns

string

glueLimitOne()

glueLimitOne(string  $sql) : string

Determines if there is a LIMIT 1 clause in the SQL.

If not, it will add a LIMIT 1. (used for findOne).

Parameters

string $sql

query to scan and adjust

Returns

string

getTables()

getTables() : array

Returns the tables that are in the database.

Returns

array

createTable()

createTable(string  $type) : void

This method will create a table for the bean.

This methods accepts a type and infers the corresponding table name.

Parameters

string $type

type of bean you want to create a table for

getColumns()

getColumns(string  $type) : array

Returns an array containing all the columns of the specified type.

The format of the return array looks like this: $field => $type where $field is the name of the column and $type is a database specific description of the datatype.

This methods accepts a type and infers the corresponding table name.

Parameters

string $type

type of bean you want to obtain a column list of

Returns

array

scanType()

scanType(string  $value, boolean  $alsoScanSpecialForTypes = FALSE) : integer

Returns the Column Type Code (integer) that corresponds to the given value type. This method is used to determine the minimum column type required to represent the given value. There are two modes of operation: with or without special types. Scanning without special types requires the second parameter to be set to FALSE. This is useful when the column has already been created and prevents it from being modified to an incompatible type leading to data loss. Special types will be taken into account when a column does not exist yet (parameter is then set to TRUE).

Special column types are determines by the AQueryWriter constant C_DATA_TYPE_ONLY_IF_NOT_EXISTS (usually 80). Another 'very special' type is type C_DATA_TYPE_MANUAL (usually 99) which represents a user specified type. Although no special treatment has been associated with the latter for now.

Parameters

string $value

value

boolean $alsoScanSpecialForTypes

take special types into account

Returns

integer

addColumn()

addColumn(string  $type, string  $column, integer  $field) : void

This method will add a column to a table.

This methods accepts a type and infers the corresponding table name.

Parameters

string $type

name of the table

string $column

name of the column

integer $field

data type for field

code()

code(string  $typedescription, boolean  $includeSpecials = FALSE) : integer

Returns the Type Code for a Column Description.

Given an SQL column description this method will return the corresponding code for the writer. If the include specials flag is set it will also return codes for special columns. Otherwise special columns will be identified as specified columns.

Parameters

string $typedescription

description

boolean $includeSpecials

whether you want to get codes for special columns as well

Returns

integer

widenColumn()

widenColumn(string  $type, string  $column, integer  $datatype) : void

This method will widen the column to the specified data type.

This methods accepts a type and infers the corresponding table name.

Parameters

string $type

type / table that needs to be adjusted

string $column

column that needs to be altered

integer $datatype

target data type

queryRecord()

queryRecord(string  $type, array  $conditions = array(), string  $addSql = NULL, array  $bindings = array()) : array

Selects records from the database.

This methods selects the records from the database that match the specified type, conditions (optional) and additional SQL snippet (optional).

Parameters

string $type

name of the table you want to query

array $conditions

criteria ( $column => array( $values ) )

string $addSql

additional SQL snippet

array $bindings

bindings for SQL snippet

Returns

array

queryRecordWithCursor()

queryRecordWithCursor(string  $type,   $addSql = NULL, array  $bindings = array()) : \RedBeanPHP\Cursor

Selects records from the database and returns a cursor.

This methods selects the records from the database that match the specified type, conditions (optional) and additional SQL snippet (optional).

Parameters

string $type

name of the table you want to query

$addSql
array $bindings

bindings for SQL snippet

Returns

\RedBeanPHP\Cursor

queryRecordRelated()

queryRecordRelated(string  $sourceType, string  $destType, mixed  $linkID, string  $addSql = '', array  $bindings = array()) : array

Returns records through an intermediate type. This method is used to obtain records using a link table and allows the SQL snippets to reference columns in the link table for additional filtering or ordering.

Parameters

string $sourceType

source type, the reference type you want to use to fetch related items on the other side

string $destType

destination type, the target type you want to get beans of

mixed $linkID

ID to use for the link table

string $addSql

Additional SQL snippet

array $bindings

Bindings for SQL snippet

Returns

array

queryRecordLink()

queryRecordLink(string  $sourceType, string  $destType, string  $sourceID, string  $destID) : array|null

Returns the row that links $sourceType $sourcID to $destType $destID in an N-M relation.

Parameters

string $sourceType

source type, the first part of the link you're looking for

string $destType

destination type, the second part of the link you're looking for

string $sourceID

ID for the source

string $destID

ID for the destination

Returns

array|null

queryRecordCount()

queryRecordCount(string  $type, array  $conditions = array(),   $addSql = NULL, array  $bindings = array()) : integer

Counts the number of records in the database that match the conditions and additional SQL.

Parameters

string $type

name of the table you want to query

array $conditions

criteria ( $column => array( $values ) )

$addSql
array $bindings

bindings for SQL snippet

Returns

integer

queryRecordCountRelated()

queryRecordCountRelated(string  $sourceType, string  $targetType, mixed  $linkID, string  $addSQL = '', array  $bindings = array()) : integer

Returns the number of records linked through $linkType and satisfying the SQL in $addSQL/$bindings.

Parameters

string $sourceType

source type

string $targetType

the thing you want to count

mixed $linkID

the of the source type

string $addSQL

additional SQL snippet

array $bindings

bindings for SQL snippet

Returns

integer

queryTagged()

queryTagged(string  $type, array  $tagList, boolean  $all = FALSE, string  $addSql = '', array  $bindings = array()) : array

Returns all rows of specified type that have been tagged with one of the strings in the specified tag list array.

Note that the additional SQL snippet can only be used for pagination, the SQL snippet will be appended to the end of the query.

Parameters

string $type

the bean type you want to query

array $tagList

an array of strings, each string containing a tag title

boolean $all

if TRUE only return records that have been associated with ALL the tags in the list

string $addSql

addition SQL snippet, for pagination

array $bindings

parameter bindings for additional SQL snippet

Returns

array

queryCountTagged()

queryCountTagged(string  $type, array  $tagList, boolean  $all = FALSE, string  $addSql = '', array  $bindings = array()) : integer

Like queryTagged but only counts.

Parameters

string $type

the bean type you want to query

array $tagList

an array of strings, each string containing a tag title

boolean $all

if TRUE only return records that have been associated with ALL the tags in the list

string $addSql

addition SQL snippet, for pagination

array $bindings

parameter bindings for additional SQL snippet

Returns

integer

queryRecursiveCommonTableExpression()

queryRecursiveCommonTableExpression(string  $type, integer  $id, boolean  $up = TRUE, string  $addSql = NULL, array  $bindings = array()) : array

Returns all parent rows or child rows of a specified row.

Given a type specifier and a primary key id, this method returns either all child rows as defined by having _id = id or all parent rows as defined per id = _id taking into account an optional SQL snippet along with parameters.

Parameters

string $type

the bean type you want to query rows for

integer $id

id of the reference row

boolean $up

TRUE to query parent rows, FALSE to query child rows

string $addSql

optional SQL snippet to embed in the query

array $bindings

parameter bindings for additional SQL snippet

Returns

array

updateRecord()

updateRecord(string  $type, array  $updatevalues, integer  $id = NULL) : integer

This method should update (or insert a record), it takes a table name, a list of update values ( $field => $value ) and an primary key ID (optional). If no primary key ID is provided, an INSERT will take place.

Returns the new ID. This methods accepts a type and infers the corresponding table name.

Parameters

string $type

name of the table to update

array $updatevalues

list of update values

integer $id

optional primary key ID value

Returns

integer

deleteRecord()

deleteRecord(string  $type, array  $conditions = array(), string  $addSql = '', array  $bindings = array()) : void

Deletes records from the database.

Parameters

string $type

name of the table you want to query

array $conditions

criteria ( $column => array( $values ) )

string $addSql

additional SQL

array $bindings

bindings

deleteRelations()

deleteRelations(string  $sourceType, string  $destType, string  $sourceID) : void

Deletes all links between $sourceType and $destType in an N-M relation.

Parameters

string $sourceType

source type

string $destType

destination type

string $sourceID

source ID

addUniqueIndex()

addUniqueIndex(  $type,   $columns) 

Parameters

$type
$columns

addUniqueConstraint()

addUniqueConstraint(string  $type,   $columns) : void

This method will add a UNIQUE constraint index to a table on columns $columns.

This methods accepts a type and infers the corresponding table name.

Parameters

string $type

target bean type

$columns

sqlStateIn()

sqlStateIn(string  $state, array  $list, array  $extraDriverDetails = array()) : boolean

This method will check whether the SQL state is in the list of specified states and returns TRUE if it does appear in this list or FALSE if it does not. The purpose of this method is to translate the database specific state to a one of the constants defined in this class and then check whether it is in the list of standard states provided.

Parameters

string $state

SQL state to consider

array $list

list of standardized SQL state constants to check against

array $extraDriverDetails

Some databases communicate state information in a driver-specific format rather than through the main sqlState code. For those databases, this extra information can be used to determine the standardized state

Returns

boolean

wipe()

wipe(string  $type) : void

This method will remove all beans of a certain type.

This methods accepts a type and infers the corresponding table name.

Parameters

string $type

bean type

addFK()

addFK(string  $type, string  $targetType, string  $property, string  $targetProperty, string  $isDep = FALSE) : void

This method will add a foreign key from type and field to target type and target field.

The foreign key is created without an action. On delete/update no action will be triggered. The FK is only used to allow database tools to generate pretty diagrams and to make it easy to add actions later on. This methods accepts a type and infers the corresponding table name.

Parameters

string $type

type that will have a foreign key field

string $targetType

points to this type

string $property

field that contains the foreign key value

string $targetProperty

field where the fk points to

string $isDep

whether target is dependent and should cascade on update/delete

addIndex()

addIndex(string  $type, string  $name, string  $property) : void

This method will add an index to a type and field with name $name.

This methods accepts a type and infers the corresponding table name.

Parameters

string $type

type to add index to

string $name

name of the new index

string $property

field to index

esc()

esc(string  $databaseStructure,   $dontQuote = FALSE) : string

Checks and filters a database structure element like a table of column for safe use in a query. A database structure has to conform to the RedBeanPHP DB security policy which basically means only alphanumeric symbols are allowed. This security policy is more strict than conventional SQL policies and does therefore not require database specific escaping rules.

Parameters

string $databaseStructure

name of the column/table to check

$dontQuote

Returns

string

wipeAll()

wipeAll() : void

Removes all tables and views from the database.

renameAssocTable()

renameAssocTable(string|array  $fromType, string  $toType = NULL) : void

Renames an association. For instance if you would like to refer to album_song as: track you can specify this by calling this method like:

renameAssociation('album_song','track')

This allows:

$album->sharedSong

to add/retrieve beans from track instead of album_song. Also works for exportAll().

This method also accepts a single associative array as its first argument.

Parameters

string|array $fromType

original type name, or array

string $toType

new type name (only if 1st argument is string)

getAssocTable()

getAssocTable(array  $types) : string

Returns the format for link tables.

Given an array containing two type names this method returns the name of the link table to be used to store and retrieve association records. For instance, given two types: person and project, the corresponding link table might be: 'person_project'.

Parameters

array $types

two types array($type1, $type2)

Returns

string

inferFetchType()

inferFetchType(  $type,   $property) : string|NULL

Given a bean type and a property, this method tries to infer the fetch type using the foreign key definitions in the database.

For instance: project, student -> person. If no fetchType can be inferred, this method will return NULL.

Parameters

$type

the source type to fetch a target type for

$property

the property to fetch the type of

Returns

string|NULL