\RedBeanPHP\RepositoryFluid

Fluid Repository.

OODB manages two repositories, a fluid one that adjust the database schema on-the-fly to accomodate for new bean types (tables) and new properties (columns) and a frozen one for use in a production environment. OODB allows you to swap the repository instances using the freeze() method.

Summary

Methods
Properties
Constants
usePartialBeans()
__construct()
check()
find()
findCollection()
store()
batch()
convertToBeans()
count()
trash()
tableExists()
wipe()
dispense()
load()
No public properties found
No constants found
storeBeanWithLists()
processGroups()
processSharedAdditions()
processResidue()
processTrashcan()
processSharedTrashcan()
processSharedResidue()
hasListsOrObjects()
processEmbeddedBean()
processAdditions()
storeBean()
handleException()
$stash
$nesting
$writer
$partialBeans
N/A
getTypeFromCast()
createTableIfNotExists()
modifySchema()
No private properties found
N/A

Properties

$stash

$stash : array

Type

array

$nesting

$nesting : 

Type

$partialBeans

$partialBeans : boolean

Type

boolean

Methods

usePartialBeans()

usePartialBeans(boolean|array  $yesNoBeans) : mixed

Toggles 'partial bean mode'. If this mode has been selected the repository will only update the fields of a bean that have been changed rather than the entire bean.

Pass the value TRUE to select 'partial mode' for all beans. Pass the value FALSE to disable 'partial mode'. Pass an array of bean types if you wish to use partial mode only for some types. This method will return the previous value.

Parameters

boolean|array $yesNoBeans

List of type names or 'all'

Returns

mixed

__construct()

__construct(\RedBeanPHP\OODB  $oodb, \RedBeanPHP\QueryWriter  $writer) : void

Constructor, requires a query writer and OODB.

Creates a new instance of the bean respository class.

Parameters

\RedBeanPHP\OODB $oodb

instance of object database

\RedBeanPHP\QueryWriter $writer

the Query Writer to use for this repository

check()

check(\RedBeanPHP\OODBBean  $bean) : void

Checks whether a OODBBean bean is valid.

If the type is not valid or the ID is not valid it will throw an exception: Security. To be valid a bean must abide to the following rules:

  • It must have an primary key id property named: id
  • It must have a type
  • The type must conform to the RedBeanPHP naming policy
  • All properties must be valid
  • All values must be valid

Parameters

\RedBeanPHP\OODBBean $bean

the bean that needs to be checked

find()

find(string  $type, array  $conditions = array(), string  $sql = NULL, array  $bindings = array()) : array

Searches the database for a bean that matches conditions $conditions and sql $addSQL and returns an array containing all the beans that have been found.

Conditions need to take form:

array( 'PROPERTY' => array( POSSIBLE VALUES... 'John', 'Steve' ) 'PROPERTY' => array( POSSIBLE VALUES... ) );

All conditions are glued together using the AND-operator, while all value lists are glued using IN-operators thus acting as OR-conditions.

Note that you can use property names; the columns will be extracted using the appropriate bean formatter.

Parameters

string $type

type of beans you are looking for

array $conditions

list of conditions

string $sql

SQL to be used in query

array $bindings

whether you prefer to use a WHERE clause or not (TRUE = not)

Returns

array

findCollection()

findCollection(string  $type, string  $sql, array  $bindings = array()) : \RedBeanPHP\BeanCollection

Finds a BeanCollection.

Given a type, an SQL snippet and optionally some parameter bindings this methods returns a BeanCollection for your query.

The BeanCollection represents a collection of beans and makes it possible to use database cursors. The BeanCollection has a method next() to obtain the first, next and last bean in the collection. The BeanCollection does not implement the array interface nor does it try to act like an array because it cannot go backward or rewind itself.

Parameters

string $type

type of beans you are looking for

string $sql

SQL to be used in query

array $bindings

whether you prefer to use a WHERE clause or not (TRUE = not)

