Reference
extends Field
in package
Elements of this class indicate a connection between two Models, this allows spitfire to let you use relational databases just like they were objects (connected to each other). While real elements are scattered around tables in no apparent manner.
This class doesn't indicate how the fields inside objects relate as their names are automatically inherited by the source model when referencing. Names for the fields are always given in a alias_srcfield fashion to improve understanding.
[NOTICE] The model doesn't check for the availability of field names, in case you have duplicate field names due to references the system may behave in an unexpected way.
Tags
Table of Contents
- TYPE_BOOLEAN = 'boolean'
- TYPE_BRIDGED = 'bridged'
- TYPE_CHILDREN = 'children'
- TYPE_DATETIME = 'datetime'
- TYPE_FILE = 'file'
- TYPE_FLOAT = 'float'
- TYPE_INTEGER = 'int'
- This constants represent the list of basic data types that spitfire supports. This should be supported by the DBMS to be used.
- TYPE_LONG = 'long'
- TYPE_REFERENCE = 'reference'
- TYPE_STRING = 'string'
- TYPE_TEXT = 'txt'
- $auto_increment : bool
- Indicates whether the field is to be incremented everytime a new record is inserted into the DBMS. This task is handled by the DBMS and Spitfire therefore does not guarantee nor enforce that the task of incrementing the field is handled correctly.
- $default : mixed
- Contains the default value for this field. In the event of this field being null but the field not-nullable, the driver should define a proper "empty" value for it's data type.
- $name : string
- Contains the name of the field inside of the model. This name should be unique and is recommended not to conatin any underscores or hyphens other than those generated by Spitfire itself to indicate it's relation with other fields and models.
- $nullable : bool
- Defines whether the field's value can be set to null or not. In case this happens the database will allow null values for this field.
- $physical : Field|array<string|int, Field>
- Contains the physical (DB) fields that are used to store the data this Field generates. For most data types Spitfire will just generate one physical field for each logical one.
- $primary : bool
- This property indicates whether the field belongs or not to the model 's primary Key. This key is the one used to identify records uniquely.
- $schema : Schema
- Contains a reference to the parent model. This allows this field to interact with it and to retrieve information about the model, the table it is in and even the DB engine that holds them.
- $target : Schema
- Indicates which model is the target of the reference. If model A references model B, then B is the target.
- $unique : bool
- This indicates whether the content of this field needs to be enforced to be unique. This restriction is handled by the DBMS and Spitfire does not guarantee that this is respected.
- __construct() : mixed
- Creates a new reference between two models, this allows them to access data through the ORM, therefore not requiring additional user generated queries to retrieve data.
- __toString() : string
- Returns the name of the Field, this is purely a conveiencce method to shorten code writing and make it easier to read.
- getAdapter() : AdapterInterface
- Returns the adapter this field wants to use for the database interaction, usually this will be a BaseAdapter that allows the most basic interaction with the most basic kinds of fields.
- getBeanField() : Field|null
- Returns the field the bean should use to render this. In case it returns null it means the field has no suggestions and the Bean should choose the way to render it
- getConnectorQueries() : mixed
- getDataType() : string
- Defines this field and all of it's children as reference fields.
- getDefault() : mixed
- getModel() : Schema
- Gets the parent model for this field. This allows the field to deliver data about which fields it's a sibling to and which fields it refers too.
- getName() : string
- Returns the name of this field. The name identifies this field among the rest of the fields of the same model / table.
- getNullable() : mixed
- getPhysical() : array<string|int, Field>
- This method returns an array of Fields. Even if the field has only one db equivalent the return value will be an array, for consistency with fields which return several ones.
- getSchema() : mixed
- getTable() : Table
- Returns the table this field belongs to. This is just a shortcut method provided to allow making logical fields and DBFields compatible.
- getTarget() : Schema
- Returns the target model (the parent model of the source). Which offers it's primary keys to the target so it can reference them.
- isAutoIncrement() : bool
- Returns whether the field is autoincrement. This means, everytime a new record of this kind is created the auto_increment field is increased by 1.
- isIndexed() : bool
- The return value of this method indicates whether the DBMS SHOULD create an index on this field. This depends on the kind of content and the settings of this field.
- isPrimary() : bool
- Returns true if the field belongs to the table's primary key. Keep in mind that a primary key can cover several fields.
- isUnique() : bool
- Returns true if the field has a unique flag, alas it's content cannot be repeated among several records.
- makePhysical() : array<string|int, Field>
- Returns a list of the fields this reference generates on the source Model. It copies the list of primary fields from the target model and prepends the role (separated by underscores) to the name of the field.
- setAutoIncrement() : self
- Defines whether the field is used as autoincrement field. This setting will have no effect on any field that is not an integer field.
- setDefault() : mixed
- setModel() : mixed
- Defines which model this field belongs to. This data basically is redundant but quickens development and makes it more efficient to find the model for the field.
- setName() : Field
- Sets the name of this field. The name identifies this field among the rest of the fields of the same model / table.
- setNullable() : mixed
- setPhysical() : mixed
- Sets the physical equivalent of this field. This needs to be a instance of DBField or an array of those.
- setPrimary() : self
- Defines whether this belongs to the primary key or not. This will also automatically set the unique flag to true.
- setSchema() : mixed
- Defines which model this field belongs to. This data basically is redundant but quickens development and makes it more efficient to find the model for the field.
- setTarget() : mixed
- Defines the target model, this model is the one 'donating' it's primary key to the source so source can reference it as a parent model.
- setUnique() : self
- Allows you to define whether the current field only allows unique (non repeated) values. When using data that only should allow unique values setting this flag to true will consistently increase the speed of database queries.
- validate() : bool|ValidationError
Constants
TYPE_BOOLEAN
public
mixed
TYPE_BOOLEAN
= 'boolean'
TYPE_BRIDGED
public
mixed
TYPE_BRIDGED
= 'bridged'
TYPE_CHILDREN
public
mixed
TYPE_CHILDREN
= 'children'
TYPE_DATETIME
public
mixed
TYPE_DATETIME
= 'datetime'
TYPE_FILE
public
mixed
TYPE_FILE
= 'file'
TYPE_FLOAT
public
mixed
TYPE_FLOAT
= 'float'
TYPE_INTEGER
This constants represent the list of basic data types that spitfire supports. This should be supported by the DBMS to be used.
public
mixed
TYPE_INTEGER
= 'int'
Tags
TYPE_LONG
public
mixed
TYPE_LONG
= 'long'
TYPE_REFERENCE
public
mixed
TYPE_REFERENCE
= 'reference'
TYPE_STRING
public
mixed
TYPE_STRING
= 'string'
TYPE_TEXT
public
mixed
TYPE_TEXT
= 'txt'
Properties
$auto_increment
Indicates whether the field is to be incremented everytime a new record is inserted into the DBMS. This task is handled by the DBMS and Spitfire therefore does not guarantee nor enforce that the task of incrementing the field is handled correctly.
private
bool
$auto_increment
= false
$default
Contains the default value for this field. In the event of this field being null but the field not-nullable, the driver should define a proper "empty" value for it's data type.
private
mixed
$default
$name
Contains the name of the field inside of the model. This name should be unique and is recommended not to conatin any underscores or hyphens other than those generated by Spitfire itself to indicate it's relation with other fields and models.
private
string
$name
$nullable
Defines whether the field's value can be set to null or not. In case this happens the database will allow null values for this field.
private
bool
$nullable
= true
$physical
Contains the physical (DB) fields that are used to store the data this Field generates. For most data types Spitfire will just generate one physical field for each logical one.
private
Field|array<string|int, Field>
$physical
Only common exception to this are the Referenced fields, which need to generate one field for each remote primary field.
$primary
This property indicates whether the field belongs or not to the model 's primary Key. This key is the one used to identify records uniquely.
private
bool
$primary
= false
Tags
$schema
Contains a reference to the parent model. This allows this field to interact with it and to retrieve information about the model, the table it is in and even the DB engine that holds them.
private
Schema
$schema
Tags
$target
Indicates which model is the target of the reference. If model A references model B, then B is the target.
private
Schema
$target
$unique
This indicates whether the content of this field needs to be enforced to be unique. This restriction is handled by the DBMS and Spitfire does not guarantee that this is respected.
private
bool
$unique
= false
Tags
Methods
__construct()
Creates a new reference between two models, this allows them to access data through the ORM, therefore not requiring additional user generated queries to retrieve data.
public
__construct(Schema|string $target) : mixed
Parameters
- $target : Schema|string
Return values
mixed —__toString()
Returns the name of the Field, this is purely a conveiencce method to shorten code writing and make it easier to read.
public
__toString() : string
Return values
string —getAdapter()
Returns the adapter this field wants to use for the database interaction, usually this will be a BaseAdapter that allows the most basic interaction with the most basic kinds of fields.
public
getAdapter(Model $model) : AdapterInterface
But you can also create custom adapters that manage complex data and return them here.
Parameters
- $model : Model
-
The model to contain the adapter
Return values
AdapterInterface —The new adapter
getBeanField()
Returns the field the bean should use to render this. In case it returns null it means the field has no suggestions and the Bean should choose the way to render it
public
getBeanField(CoffeeBean $bean, Field $field, string $caption) : Field|null
Parameters
- $bean : CoffeeBean
- $field : Field
- $caption : string
Return values
Field|null —getConnectorQueries()
public
getConnectorQueries(Query $parent) : mixed
Parameters
- $parent : Query
Return values
mixed —getDataType()
Defines this field and all of it's children as reference fields.
public
getDataType() : string
Return values
string —getDefault()
public
getDefault() : mixed
Return values
mixed —getModel()
Gets the parent model for this field. This allows the field to deliver data about which fields it's a sibling to and which fields it refers too.
public
getModel() : Schema
Return values
Schema —getName()
Returns the name of this field. The name identifies this field among the rest of the fields of the same model / table.
public
getName() : string
Return values
string —getNullable()
public
getNullable() : mixed
Return values
mixed —getPhysical()
This method returns an array of Fields. Even if the field has only one db equivalent the return value will be an array, for consistency with fields which return several ones.
public
getPhysical() : array<string|int, Field>
Return values
array<string|int, Field> —getSchema()
public
getSchema() : mixed
Return values
mixed —getTable()
Returns the table this field belongs to. This is just a shortcut method provided to allow making logical fields and DBFields compatible.
public
getTable() : Table
Return values
Table —getTarget()
Returns the target model (the parent model of the source). Which offers it's primary keys to the target so it can reference them.
public
getTarget() : Schema
Return values
Schema —isAutoIncrement()
Returns whether the field is autoincrement. This means, everytime a new record of this kind is created the auto_increment field is increased by 1.
public
isAutoIncrement() : bool
Return values
bool —isIndexed()
The return value of this method indicates whether the DBMS SHOULD create an index on this field. This depends on the kind of content and the settings of this field.
public
isIndexed() : bool
Spitfire automatically chooses the right settings for you, this function should be overriden by methods for field types that have higher performance with specific values.
Tags
Return values
bool —isPrimary()
Returns true if the field belongs to the table's primary key. Keep in mind that a primary key can cover several fields.
public
isPrimary() : bool
Tags
Return values
bool —isUnique()
Returns true if the field has a unique flag, alas it's content cannot be repeated among several records.
public
isUnique() : bool
[NOTICE] If the field is a primary key this will return true. Due to the primary having to be unique.
Tags
Return values
bool —makePhysical()
Returns a list of the fields this reference generates on the source Model. It copies the list of primary fields from the target model and prepends the role (separated by underscores) to the name of the field.
public
makePhysical() : array<string|int, Field>
This function is just included for convenience. It just generates the data in a easy way to pick, so you cannot modify the way this is done or the fields below.
Return values
array<string|int, Field> —setAutoIncrement()
Defines whether the field is used as autoincrement field. This setting will have no effect on any field that is not an integer field.
public
setAutoIncrement(bool $ai) : self
Parameters
- $ai : bool
Return values
self —setDefault()
public
setDefault(mixed $default) : mixed
Parameters
- $default : mixed
Return values
mixed —setModel()
Defines which model this field belongs to. This data basically is redundant but quickens development and makes it more efficient to find the model for the field.
public
setModel(Schema $model) : mixed
Parameters
- $model : Schema
Tags
Return values
mixed —setName()
Sets the name of this field. The name identifies this field among the rest of the fields of the same model / table.
public
setName(string $name) : Field
Parameters
- $name : string
-
New name of the field.
Return values
Field —The field, for method chaining
setNullable()
public
setNullable(mixed $nullable) : mixed
Parameters
- $nullable : mixed
Return values
mixed —setPhysical()
Sets the physical equivalent of this field. This needs to be a instance of DBField or an array of those.
public
setPhysical(Field|array<string|int, Field> $physical) : mixed
[NOTICE] As it is uncommon for this function to be called with invalid data (due to be being mainly an internal function) there is no validation being done for the type of data that is inserted. Be careful!
Parameters
- $physical : Field|array<string|int, Field>
Return values
mixed —setPrimary()
Defines whether this belongs to the primary key or not. This will also automatically set the unique flag to true.
public
setPrimary(bool $primary) : self
Parameters
- $primary : bool
Tags
Return values
self —setSchema()
Defines which model this field belongs to. This data basically is redundant but quickens development and makes it more efficient to find the model for the field.
public
setSchema(Schema $schema) : mixed
Parameters
- $schema : Schema
Return values
mixed —setTarget()
Defines the target model, this model is the one 'donating' it's primary key to the source so source can reference it as a parent model.
public
setTarget(Schema $target) : mixed
Parameters
- $target : Schema
Return values
mixed —setUnique()
Allows you to define whether the current field only allows unique (non repeated) values. When using data that only should allow unique values setting this flag to true will consistently increase the speed of database queries.
public
setUnique(bool $unique) : self
Parameters
- $unique : bool
Tags
Return values
self —validate()
public
validate(type $value) : bool|ValidationError
Parameters
- $value : type