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