Returns

\RedBeanPHP\BeanCollection

store()

store(\RedBeanPHP\OODBBean|\RedBeanPHP\SimpleModel  $bean) : integer|string

Stores a bean in the database. This method takes a OODBBean Bean Object $bean and stores it in the database. If the database schema is not compatible with this bean and RedBean runs in fluid mode the schema will be altered to store the bean correctly.

If the database schema is not compatible with this bean and RedBean runs in frozen mode it will throw an exception. This function returns the primary key ID of the inserted bean.

The return value is an integer if possible. If it is not possible to represent the value as an integer a string will be returned. We use explicit casts instead of functions to preserve performance (0.13 vs 0.28 for 10000 iterations on Core i3).

Parameters

\RedBeanPHP\OODBBean|\RedBeanPHP\SimpleModel $bean

bean to store

Returns

integer|string

batch()

batch(string  $type, array  $ids) : array

Returns an array of beans. Pass a type and a series of ids and this method will bring you the corresponding beans.

important note: Because this method loads beans using the load() function (but faster) it will return empty beans with ID 0 for every bean that could not be located. The resulting beans will have the passed IDs as their keys.

Parameters

string $type

type of beans

array $ids

ids to load

Returns

array

convertToBeans()

convertToBeans(string  $type, array  $rows, string  $mask = NULL) : array

This is a convenience method; it converts database rows (arrays) into beans. Given a type and a set of rows this method will return an array of beans of the specified type loaded with the data fields provided by the result set from the database.

New in 4.3.2: meta mask. The meta mask is a special mask to send data from raw result rows to the meta store of the bean. This is useful for bundling additional information with custom queries. Values of every column whos name starts with $mask will be transferred to the meta section of the bean under key 'data.bundle'.

Parameters

string $type

type of beans you would like to have

array $rows

rows from the database result

string $mask

meta mask to apply (optional)

Returns

array

count()

count(string  $type, string  $addSQL = '', array  $bindings = array()) : integer

Counts the number of beans of type $type.

This method accepts a second argument to modify the count-query. A third argument can be used to provide bindings for the SQL snippet.

Parameters

string $type

type of bean we are looking for

string $addSQL

additional SQL snippet

array $bindings

parameters to bind to SQL

Returns

integer

trash()

trash(\RedBeanPHP\OODBBean|\RedBeanPHP\SimpleModel  $bean) : void

Removes a bean from the database.

This function will remove the specified OODBBean Bean Object from the database.

Parameters

\RedBeanPHP\OODBBean|\RedBeanPHP\SimpleModel $bean

bean you want to remove from database

tableExists()

tableExists(string  $table) : boolean

Checks whether the specified table already exists in the database.

Not part of the Object Database interface!

Parameters

string $table

table name

Returns

boolean

wipe()

wipe(string  $type) : boolean

Trash all beans of a given type.

Wipes an entire type of bean. After this operation there will be no beans left of the specified type. This method will ignore exceptions caused by database tables that do not exist.

Parameters

string $type

type of bean you wish to delete all instances of

Returns

boolean

dispense()

dispense(string  $type, string  $number = 1, boolean  $alwaysReturnArray = FALSE) : \RedBeanPHP\OODBBean

Dispenses a new bean (a OODBBean Bean Object) of the specified type. Always use this function to get an empty bean object. Never instantiate a OODBBean yourself because it needs to be configured before you can use it with RedBean. This function applies the appropriate initialization / configuration for you.

Parameters

string $type

type of bean you want to dispense

string $number

number of beans you would like to get

boolean $alwaysReturnArray

if TRUE always returns the result as an array

Returns

\RedBeanPHP\OODBBean

load()

load(string  $type, integer  $id) : \RedBeanPHP\OODBBean

Loads a bean from the object database.

