Documentation

ServiceableModel extends DefaultModel implements IServiceableModel

The default property bag model for storing stuff.

I highly recommend creating children of this class that contain getter/setter methods for any properties expected to be in the model. It makes development a lot easier in the long run.

It's worth noting that you DO NOT have to descend from this class. You can simply pass a property set to the default model, and go to town.

Table of Contents

$providers Model-backed Service providers. \buffalokiwi\magicgraph\IModelPropertyProvider[]
$properties Properties IPropertySet
$cloneNames A copy of the internal list of names for use elsewhere. IBigSet
$edited Edited properties IPropertySet
$prefixMap A map of prefix => property name. array
$validationEnabled If validation is enabled bool
__construct() Create a model wrapper that can interact with service providers. mixed
getPropertyProviders() Retrieve a list of property service providers \buffalokiwi\magicgraph\IPropertyServiceProvider[]
getValue() Retrieve the value of some property mixed
setValue() Sets the value of some property void
validate() Test to see if this model is valid prior to save() void
toObject() Convert the model to a json representation. string
toArray() Convert this model to an array. array
providerWarmup() mixed
__construct() Create a new DefaultModel instance. mixed
toggleValidation() Toggle validation. If disabled, then the call to validate() simply returns. void
isValidationEnabled() bool
__clone() mixed
getIterator() Retrieve an external iterator <p>Returns an external iterator.</p> Traversable
createCopy() Create a copy/clone of the model and all properties. IModel
getPropertyConfig() Retrieve a property config instance attached to this model. IPropertyConfig
__isset() Determine if $name matches a property name defined in the IPropertySet instance supplied to the constructor. bool
__get() Generic getter. mixed
__set() Sets some property value. mixed
instanceOf() A way to determine if this model OR if a property set is an instance of some interface. bool
getValue() Retrieve the value of some property. mixed
setValue() Sets the value of some property. void
getModifiedProperties() Retrieve a list of modified properties IPropertySet
hasEdits() Detect if any properties have been edited in this model bool
testEdited() bool
clearEditFlags() Clears the internal edited flags for each property void
getPropertySet() Retrieve the property set used for this model. IPropertySet
getPropertyNameSet() Retrieve property names as an IBigSet instance. IBigSet
getPropertyNameSetByFlags() Retrieve a set with the property name bits toggled on for properties with the supplied flags. IBigSet
arrayToObject() mixed
fromArray() Sets properties from some array. void
toObject() Convert the model to a json representation. string
toArray() Convert this model to an array. array
equals() Test if this model is equal to some other model bool
validate() Test to see if this model is valid prior to save() void
validateProperties() array
validateAll() If you want to validate each property and return a list of errors indexed by property name, this is the method to call. array
hash() Retrieve a unique hash for this object string
getInsertProperties() Gets A propertyset containing properties for insert IBigSet
jsonSerialize() Specify data which should be serialized to JSON <p>Serializes the object to a value that can be serialized natively by <code>json_encode()</code>.</p> mixed
beforeValidate() Called prior to the validation loop mixed
isMember() Checks to see if some property is a member of the property set bool
getProperty() Retrieve a prop. IProperty
getPropertyByPrefix() If a prefix is used on some object type, this will return the string
getPrimaryKeyMap() array
hasPrimaryKeyValues() Test that the model has all primary key values bool
testPrefixModelWriteNewFlag() Called from setValue(), and used when the property has a prefix value set. mixed

Properties

$providers

Model-backed Service providers.

private \buffalokiwi\magicgraph\IModelPropertyProvider[] $providers = []

$cloneNames

A copy of the internal list of names for use elsewhere.

private IBigSet $cloneNames = null

$prefixMap

A map of prefix => property name.

private array $prefixMap
When setValue is called, this map is checked. If the current property name matches an entry in this map, the value is used as the new property name.

$validationEnabled

If validation is enabled

private bool $validationEnabled = true

Methods

__construct()

