DEFAULT_SOURCE_TYPE
DEFAULT_SOURCE_TYPE
\Charcoal\ModelModel
Charcoal Model class
The Charcoal Model
Custom Object Type
It is possible to attach a custom object type ($_obj_type) to a Model. This will allow the
various loaders (metadata and source data)
Metadata
In Charcoal, all models are held in an instance of \Charcoal\Model\Model
and its configuration meta-data structure is defined in a \Charcoal\Model\Metadata object.
Loading metadata
To access the metadata, use $this->metadata(). To set metadata, use either
Properties
The Model Attributes are stored in \Charcoal\Property\PropertyInterface objects. The properties are defined
in the Model's metadata and can be accessed either with p($ident) to retrieve a property or with
properties() to get all properties.
Data Source
The Model data (which is stored internally in the class) can be stored in a storage Source object.
There is only one source type currently implemented: \Charcoal\Source\Database.
Loading from source
...
Loading into Collection
...
Data validation
Once an object has had its data filled (from a form, database, or other source), it is possible to check
wether the data is conform to the object definition, as defined by it's properties and meta-properties.
This check is done with the validate() function.
The validate() method always return a boolean (true for success and false if there was any
validation error(s)). The validation details are held in a Validator object which can then be
accessed with the validator() method.
Rendering a model
Every Charcoal Model can be rendered with the help of a View and a ViewController.
Or, more precisely, a \Charcoal\View\ModelView and a \Charcoal\View\ModelViewController.
Summary
setDependencies()
setData()
data()
mergeData()
defaultData()
setFlatData()
flatData()
propertyValue()
saveProperties()
loadFromL10n()
save()
createView()
objType()
setMetadataLoader()
setMetadata()
metadata()
loadMetadata()
setMetadataIdent()
metadataIdent()
setId()
id()
setKey()
key()
setSource()
source()
load()
loadFrom()
loadFromQuery()
update()
delete()
setValidator()
validator()
validate()
preSave()
preUpdate()
createMetadata()
createSource()
createValidator()
metadataLoader()
generateMetadataIdent()
setSourceFactory()
sourceFactory()
postSave()
postUpdate()
preDelete()
postDelete()
$metadata
$metadataIdent
$id
$key
$sourceFactory
$validator
Constants
Properties
$metadataLoader
$metadataLoader : \Charcoal\Model\Service\MetadataLoader
Type
\Charcoal\Model\Service\MetadataLoader$metadata
$metadata : \Charcoal\Model\MetadataInterface
Type
\Charcoal\Model\MetadataInterface$validator
$validator : \Charcoal\Validator\ValidatorInterface
In-objet copy of the `ValidatorInterface` validator object
Type
\Charcoal\Validator\ValidatorInterface$source
$source : \Charcoal\Source\SourceInterface
Type
\Charcoal\Source\SourceInterfaceMethods
setData()
setData(array $data) : \Charcoal\Model\DescribableInterface
Describable object needs to have a `setData()` method
Parameters
| array | $data | The object's data. |
Returns
\Charcoal\Model\DescribableInterface —Chainable
mergeData()
mergeData(array|\Traversable $data) : \Charcoal\Model\EntityInterface
Override's `\Charcoal\Config\AbstractEntity`'s `setData` method to take properties into consideration.
Also add a special case, to merge values for l10n properties.
Parameters
| array|\Traversable | $data | The data to merge. |
Returns
\Charcoal\Model\EntityInterface —Chainable
setFlatData()
setFlatData(array $flatData) : \Charcoal\Model\AbstractModel
Sets the data
This function takes a 1-dimensional array and fill the object with its value.
Parameters
| array | $flatData | The data, as a flat (1-dimension) array. |
Returns
\Charcoal\Model\AbstractModel —Chainable
loadFromL10n()
loadFromL10n(string $key, mixed $value, array $langs) : string
Load an object from the database from its l10n key $key.
Also retrieve and return the actual language that matched.
Parameters
| string | $key | Key pointing a column's l10n base ident. |
| mixed | $value | Value to search in all languages. |
| array | $langs | List of languages (code, ex: "en") to check into. |
Throws
- \Exception
If the PDO query fails.
Returns
string —The matching language.
setMetadataLoader()
setMetadataLoader(\Charcoal\Model\Service\MetadataLoader $loader) : \Charcoal\Model\DescribableInterface
Parameters
| \Charcoal\Model\Service\MetadataLoader | $loader | The loader instance, used to load metadata. |
Returns
\Charcoal\Model\DescribableInterface —Chainable
setMetadata()
setMetadata(array|\Charcoal\Model\MetadataInterface $metadata) : \Charcoal\Model\DescribableInterface
Parameters
| array|\Charcoal\Model\MetadataInterface | $metadata | The object's metadata. |
Throws
- \InvalidArgumentException
If the parameter is not an array or MetadataInterface.
Returns
\Charcoal\Model\DescribableInterface —Chainable
metadata()
metadata() : \Charcoal\Model\MetadataInterface
Returns
\Charcoal\Model\MetadataInterfaceloadMetadata()
loadMetadata(string $metadataIdent = null) : \Charcoal\Model\MetadataInterface
Load a metadata file and store it as a static var.
Use a MetadataLoader object and the object's metadataIdent
to load the metadata content (typically from the filesystem, as json).
Parameters
| string | $metadataIdent | Optional ident. |
Returns
\Charcoal\Model\MetadataInterfacesetMetadataIdent()
setMetadataIdent(string $metadataIdent) : \Charcoal\Model\DescribableInterface
Parameters
| string | $metadataIdent | The metadata ident. |
Returns
\Charcoal\Model\DescribableInterface —Chainable
setId()
setId(mixed $id) : \Charcoal\Source\StorableInterface
Set the object's ID. The actual property set depends on `key()`
Parameters
| mixed | $id | The object id (identifier / primary key value). |
Throws
- \InvalidArgumentException
If the argument is not scalar.
Returns
\Charcoal\Source\StorableInterface —Chainable
setKey()
setKey(string $key) : \Charcoal\Source\StorableInterface
Set the key property.
Parameters
| string | $key | The object key, or identifier "name". |
Throws
- \InvalidArgumentException
If the argument is not scalar.
Returns
\Charcoal\Source\StorableInterface —Chainable
setSource()
setSource(\Charcoal\Source\SourceInterface $source) : \Charcoal\Source\StorableInterface
Set the object's source.
Parameters
| \Charcoal\Source\SourceInterface | $source | The storable object's source. |
Returns
\Charcoal\Source\StorableInterface —Chainable
source()
source() : \Charcoal\Source\SourceInterface
Get the object's source.
Returns
\Charcoal\Source\SourceInterfaceload()
load(mixed $id = null) : \Charcoal\Source\StorableInterface
Load an object from the database from its ID.
Parameters
| mixed | $id | The identifier to load. |
Returns
\Charcoal\Source\StorableInterface —Chainable
loadFrom()
loadFrom(string $key = null, mixed $value = null) : \Charcoal\Source\StorableInterface
Load an object from the database from its key $key.
Parameters
| string | $key | Key pointing a column's name. |
| mixed | $value | Value of said column. |
Returns
\Charcoal\Source\StorableInterface —Chainable.
loadFromQuery()
loadFromQuery(string $query, array $binds = array()) : \Charcoal\Source\StorableInterface
Load an object from the database from a custom SQL query.
Parameters
| string | $query | The SQL query. |
| array | $binds | Optional. The SQL query parameters. |
Returns
\Charcoal\Source\StorableInterface —Chainable.
setValidator()
setValidator(\Charcoal\Validator\ValidatorInterface $validator) : \Charcoal\Validator\ValidatableInterface
Parameters
| \Charcoal\Validator\ValidatorInterface | $validator | The validator object to use for validation. |
Returns
\Charcoal\Validator\ValidatableInterface —Chainable
validator()
validator() : \Charcoal\Validator\ValidatorInterface
Returns
\Charcoal\Validator\ValidatorInterfacevalidate()
validate(\Charcoal\Validator\ValidatorInterface $v = null) : boolean
Parameters
| \Charcoal\Validator\ValidatorInterface | $v | Optional. A custom validator object to use for validation. If null, use object's. |
Returns
booleansetIdFromData()
setIdFromData(array|\Traversable $data) : array|\Traversable
Set the object's ID from an associative array map (or any other Traversable).
Useful for setting the object ID before the rest of the object's data.
Parameters
| array|\Traversable | $data | The object data. |
Returns
array|\Traversable —The object data without the pre-set ID.
createMetadata()
createMetadata() : \Charcoal\Model\MetadataInterface
Returns
\Charcoal\Model\MetadataInterfacecreateSource()
createSource() : \Charcoal\Source\SourceInterface
Create the model's source, with the Source Factory.
Returns
\Charcoal\Source\SourceInterfacecreateValidator()
createValidator() : \Charcoal\Validator\ValidatorInterface
Returns
\Charcoal\Validator\ValidatorInterfacemetadataLoader()
metadataLoader() : \Charcoal\Model\Service\MetadataLoader
Safe MetdataLoader getter. Create the loader if it does not exist.
Throws
- \Exception
If the metadata loader was not set.
Returns
\Charcoal\Model\Service\MetadataLoadersetSourceFactory()
setSourceFactory(\Charcoal\Factory\FactoryInterface $factory) : \Charcoal\Source\StorableInterface
Parameters
| \Charcoal\Factory\FactoryInterface | $factory | The source factory, which is useful to create source. |
Returns
\Charcoal\Source\StorableInterface —Chainable