It searches for a OODBBean Bean Object in the database. It does not matter how this bean has been stored. RedBean uses the primary key ID $id and the string $type to find the bean. The $type specifies what kind of bean you are looking for; this is the same type as used with the dispense() function. If RedBean finds the bean it will return the OODB Bean object; if it cannot find the bean RedBean will return a new bean of type $type and with primary key ID 0. In the latter case it acts basically the same as dispense().

Important note: If the bean cannot be found in the database a new bean of the specified type will be generated and returned.

Parameters

string $type

type of bean you want to load

integer $id

ID of the bean you want to load

Returns

\RedBeanPHP\OODBBean

storeBeanWithLists()

storeBeanWithLists(\RedBeanPHP\OODBBean  $bean) : void

Fully processes a bean and updates the associated records in the database.

First the bean properties will be grouped as 'embedded' bean, addition, deleted 'trash can' or residue. Next, the different groups of beans will be processed accordingly and the reference bean (i.e. the one that was passed to the method as an argument) will be stored. Each type of list (own/shared) has 3 bean processors:

  • trashCanProcessor : removes the bean or breaks its association with the current bean
  • additionProcessor : associates the bean with the current one
  • residueProcessor : manages beans in lists that 'remain' but may need to be updated

This method first groups the beans and then calls the internal processing methods.

Parameters

\RedBeanPHP\OODBBean $bean

bean to process

processGroups()

processGroups(array  $originals, array  $current, array  $additions, array  $trashcan, array  $residue) : array

Process groups. Internal function. Processes different kind of groups for storage function. Given a list of original beans and a list of current beans, this function calculates which beans remain in the list (residue), which have been deleted (are in the trashcan) and which beans have been added (additions).

Parameters

array $originals

originals

array $current

the current beans

array $additions

beans that have been added

array $trashcan

beans that have been deleted

array $residue

beans that have been left untouched

Returns

array

processSharedAdditions()

processSharedAdditions(\RedBeanPHP\OODBBean  $bean, array  $sharedAdditions) : void

Processes a list of beans from a bean.

A bean may contain lists. This method handles shared addition lists; i.e. the $bean->sharedObject properties. Shared beans will be associated with eachother using the Association Manager.

Parameters

\RedBeanPHP\OODBBean $bean

the bean

array $sharedAdditions

list with shared additions

processResidue()

processResidue(array  $ownresidue) : void

Processes a list of beans from a bean.

A bean may contain lists. This method handles own lists; i.e. the $bean->ownObject properties. A residue is a bean in an own-list that stays where it is. This method checks if there have been any modification to this bean, in that case the bean is stored once again, otherwise the bean will be left untouched.

Parameters

array $ownresidue

list to process

processTrashcan()

processTrashcan(\RedBeanPHP\OODBBean  $bean, array  $ownTrashcan) : void

Processes a list of beans from a bean. A bean may contain lists. This method handles own lists; i.e. the $bean->ownObject properties.

A trash can bean is a bean in an own-list that has been removed (when checked with the shadow). This method checks if the bean is also in the dependency list. If it is the bean will be removed. If not, the connection between the bean and the owner bean will be broken by setting the ID to NULL.

Parameters

\RedBeanPHP\OODBBean $bean

bean to process

array $ownTrashcan

list to process

processSharedTrashcan()

processSharedTrashcan(\RedBeanPHP\OODBBean  $bean, array  $sharedTrashcan) : void

Unassociates the list items in the trashcan.

This bean processor processes the beans in the shared trash can. This group of beans has been deleted from a shared list. The affected beans will no longer be associated with the bean that contains the shared list.

Parameters

\RedBeanPHP\OODBBean $bean

bean to process

array $sharedTrashcan

list to process

processSharedResidue()

processSharedResidue(\RedBeanPHP\OODBBean  $bean, array  $sharedresidue) : void

Stores all the beans in the residue group.

This bean processor processes the beans in the shared residue group. This group of beans 'remains' in the list but might need to be updated or synced. The affected beans will be stored to perform the required database queries.

Parameters