Create a model wrapper that can interact with service providers.

public __construct( $properties : IPropertySet , ...$providers : IModelPropertyProvider ) : mixed

The supplied property set is used to determine what properties are available and the behavior of those properties attached to the model instance.

The supplied property set is cloned twice into two internal properties: "properties" and "edited". "properties" contains the master property set. This is freely editable and can be used as input for various methods.

The "edited" property is the list of properties attached to the model that have been edited. Each time setValue() is called, the corresponding bit in the "edited" property is enabled. When getModifiedProperties() is called, the enabled bits in edited are used to determine which properties to return.

For each property, a default value is set. If the property has an init callback, the property's default value property is supplied as an argument to the init callback, and the return value is used as the default property value within the model. If the init callback is not defined, then the property's default value is used as the default property value within the model.

Parameters
$properties : IPropertySet

Properties

$providers : IModelPropertyProvider

A list of service providers for this model

Return values
mixed

getPropertyProviders()

Retrieve a list of property service providers

public getPropertyProviders( ) : \buffalokiwi\magicgraph\IPropertyServiceProvider[]
Return values
\buffalokiwi\magicgraph\IPropertyServiceProvider[]

getValue()

Retrieve the value of some property

public getValue( $property : string [, $context : array = [] ] ) : mixed

When retrieving a value:

First the supplied property name it checked to ensure it exists in the internal IPropertySet instance If not, then an \InvalidArgumentException is thrown.

If the property has a getter callback, it is called with (this,IProperty,value) and the result of that callback is returned. Otherwise, the stored value is returned.

WARNING: This returns a reference. Be careful about setting variables equal to this...

Parameters
$property : string

Property

$context : array = []
Tags
throws
InvalidArgumentException

if the property is invalid

Return values
mixed —

value

setValue()

Sets the value of some property

public setValue( $property : string , $value : mixed ) : void

If the IProperty::getPrepare() callback is used, $aValue is supplied as an argument, and the result of that callback is used as the value moving forward.

The value is validated against IProperty::validate()

The value is committed to the model using commitValue()

The edited property set has the corresponding bit enabled

Parameters
$property : string

Property to set

$value : mixed

property value

Tags
throws
InvalidArgumentException

if the property is invalid

toObject()

Convert the model to a json representation.

public toObject( [ $properties : IBigSet|null = null ] [, $includeArrays : bool = false ] [, $includeModels : bool = false ] ) : string

This probably does not work with object properties. Need to test.

Parameters
$properties : IBigSet|null = null
$includeArrays : bool = false
$includeModels : bool = false
Return values
string —

JSON object

toArray()

Convert this model to an array.

public toArray( [ $properties : IPropertySet = null ] [, $includeArrays : bool = false ] [, $includeModels : bool = false ] ) : array
Parameters
$properties : IPropertySet = null

Properties to include

$includeArrays : bool = false
$includeModels : bool = false
Return values
array

__construct()

Create a new DefaultModel instance.

public __construct( $properties : IPropertySet ) : mixed

The supplied property set is used to determine what properties are available and the behavior of those properties attached to the model instance.

The supplied property set is cloned twice into two internal properties: "properties" and "edited". "properties" contains the master property set. This is freely editable and can be used as input for various methods.

The "edited" property is the list of properties attached to the model that have been edited. Each time setValue() is called, the corresponding bit in the "edited" property is enabled. When getModifiedProperties() is called, the enabled bits in edited are used to determine which properties to return.

For each property, a default value is set. If the property has an init callback, the property's default value property is supplied as an argument to the init callback, and the return value is used as the default property value within the model. If the init callback is not defined, then the property's default value is used as the default property value within the model.

Parameters
$properties : IPropertySet

Properties

Return values
mixed

toggleValidation()

Toggle validation. If disabled, then the call to validate() simply returns.

protected final toggleValidation( $on : bool ) : void
Parameters
$on : bool
Tags
final

