• Home
• lithium
• data
• Model

PHP Class lithium\data\Model

Models are tasked with providing meaning to otherwise raw and unprocessed data (e.g. user profile). Models expose a consistent and unified API to interact with an underlying datasource (e.g. MongoDB, CouchDB, MySQL) for operations such as querying, saving, updating and deleting data from the persistent storage. Models allow you to interact with your data in two fundamentally different ways: querying, and data mutation (saving/updating/deleting). All query-related operations may be done through the static find() method, along with some additional utility methods provided for convenience. Classes extending this one should, conventionally, be named as Singular, CamelCase and be placed in the app/models directory. i.e. a posts model would be app/model/Post.php. Examples: {{{ Return all 'post' records Post::find('all'); Post::all(); With conditions and a limit Post::find('all', array('conditions' => array('published' => true), 'limit' => 10)); Post::all(array('conditions' => array('published' => true), 'limit' => 10)); Integer count of all 'post' records Post::find('count'); Post::count(); // This is equivalent to the above. With conditions Post::find('count', array('conditions' => array('published' => true))); Post::count(array('published' => true)); }}} The actual objects returned from find() calls will depend on the type of datasource in use. MongoDB, for example, will return results as a Document, while MySQL will return results as a RecordSet. Both of these classes extend a common data\Collection class, and provide the necessary abstraction to make working with either type completely transparent. For data mutation (saving/updating/deleting), the Model class acts as a broker to the proper objects. When creating a new record, for example, a call to Post::create() will return a data\model\Record object, which can then be acted upon. Example: {{{ $post = Post::create(); $post->author = 'Robert'; $post->title = 'Newest Post!'; $post->content = 'Lithium rocks. That is all.'; $post->save(); }}} Show file Open project: unionofrad/lithium Class Usage Examples

Public Properties

Property	Type	Description
$belongsTo	array	Model belongsTo relations.
$hasMany	array	Model hasMany relations.
$hasOne	array	Model hasOne relations.
$validates	array	Example usage: public $validates = array( 'title' => 'please enter a title', 'email' => array( array('notEmpty', 'message' => 'Email is empty.'), array('email', 'message' => 'Email is not valid.'), ) );

Protected Properties

Property	Type	Description
$_autoConfig	array	Holds an array of values that should be processed on Model::config(). Each value should have a matching protected property (prefixed with _) defined in the class. If the property is an array, the property name should be the key and the value should be 'merge'.
$_classes	array	Class dependencies.
$_finders	array	Custom find query properties, indexed by name.
$_inherits	array	Holds an array of attributes to be inherited.
$_initialized	array	List of initialized instances.
$_initializers	array	Array of closures used to lazily initialize metadata.
$_instanceFilters	array	Stores the filters that are applied to the model instances stored in Model::$_instances.
$_instanceMethods	array	Stores all custom instance methods created by Model::instanceMethods.
$_instances	array	While the Model public API does not require instantiation thanks to late static binding introduced in PHP 5.3, LSB does not apply to class attributes. In order to prevent you from needing to redeclare every single Model class attribute in subclasses, instances of the models are stored and used internally.
$_meta	array	- connection: The name of the connection (as defined in Connections::add()) to which the model should bind - key: The primary key or identifier key for records / documents this model produces, i.e. 'id' or array('_id', '_rev'). Defaults to 'id'. - name: The canonical name of this model. Defaults to the class name. - source: The name of the database table or document collection to bind to. Defaults to the lower-cased and underscored name of the class, i.e. class UserProfile maps to 'user_profiles'. - title: The field or key used as the title for each record. Defaults to 'title' or 'name', if those fields are available.
$_query	array	- 'conditions': The conditional query elements, e.g. array('published' => true). - 'fields': The fields that should be retrieved. When unset or explitily set to null, '*' or left unset, defaults to all fields. - 'order': The order in which the data will be returned, e.g. array('id' => 'ASC') or array('modified' => 'DESC'). - 'limit': The maximum number of records to return. - 'page': For pagination of data (equals limit * offset). - 'with': An array of relationship names to be included in the query.
$_relationFieldNames	array	Matching between relation's fieldnames and their corresponding relation name.
$_relationTypes	array	Valid relation types are: - belongsTo - hasOne - hasMany
$_relations	array	A list of the current relation types for this Model.
$_relationsToLoad		Store available relation names for this model which still unloaded.
$_schema	array	The schema is lazy-loaded by the first call to Model::schema(), unless it has been manually defined in the Model subclass. For schemaless persistent storage (e.g. MongoDB), this is never populated automatically - if you desire a fixed schema to interact with in those cases, you will be required to define it yourself. Example: protected $_schema = array( '_id' => array('type' => 'id'), // required for Mongo 'name' => array('type' => 'string', 'default' => 'Moe', 'null' => false), 'sign' => array('type' => 'string', 'default' => 'bar', 'null' => false), 'age' => array('type' => 'integer', 'default' => 0, 'null' => false) ); For MongoDB specifically, you can also implement a callback in your database connection configuration that fetches and returns the schema data, as in the following: config/bootstrap/connections.php: Connections::add('default', array( 'type' => 'MongoDb', 'host' => 'localhost', 'database' => 'app_name', 'schema' => function($db, $collection, $meta) { $result = $db->connection->schemas->findOne(compact('collection')); return $result ? $result['data'] : array(); } )); This example defines an optional MongoDB convention in which the schema for each individual collection is stored in a "schemas" collection, where each document contains the name of a collection, along with a 'data' key, which contains the schema for that collection, in the format specified above. When defining '$_schema' where the data source is MongoDB, the types map to database types as follows: id => MongoId date => MongoDate regex => MongoRegex integer => integer float => float boolean => boolean code => MongoCode binary => MongoBinData

Public Methods

Method	Description
__call ( string $method, array $params ) : mixed	Magic method that allows calling Model::_instanceMethods's closure like normal methods on the model instance.
__callStatic ( string $method, array $params ) : mixed	Enables magic finders. These provide some syntactic-sugar which allows to i.e. use Model::all() instead of Model::find('all').
applyFilter ( string $method, mixed $closure = null )	Wraps StaticObject::applyFilter() to account for object instances.
bind ( string $type, string $name, array $config = [] ) : object	Creates a relationship binding between this model and another.
config ( array $config = [] )	Configures the model for use. This method will set the Model::$_schema, Model::$_meta, Model::$_finders class attributes, as well as obtain a handle to the configured persistent storage connection.
connection ( ) : object	Gets the connection object to which this model is bound. Throws exceptions if a connection isn't set, or if the connection named isn't configured.
create ( array $data = [], array $options = [] ) : object	Instantiates a new record or document object, initialized with any data passed in. For example:
delete ( object $entity, array $options = [] ) : boolean	Deletes the data associated with the current Model.
find ( string | object | integer $type, array $options = [] ) : mixed	The find method allows you to retrieve data from the connected data source.
finder ( string $name, string | callable | null $finder = null ) : callable | void	Sets or gets a custom finder by name. The finder definition can be an array of default query options, or an anonymous functions that accepts an array of query options, and a function to continue. To get a finder specify just the name.
hasField ( mixed $field ) : mixed	Checks to see if a particular field exists in a model's schema. Can check a single field, or return the first field found in an array of multiple options.
instanceMethods ( array $methods = null ) : array	Getter and setter for custom instance methods. This is used in Entity::__call().
key ( mixed $values = null ) : mixed	If no values supplied, returns the name of the Model key. If values are supplied, returns the key value.
meta ( string $key = null, string $value = null ) : mixed	Gets or sets Model's metadata.
query ( array $query = null ) : mixed	Gets or sets the default query for the model.
relations ( string $type = null ) : array | object | void	Returns a list of models related to Model, or a list of models related to this model, but of a certain type.
remove ( mixed $conditions = [], array $options = [] ) : boolean	Remove multiple documents or records based on a given set of criteria. **WARNING**: If no criteria are specified, or if the criteria ($conditions) is an empty value (i.e. an empty array or null), all the data in the backend data source (i.e. table or collection) _will_ be deleted.
reset ( )	Resetting the model.
respondsTo ( string $method, boolean $internal = false ) : boolean	Determines if a given method can be called.
save ( object $entity, array $data = null, array $options = [] ) : boolean	An instance method (called on record and document objects) to create or update the record or document in the database that corresponds to $entity.
schema ( mixed $field = null ) : array | lithium\data\Schema	Lazy-initialize the schema for this Model object, if it is not already manually set in the object. You can declare `protected $_schema = array(.
title ( object $entity ) : string	The title() method is invoked whenever an Entity object is cast or coerced to a string. This method can also be called on the entity directly, i.e. $post->title().
update ( mixed $data, mixed $conditions = [], array $options = [] ) : boolean	Update multiple records or documents with the given data, restricted by the given set of criteria (optional).
validates ( object $entity, array $options = [] ) : boolean	An important part of describing the business logic of a model class is defining the validation rules. In Lithium models, rules are defined through the $validates class property, and are used by this method before saving to verify the correctness of the data being sent to the backend data source.

Protected Methods

Method	Description
_filter ( string $method, array $params, mixed $callback, array $filters = [] ) : object	Wraps StaticObject::_filter() to account for object instances.
_finders ( ) : array	Returns an array with the default finders.
_getMetaKey ( string $key = null ) : mixed	Helper method used by meta() to generate and cache metadata values.
_inherit ( )	Merge parent class attributes to the current instance.
_inherited ( )	Return inherited attributes.
_initialize ( string $class ) : object	Init default connection options and connects default finders.
_instance ( string | object $name, array $options = [] ) : object	Returns an instance of a class with given config. The name could be a key from the classes array, a fully-namespaced class name, or an object. Typically this method is used in _init to create the dependencies used in the current class.
_key ( string $key, object $values, string $entity ) : mixed	Helper for the Model::key() function
_object ( )
_relationFieldName ( $type, $name )
_relations ( $type = null, $name = null ) : An	This method automagically bind in the fly unloaded relations.
_relationsToLoad ( ) : void	Iterates through relationship types to construct relation map.

Method Details

Property Details