\RedBeanPHP\OODBBean $bean

bean to process

array $sharedresidue

list to process

hasListsOrObjects()

hasListsOrObjects(\RedBeanPHP\OODBBean  $bean) : boolean

Determines whether the bean has 'loaded lists' or 'loaded embedded beans' that need to be processed by the store() method.

Parameters

\RedBeanPHP\OODBBean $bean

bean to be examined

Returns

boolean

processEmbeddedBean()

processEmbeddedBean(array  $embeddedBeans, \RedBeanPHP\OODBBean  $bean, string  $property, \RedBeanPHP\OODBBean  $value) : void

Converts an embedded bean to an ID, removes the bean property and stores the bean in the embedded beans array. The id will be assigned to the link field property, i.e. 'bean_id'.

Parameters

array $embeddedBeans

destination array for embedded bean

\RedBeanPHP\OODBBean $bean

target bean to process

string $property

property that contains the embedded bean

\RedBeanPHP\OODBBean $value

embedded bean itself

processAdditions()

processAdditions(\RedBeanPHP\OODBBean  $bean, array  $ownAdditions) : void

Part of the store() functionality.

Handles all new additions after the bean has been saved. Stores addition bean in own-list, extracts the id and adds a foreign key. Also adds a constraint in case the type is in the dependent list.

Note that this method raises a custom exception if the bean is not an instance of OODBBean. Therefore it does not use a type hint. This allows the user to take action in case invalid objects are passed in the list.

Parameters

\RedBeanPHP\OODBBean $bean

bean to process

array $ownAdditions

list of addition beans in own-list

storeBean()

storeBean(\RedBeanPHP\OODBBean  $bean) : void

Stores a cleaned bean; i.e. only scalar values. This is the core of the store() method. When all lists and embedded beans (parent objects) have been processed and removed from the original bean the bean is passed to this method to be stored in the database.

Parameters

\RedBeanPHP\OODBBean $bean

the clean bean

handleException()

handleException(\Exception  $exception) : void

Exception handler.

Fluid and Frozen mode have different ways of handling exceptions. Fluid mode (using the fluid repository) ignores exceptions caused by the following:

  • missing tables
  • missing column

In these situations, the repository will behave as if no beans could be found. This is because in fluid mode it might happen to query a table or column that has not been created yet. In frozen mode, this is not supposed to happen and the corresponding exceptions will be thrown.

Parameters

\Exception $exception

exception

getTypeFromCast()

getTypeFromCast(string  $cast) : integer

Figures out the desired type given the cast string ID.

Given a cast ID, this method will return the associated type (INT(10) or VARCHAR for instance). The returned type can be processed by the Query Writer to build the specified column for you in the database. The Cast ID is actually just a superset of the QueryWriter types. In addition to default Query Writer column types you can pass the following 'cast types': 'id' and 'string'. These will map to Query Writer specific column types (probably INT and VARCHAR).

Parameters

string $cast

cast identifier

Returns

integer

createTableIfNotExists()

createTableIfNotExists(\RedBeanPHP\OODBBean  $bean, string  $table) : void

Orders the Query Writer to create a table if it does not exist already and adds a note in the build report about the creation.

Parameters

\RedBeanPHP\OODBBean $bean

bean to update report of

string $table

table to check and create if not exists

modifySchema()

modifySchema(\RedBeanPHP\OODBBean  $bean, string  $property, mixed  $value,   $columns = NULL) : void

Modifies the table to fit the bean data.

Given a property and a value and the bean, this method will adjust the table structure to fit the requirements of the property and value. This may include adding a new column or widening an existing column to hold a larger or different kind of value. This method employs the writer to adjust the table structure in the database. Schema updates are recorded in meta properties of the bean.

This method will also apply indexes, unique constraints and foreign keys.

Parameters

\RedBeanPHP\OODBBean $bean

bean to get cast data from and store meta in

string $property

property to store

mixed $value

value to store

$columns