isValidationEnabled()

protected final isValidationEnabled( ) : bool
Return values
bool

createCopy()

Create a copy/clone of the model and all properties.

public createCopy( [ $copyIsSaveable : bool = true ] [, $removePriKeys : bool = true ] ) : IModel
Parameters
$copyIsSaveable : bool = true

If this is false, then the primary key flags are removed from the copied model. This will cause the repository save method

$removePriKeys : bool = true
Return values
IModel —

Copied model

getPropertyConfig()

Retrieve a property config instance attached to this model.

public getPropertyConfig( $intf : string ) : IPropertyConfig
Parameters
$intf : string

Interface of the config instance

Tags
throws
Exception

if The requested interface was not used to build this model.

Return values
IPropertyConfig —

The config instance

__isset()

Determine if $name matches a property name defined in the IPropertySet instance supplied to the constructor.

public __isset( $name : string ) : bool

Calls IPropertySet::isMember()

Parameters
$name : string

property name

Tags
see
ISet::isMember()
Return values
bool —

is set

__set()

Sets some property value.

public __set( $p : string , $v : mixed ) : mixed

Alias of setValue()

Parameters
$p : string

Property name

$v : mixed

Property value

Tags
see
DefaultModel::setValue()
Return values
mixed

instanceOf()

A way to determine if this model OR if a property set is an instance of some interface.

public instanceOf( $interface : string ) : bool

This is used due to decorators.

Parameters
$interface : string

Interface name

Return values
bool —

if this implements it

getValue()

Retrieve the value of some property.

public getValue( $property : string [, $context : array = [] ] ) : mixed

When retrieving a value:

First the supplied property name it checked to ensure it exists in the internal IPropertySet instance If not, then an \InvalidArgumentException is thrown.

If the property has a getter callback, it is called with (this,IProperty,value) and the result of that callback is returned. Otherwise, the stored value is returned.

WARNING: This returns a reference. Be careful about setting variables equal to this...

Parameters
$property : string

Property

$context : array = []
Tags
throws
InvalidArgumentException

if the property is not a member of the supplied IPropertySet instance

Return values
mixed —

value

setValue()

Sets the value of some property.

public setValue( $property : string , $value : mixed ) : void

If the IProperty::getPrepare() callback is used, $aValue is supplied as an argument, and the result of that callback is used as the value moving forward.

The value is validated against IProperty::validate()

The value is committed to the model using commitValue()

The edited property set has the corresponding bit enabled

Parameters
$property : string

Property to set

$value : mixed

property value

Tags
throws
InvalidArgumentException

if the property is not a member of this model

throws
ValidationException

if value is invalid

hasEdits()

Detect if any properties have been edited in this model

public hasEdits( [ $prop : string = '' ] ) : bool
Parameters
$prop : string = ''

Property name. If $prop is not empty then this would test that the supplied property name is not empty. Otherwise, this tests if any property was edited.

Tags
todo

This method is too complex. Consider adding an isEdited property to IProperty instead of using all of this type checking.

Return values
bool —

has edits

testEdited()

private testEdited( [ $prop : string = '' ] ) : bool
Parameters
$prop : string = ''
Return values
bool

clearEditFlags()

Clears the internal edited flags for each property

public clearEditFlags( ) : void

getPropertySet()

Retrieve the property set used for this model.

public final getPropertySet( ) : IPropertySet

This method FORMERLY returned a clone of the internal property set. Currently, this returns the internal PropertySet.

Tags
reutrn

IPropertySet properties

final
Return values
IPropertySet

getPropertyNameSet()

Retrieve property names as an IBigSet instance.

public getPropertyNameSet( ) : IBigSet

This will return a set containing all of the property names, and have zero members active. This is available due to how expensive cloning the backing IPropertySet instance can be. Use this for simple operations such as determining if a property name is valid.

This returns a SHARED instance. Either clone or don't store this anywhere.

Return values
IBigSet —

property names

