1: <?php
2: /**
3: * Model behaviors base class.
4: *
5: * Adds methods and automagic functionality to CakePHP Models.
6: *
7: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
8: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
9: *
10: * Licensed under The MIT License
11: * For full copyright and license information, please see the LICENSE.txt
12: * Redistributions of files must retain the above copyright notice.
13: *
14: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
15: * @link http://cakephp.org CakePHP(tm) Project
16: * @package Cake.Model
17: * @since CakePHP(tm) v 1.2.0.0
18: * @license http://www.opensource.org/licenses/mit-license.php MIT License
19: */
20:
21: /**
22: * Model behavior base class.
23: *
24: * Defines the Behavior interface, and contains common model interaction functionality. Behaviors
25: * allow you to simulate mixins, and create reusable blocks of application logic, that can be reused across
26: * several models. Behaviors also provide a way to hook into model callbacks and augment their behavior.
27: *
28: * ### Mixin methods
29: *
30: * Behaviors can provide mixin like features by declaring public methods. These methods should expect
31: * the model instance to be shifted onto the parameter list.
32: *
33: * ```
34: * function doSomething(Model $model, $arg1, $arg2) {
35: * //do something
36: * }
37: * ```
38: *
39: * Would be called like `$this->Model->doSomething($arg1, $arg2);`.
40: *
41: * ### Mapped methods
42: *
43: * Behaviors can also define mapped methods. Mapped methods use pattern matching for method invocation. This
44: * allows you to create methods similar to Model::findAllByXXX methods on your behaviors. Mapped methods need to
45: * be declared in your behaviors `$mapMethods` array. The method signature for a mapped method is slightly different
46: * than a normal behavior mixin method.
47: *
48: * ```
49: * public $mapMethods = array('/do(\w+)/' => 'doSomething');
50: *
51: * function doSomething(Model $model, $method, $arg1, $arg2) {
52: * //do something
53: * }
54: * ```
55: *
56: * The above will map every doXXX() method call to the behavior. As you can see, the model is
57: * still the first parameter, but the called method name will be the 2nd parameter. This allows
58: * you to munge the method name for additional information, much like Model::findAllByXX.
59: *
60: * @package Cake.Model
61: * @see Model::$actsAs
62: * @see BehaviorCollection::load()
63: */
64: class ModelBehavior extends CakeObject {
65:
66: /**
67: * Contains configuration settings for use with individual model objects. This
68: * is used because if multiple models use this Behavior, each will use the same
69: * object instance. Individual model settings should be stored as an
70: * associative array, keyed off of the model name.
71: *
72: * @var array
73: * @see Model::$alias
74: */
75: public $settings = array();
76:
77: /**
78: * Allows the mapping of preg-compatible regular expressions to public or
79: * private methods in this class, where the array key is a /-delimited regular
80: * expression, and the value is a class method. Similar to the functionality of
81: * the findBy* / findAllBy* magic methods.
82: *
83: * @var array
84: */
85: public $mapMethods = array();
86:
87: /**
88: * Setup this behavior with the specified configuration settings.
89: *
90: * @param Model $model Model using this behavior
91: * @param array $config Configuration settings for $model
92: * @return void
93: */
94: public function setup(Model $model, $config = array()) {
95: }
96:
97: /**
98: * Clean up any initialization this behavior has done on a model. Called when a behavior is dynamically
99: * detached from a model using Model::detach().
100: *
101: * @param Model $model Model using this behavior
102: * @return void
103: * @see BehaviorCollection::detach()
104: */
105: public function cleanup(Model $model) {
106: if (isset($this->settings[$model->alias])) {
107: unset($this->settings[$model->alias]);
108: }
109: }
110:
111: /**
112: * beforeFind can be used to cancel find operations, or modify the query that will be executed.
113: * By returning null/false you can abort a find. By returning an array you can modify/replace the query
114: * that is going to be run.
115: *
116: * @param Model $model Model using this behavior
117: * @param array $query Data used to execute this query, i.e. conditions, order, etc.
118: * @return bool|array False or null will abort the operation. You can return an array to replace the
119: * $query that will be eventually run.
120: */
121: public function beforeFind(Model $model, $query) {
122: return true;
123: }
124:
125: /**
126: * After find callback. Can be used to modify any results returned by find.
127: *
128: * @param Model $model Model using this behavior
129: * @param mixed $results The results of the find operation
130: * @param bool $primary Whether this model is being queried directly (vs. being queried as an association)
131: * @return mixed An array value will replace the value of $results - any other value will be ignored.
132: */
133: public function afterFind(Model $model, $results, $primary = false) {
134: }
135:
136: /**
137: * beforeValidate is called before a model is validated, you can use this callback to
138: * add behavior validation rules into a models validate array. Returning false
139: * will allow you to make the validation fail.
140: *
141: * @param Model $model Model using this behavior
142: * @param array $options Options passed from Model::save().
143: * @return mixed False or null will abort the operation. Any other result will continue.
144: * @see Model::save()
145: */
146: public function beforeValidate(Model $model, $options = array()) {
147: return true;
148: }
149:
150: /**
151: * afterValidate is called just after model data was validated, you can use this callback
152: * to perform any data cleanup or preparation if needed
153: *
154: * @param Model $model Model using this behavior
155: * @return mixed False will stop this event from being passed to other behaviors
156: */
157: public function afterValidate(Model $model) {
158: return true;
159: }
160:
161: /**
162: * beforeSave is called before a model is saved. Returning false from a beforeSave callback
163: * will abort the save operation.
164: *
165: * @param Model $model Model using this behavior
166: * @param array $options Options passed from Model::save().
167: * @return mixed False if the operation should abort. Any other result will continue.
168: * @see Model::save()
169: */
170: public function beforeSave(Model $model, $options = array()) {
171: return true;
172: }
173:
174: /**
175: * afterSave is called after a model is saved.
176: *
177: * @param Model $model Model using this behavior
178: * @param bool $created True if this save created a new record
179: * @param array $options Options passed from Model::save().
180: * @return bool
181: * @see Model::save()
182: */
183: public function afterSave(Model $model, $created, $options = array()) {
184: return true;
185: }
186:
187: /**
188: * Before delete is called before any delete occurs on the attached model, but after the model's
189: * beforeDelete is called. Returning false from a beforeDelete will abort the delete.
190: *
191: * @param Model $model Model using this behavior
192: * @param bool $cascade If true records that depend on this record will also be deleted
193: * @return mixed False if the operation should abort. Any other result will continue.
194: */
195: public function beforeDelete(Model $model, $cascade = true) {
196: return true;
197: }
198:
199: /**
200: * After delete is called after any delete occurs on the attached model.
201: *
202: * @param Model $model Model using this behavior
203: * @return void
204: */
205: public function afterDelete(Model $model) {
206: }
207:
208: /**
209: * DataSource error callback
210: *
211: * @param Model $model Model using this behavior
212: * @param string $error Error generated in DataSource
213: * @return void
214: */
215: public function onError(Model $model, $error) {
216: }
217:
218: /**
219: * If $model's whitelist property is non-empty, $field will be added to it.
220: * Note: this method should *only* be used in beforeValidate or beforeSave to ensure
221: * that it only modifies the whitelist for the current save operation. Also make sure
222: * you explicitly set the value of the field which you are allowing.
223: *
224: * @param Model $model Model using this behavior
225: * @param string $field Field to be added to $model's whitelist
226: * @return void
227: */
228: protected function _addToWhitelist(Model $model, $field) {
229: if (is_array($field)) {
230: foreach ($field as $f) {
231: $this->_addToWhitelist($model, $f);
232: }
233: return;
234: }
235: if (!empty($model->whitelist) && !in_array($field, $model->whitelist)) {
236: $model->whitelist[] = $field;
237: }
238: }
239:
240: }
241: