/lib/Cake/Model/ModelBehavior.php
PHP | 220 lines | 40 code | 15 blank | 165 comment | 4 complexity | 71314859596f05533ba5e20b316a2076 MD5 | raw file
- <?php
- /**
- * Model behaviors base class.
- *
- * Adds methods and automagic functionality to Cake Models.
- *
- * PHP 5
- *
- * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
- * Copyright 2005-2011, Cake Software Foundation, Inc. (http://cakefoundation.org)
- *
- * Licensed under The MIT License
- * Redistributions of files must retain the above copyright notice.
- *
- * @copyright Copyright 2005-2011, Cake Software Foundation, Inc. (http://cakefoundation.org)
- * @link http://cakephp.org CakePHP(tm) Project
- * @package Cake.Model
- * @since CakePHP(tm) v 1.2.0.0
- * @license MIT License (http://www.opensource.org/licenses/mit-license.php)
- */
- /**
- * Model behavior base class.
- *
- * Defines the Behavior interface, and contains common model interaction functionality. Behaviors
- * allow you to simulate mixins, and create reusable blocks of application logic, that can be reused across
- * several models. Behaviors also provide a way to hook into model callbacks and augment their behavior.
- *
- * ### Mixin methods
- *
- * Behaviors can provide mixin like features by declaring public methods. These methods should expect
- * the model instance to be shifted onto the parameter list.
- *
- * {{{
- * function doSomething($model, $arg1, $arg2) {
- * //do something
- * }
- * }}}
- *
- * Would be called like `$this->Model->doSomething($arg1, $arg2);`.
- *
- * ### Mapped methods
- *
- * Behaviors can also define mapped methods. Mapped methods use pattern matching for method invocation. This
- * allows you to create methods similar to Model::findAllByXXX methods on your behaviors. Mapped methods need to
- * be declared in your behaviors `$mapMethods` array. The method signature for a mapped method is slightly different
- * than a normal behavior mixin method.
- *
- * {{{
- * public $mapMethods = array('/do(\w+)/' => 'doSomething');
- *
- * function doSomething($model, $method, $arg1, $arg2) {
- * //do something
- * }
- * }}}
- *
- * The above will map every doXXX() method call to the behavior. As you can see, the model is
- * still the first parameter, but the called method name will be the 2nd parameter. This allows
- * you to munge the method name for additional information, much like Model::findAllByXX.
- *
- * @package Cake.Model
- * @see Model::$actsAs
- * @see BehaviorCollection::load()
- */
- class ModelBehavior extends Object {
- /**
- * Contains configuration settings for use with individual model objects. This
- * is used because if multiple models use this Behavior, each will use the same
- * object instance. Individual model settings should be stored as an
- * associative array, keyed off of the model name.
- *
- * @var array
- * @see Model::$alias
- */
- public $settings = array();
- /**
- * Allows the mapping of preg-compatible regular expressions to public or
- * private methods in this class, where the array key is a /-delimited regular
- * expression, and the value is a class method. Similar to the functionality of
- * the findBy* / findAllBy* magic methods.
- *
- * @var array
- */
- public $mapMethods = array();
- /**
- * Setup this behavior with the specified configuration settings.
- *
- * @param Model $model Model using this behavior
- * @param array $config Configuration settings for $model
- * @return void
- */
- public function setup($model, $config = array()) { }
- /**
- * Clean up any initialization this behavior has done on a model. Called when a behavior is dynamically
- * detached from a model using Model::detach().
- *
- * @param Model $model Model using this behavior
- * @return void
- * @see BehaviorCollection::detach()
- */
- public function cleanup($model) {
- if (isset($this->settings[$model->alias])) {
- unset($this->settings[$model->alias]);
- }
- }
- /**
- * beforeFind can be used to cancel find operations, or modify the query that will be executed.
- * By returning null/false you can abort a find. By returning an array you can modify/replace the query
- * that is going to be run.
- *
- * @param Model $model Model using this behavior
- * @param array $query Data used to execute this query, i.e. conditions, order, etc.
- * @return boolean|array False or null will abort the operation. You can return an array to replace the
- * $query that will be eventually run.
- */
- public function beforeFind($model, $query) {
- return true;
- }
- /**
- * After find callback. Can be used to modify any results returned by find.
- *
- * @param Model $model Model using this behavior
- * @param mixed $results The results of the find operation
- * @param boolean $primary Whether this model is being queried directly (vs. being queried as an association)
- * @return mixed An array value will replace the value of $results - any other value will be ignored.
- */
- public function afterFind($model, $results, $primary) { }
- /**
- * beforeValidate is called before a model is validated, you can use this callback to
- * add behavior validation rules into a models validate array. Returning false
- * will allow you to make the validation fail.
- *
- * @param Model $model Model using this behavior
- * @return mixed False or null will abort the operation. Any other result will continue.
- */
- public function beforeValidate($model) {
- return true;
- }
- /**
- * beforeSave is called before a model is saved. Returning false from a beforeSave callback
- * will abort the save operation.
- *
- * @param Model $model Model using this behavior
- * @return mixed False if the operation should abort. Any other result will continue.
- */
- public function beforeSave($model) {
- return true;
- }
- /**
- * afterSave is called after a model is saved.
- *
- * @param Model $model Model using this behavior
- * @param boolean $created True if this save created a new record
- * @return boolean
- */
- public function afterSave($model, $created) {
- return true;
- }
- /**
- * Before delete is called before any delete occurs on the attached model, but after the model's
- * beforeDelete is called. Returning false from a beforeDelete will abort the delete.
- *
- * @param Model $model Model using this behavior
- * @param boolean $cascade If true records that depend on this record will also be deleted
- * @return mixed False if the operation should abort. Any other result will continue.
- */
- public function beforeDelete($model, $cascade = true) {
- return true;
- }
- /**
- * After delete is called after any delete occurs on the attached model.
- *
- * @param Model $model Model using this behavior
- * @return void
- */
- public function afterDelete($model) { }
- /**
- * DataSource error callback
- *
- * @param Model $model Model using this behavior
- * @param string $error Error generated in DataSource
- * @return void
- */
- public function onError($model, $error) { }
- /**
- * If $model's whitelist property is non-empty, $field will be added to it.
- * Note: this method should *only* be used in beforeValidate or beforeSave to ensure
- * that it only modifies the whitelist for the current save operation. Also make sure
- * you explicitly set the value of the field which you are allowing.
- *
- * @param Model $model Model using this behavior
- * @param string $field Field to be added to $model's whitelist
- * @return void
- */
- protected function _addToWhitelist($model, $field) {
- if (is_array($field)) {
- foreach ($field as $f) {
- $this->_addToWhitelist($model, $f);
- }
- return;
- }
- if (!empty($model->whitelist) && !in_array($field, $model->whitelist)) {
- $model->whitelist[] = $field;
- }
- }
- }