getPropertyNameSetByFlags()

Retrieve a set with the property name bits toggled on for properties with the supplied flags.

public getPropertyNameSetByFlags( ...$flags : string ) : IBigSet
Parameters
$flags : string

Flags

Return values
IBigSet —

names

arrayToObject()

private arrayToObject( &$a : array ) : mixed
Parameters
$a : array
Return values
mixed

fromArray()

Sets properties from some array.

public fromArray( $data : array ) : void

Invalid properties are quietly ignored.

Parameters
$data : array

data to set

toObject()

Convert the model to a json representation.

public toObject( [ $properties : IBigSet|null = null ] [, $includeArrays : bool = false ] [, $includeModels : bool = false ] ) : string

This probably does not work with object properties. Need to test.

Parameters
$properties : IBigSet|null = null
$includeArrays : bool = false
$includeModels : bool = false
Return values
string —

JSON object

toArray()

Convert this model to an array.

public toArray( [ $properties : IPropertySet = null ] [, $includeArrays : bool = false ] [, $includeModels : bool = false ] ) : array
Parameters
$properties : IPropertySet = null

Properties to include

$includeArrays : bool = false
$includeModels : bool = false
Return values
array

equals()

Test if this model is equal to some other model

public equals( $that : IModel ) : bool
Parameters
$that : IModel

model to compare

Return values
bool —

is equals

validateProperties()

private validateProperties( [ $throw : bool = true ] ) : array
Parameters
$throw : bool = true
Return values
array

validateAll()

If you want to validate each property and return a list of errors indexed by property name, this is the method to call.

public validateAll( [ $debugErrors : bool = false ] ) : array

Note: This simply calls validate() in a loop, catches exceptions and tosses some errors in a list.

Parameters
$debugErrors : bool = false
Return values
array —

[property name => message]

hash()

Retrieve a unique hash for this object

public hash( ) : string
Return values
string —

hash

getInsertProperties()

Gets A propertyset containing properties for insert

public getInsertProperties( ) : IBigSet
Return values
IBigSet —

insert properties

jsonSerialize()

Specify data which should be serialized to JSON <p>Serializes the object to a value that can be serialized natively by <code>json_encode()</code>.</p>

public jsonSerialize( ) : mixed
Tags
link
http://php.net/manual/en/jsonserializable.jsonserialize.php
since

PHP 5 >= 5.4.0, PHP 7

Return values
mixed —

<p>Returns data which can be serialized by <code>json_encode()</code>, which is a value of any type other than a resource.</p>

beforeValidate()

Called prior to the validation loop

protected beforeValidate( ) : mixed
Return values
mixed

getProperty()

Retrieve a prop.

private getProperty( $property : string ) : IProperty

If the property name is not a member of the listed IPropertySet instance, an InvalidArgumentExcepiton is thrown. Otherwise IPropertySet::getProperty( $property ) is returned.

Parameters
$property : string

Property name

Tags
throws
InvalidArgumentException

if property is not a valid member

see
IPropertySet::getMember()
see
IPropertySet::getProperty()
Return values
IProperty —

property requested property object

getPropertyByPrefix()

If a prefix is used on some object type, this will return the

private getPropertyByPrefix( $inp : string ) : string
Parameters
$inp : string
Return values
string

getPrimaryKeyMap()

private getPrimaryKeyMap( ) : array
Return values
array

hasPrimaryKeyValues()

Test that the model has all primary key values

public hasPrimaryKeyValues( ) : bool
Return values
bool —

has values

testPrefixModelWriteNewFlag()

Called from setValue(), and used when the property has a prefix value set.

private testPrefixModelWriteNewFlag( $o : IModel , $newProperty : string ) : mixed

If the WRITE_NEW flag is set, then the The sub-model primary key properties are tested for empty. If not empty, then this throws a validation exception.

Parameters
$o : IModel
$newProperty : string
Tags
throws
ValidationException
Return values
mixed

Search results