1<?php
2/**
3 * Behavior for binding management.
4 *
5 * Behavior to simplify manipulating a model's bindings when doing a find operation
6 *
7 * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
8 * Copyright (c) Cake Software Foundation, Inc. (https://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. (https://cakefoundation.org)
15 * @link          https://cakephp.org CakePHP(tm) Project
16 * @package       Cake.Model.Behavior
17 * @since         CakePHP(tm) v 1.2.0.5669
18 * @license       https://opensource.org/licenses/mit-license.php MIT License
19 */
20
21App::uses('ModelBehavior', 'Model');
22
23/**
24 * Behavior to allow for dynamic and atomic manipulation of a Model's associations
25 * used for a find call. Most useful for limiting the amount of associations and
26 * data returned.
27 *
28 * @package       Cake.Model.Behavior
29 * @link https://book.cakephp.org/2.0/en/core-libraries/behaviors/containable.html
30 */
31class ContainableBehavior extends ModelBehavior {
32
33/**
34 * Types of relationships available for models
35 *
36 * @var array
37 */
38	public $types = array('belongsTo', 'hasOne', 'hasMany', 'hasAndBelongsToMany');
39
40/**
41 * Runtime configuration for this behavior
42 *
43 * @var array
44 */
45	public $runtime = array();
46
47/**
48 * Initiate behavior for the model using specified settings.
49 *
50 * Available settings:
51 *
52 * - recursive: (boolean, optional) set to true to allow containable to automatically
53 *   determine the recursiveness level needed to fetch specified models,
54 *   and set the model recursiveness to this level. setting it to false
55 *   disables this feature. DEFAULTS TO: true
56 * - notices: (boolean, optional) issues E_NOTICES for bindings referenced in a
57 *   containable call that are not valid. DEFAULTS TO: true
58 * - autoFields: (boolean, optional) auto-add needed fields to fetch requested
59 *   bindings. DEFAULTS TO: true
60 *
61 * @param Model $Model Model using the behavior
62 * @param array $settings Settings to override for model.
63 * @return void
64 */
65	public function setup(Model $Model, $settings = array()) {
66		if (!isset($this->settings[$Model->alias])) {
67			$this->settings[$Model->alias] = array('recursive' => true, 'notices' => true, 'autoFields' => true);
68		}
69		$this->settings[$Model->alias] = array_merge($this->settings[$Model->alias], $settings);
70	}
71
72/**
73 * Runs before a find() operation. Used to allow 'contain' setting
74 * as part of the find call, like this:
75 *
76 * `Model->find('all', array('contain' => array('Model1', 'Model2')));`
77 *
78 * ```
79 * Model->find('all', array('contain' => array(
80 * 	'Model1' => array('Model11', 'Model12'),
81 * 	'Model2',
82 * 	'Model3' => array(
83 * 		'Model31' => 'Model311',
84 * 		'Model32',
85 * 		'Model33' => array('Model331', 'Model332')
86 * )));
87 * ```
88 *
89 * @param Model $Model Model using the behavior
90 * @param array $query Query parameters as set by cake
91 * @return array
92 */
93	public function beforeFind(Model $Model, $query) {
94		$reset = (isset($query['reset']) ? $query['reset'] : true);
95		$noContain = false;
96		$contain = array();
97
98		if (isset($this->runtime[$Model->alias]['contain'])) {
99			$noContain = empty($this->runtime[$Model->alias]['contain']);
100			$contain = $this->runtime[$Model->alias]['contain'];
101			unset($this->runtime[$Model->alias]['contain']);
102		}
103
104		if (isset($query['contain'])) {
105			$noContain = $noContain || empty($query['contain']);
106			if ($query['contain'] !== false) {
107				$contain = array_merge($contain, (array)$query['contain']);
108			}
109		}
110		$noContain = $noContain && empty($contain);
111
112		if ($noContain || empty($contain)) {
113			if ($noContain) {
114				$query['recursive'] = -1;
115			}
116			return $query;
117		}
118		if ((isset($contain[0]) && is_bool($contain[0])) || is_bool(end($contain))) {
119			$reset = is_bool(end($contain))
120				? array_pop($contain)
121				: array_shift($contain);
122		}
123		$containments = $this->containments($Model, $contain);
124		$map = $this->containmentsMap($containments);
125
126		$mandatory = array();
127		foreach ($containments['models'] as $model) {
128			$instance = $model['instance'];
129			$needed = $this->fieldDependencies($instance, $map, false);
130			if (!empty($needed)) {
131				$mandatory = array_merge($mandatory, $needed);
132			}
133			if ($contain) {
134				$backupBindings = array();
135				foreach ($this->types as $relation) {
136					if (!empty($instance->__backAssociation[$relation])) {
137						$backupBindings[$relation] = $instance->__backAssociation[$relation];
138					} else {
139						$backupBindings[$relation] = $instance->{$relation};
140					}
141				}
142				foreach ($this->types as $type) {
143					$unbind = array();
144					foreach ($instance->{$type} as $assoc => $options) {
145						if (!isset($model['keep'][$assoc])) {
146							$unbind[] = $assoc;
147						}
148					}
149					if (!empty($unbind)) {
150						if (!$reset && empty($instance->__backOriginalAssociation)) {
151							$instance->__backOriginalAssociation = $backupBindings;
152						}
153						$instance->unbindModel(array($type => $unbind), $reset);
154					}
155					foreach ($instance->{$type} as $assoc => $options) {
156						if (isset($model['keep'][$assoc]) && !empty($model['keep'][$assoc])) {
157							if (isset($model['keep'][$assoc]['fields'])) {
158								$model['keep'][$assoc]['fields'] = $this->fieldDependencies($containments['models'][$assoc]['instance'], $map, $model['keep'][$assoc]['fields']);
159							}
160							if (!$reset && empty($instance->__backOriginalAssociation)) {
161								$instance->__backOriginalAssociation = $backupBindings;
162							} elseif ($reset) {
163								$instance->__backAssociation[$type] = $backupBindings[$type];
164							}
165							$instance->{$type}[$assoc] = array_merge($instance->{$type}[$assoc], $model['keep'][$assoc]);
166						}
167						if (!$reset) {
168							$instance->__backInnerAssociation[] = $assoc;
169						}
170					}
171				}
172			}
173		}
174
175		if ($this->settings[$Model->alias]['recursive']) {
176			$query['recursive'] = (isset($query['recursive'])) ? max($query['recursive'], $containments['depth']) : $containments['depth'];
177		}
178
179		$autoFields = ($this->settings[$Model->alias]['autoFields']
180					&& !in_array($Model->findQueryType, array('list', 'count'))
181					&& !empty($query['fields']));
182
183		if (!$autoFields) {
184			return $query;
185		}
186
187		$query['fields'] = (array)$query['fields'];
188		foreach (array('hasOne', 'belongsTo') as $type) {
189			if (!empty($Model->{$type})) {
190				foreach ($Model->{$type} as $assoc => $data) {
191					if ($Model->useDbConfig === $Model->{$assoc}->useDbConfig && !empty($data['fields'])) {
192						foreach ((array)$data['fields'] as $field) {
193							$query['fields'][] = (strpos($field, '.') === false ? $assoc . '.' : '') . $field;
194						}
195					}
196				}
197			}
198		}
199
200		if (!empty($mandatory[$Model->alias])) {
201			foreach ($mandatory[$Model->alias] as $field) {
202				if ($field === '--primaryKey--') {
203					$field = $Model->primaryKey;
204				} elseif (preg_match('/^.+\.\-\-[^-]+\-\-$/', $field)) {
205					list($modelName, $field) = explode('.', $field);
206					if ($Model->useDbConfig === $Model->{$modelName}->useDbConfig) {
207						$field = $modelName . '.' . (
208							($field === '--primaryKey--') ? $Model->$modelName->primaryKey : $field
209						);
210					} else {
211						$field = null;
212					}
213				}
214				if ($field !== null) {
215					$query['fields'][] = $field;
216				}
217			}
218		}
219		$query['fields'] = array_unique($query['fields']);
220		return $query;
221	}
222
223/**
224 * Unbinds all relations from a model except the specified ones. Calling this function without
225 * parameters unbinds all related models.
226 *
227 * @param Model $Model Model on which binding restriction is being applied
228 * @return void
229 * @link https://book.cakephp.org/2.0/en/core-libraries/behaviors/containable.html#using-containable
230 */
231	public function contain(Model $Model) {
232		$args = func_get_args();
233		$contain = call_user_func_array('am', array_slice($args, 1));
234		$this->runtime[$Model->alias]['contain'] = $contain;
235	}
236
237/**
238 * Permanently restore the original binding settings of given model, useful
239 * for restoring the bindings after using 'reset' => false as part of the
240 * contain call.
241 *
242 * @param Model $Model Model on which to reset bindings
243 * @return void
244 */
245	public function resetBindings(Model $Model) {
246		if (!empty($Model->__backOriginalAssociation)) {
247			$Model->__backAssociation = $Model->__backOriginalAssociation;
248			unset($Model->__backOriginalAssociation);
249		}
250		$Model->resetAssociations();
251		if (!empty($Model->__backInnerAssociation)) {
252			$assocs = $Model->__backInnerAssociation;
253			$Model->__backInnerAssociation = array();
254			foreach ($assocs as $currentModel) {
255				$this->resetBindings($Model->$currentModel);
256			}
257		}
258	}
259
260/**
261 * Process containments for model.
262 *
263 * @param Model $Model Model on which binding restriction is being applied
264 * @param array $contain Parameters to use for restricting this model
265 * @param array $containments Current set of containments
266 * @param bool $throwErrors Whether non-existent bindings show throw errors
267 * @return array Containments
268 */
269	public function containments(Model $Model, $contain, $containments = array(), $throwErrors = null) {
270		$options = array('className', 'joinTable', 'with', 'foreignKey', 'associationForeignKey', 'conditions', 'fields', 'order', 'limit', 'offset', 'unique', 'finderQuery');
271		$keep = array();
272		if ($throwErrors === null) {
273			$throwErrors = (empty($this->settings[$Model->alias]) ? true : $this->settings[$Model->alias]['notices']);
274		}
275		foreach ((array)$contain as $name => $children) {
276			if (is_numeric($name)) {
277				$name = $children;
278				$children = array();
279			}
280			if (preg_match('/(?<!\.)\(/', $name)) {
281				$name = str_replace('(', '.(', $name);
282			}
283			if (strpos($name, '.') !== false) {
284				$chain = explode('.', $name);
285				$name = array_shift($chain);
286				$children = array(implode('.', $chain) => $children);
287			}
288
289			$children = (array)$children;
290			foreach ($children as $key => $val) {
291				if (is_string($key) && is_string($val) && !in_array($key, $options, true)) {
292					$children[$key] = (array)$val;
293				}
294			}
295
296			$keys = array_keys($children);
297			if ($keys && isset($children[0])) {
298				$keys = array_merge(array_values($children), $keys);
299			}
300
301			foreach ($keys as $i => $key) {
302				if (is_array($key)) {
303					continue;
304				}
305				$optionKey = in_array($key, $options, true);
306				if (!$optionKey && is_string($key) && preg_match('/^[a-z(]/', $key) && (!isset($Model->{$key}) || !is_object($Model->{$key}))) {
307					$option = 'fields';
308					$val = array($key);
309					if ($key[0] === '(') {
310						$val = preg_split('/\s*,\s*/', substr($key, 1, -1));
311					} elseif (preg_match('/ASC|DESC$/', $key)) {
312						$option = 'order';
313						$val = $Model->{$name}->alias . '.' . $key;
314					} elseif (preg_match('/[ =!]/', $key)) {
315						$option = 'conditions';
316						$val = $Model->{$name}->alias . '.' . $key;
317					}
318					$children[$option] = is_array($val) ? $val : array($val);
319					$newChildren = null;
320					if (!empty($name) && !empty($children[$key])) {
321						$newChildren = $children[$key];
322					}
323					unset($children[$key], $children[$i]);
324					$key = $option;
325					$optionKey = true;
326					if (!empty($newChildren)) {
327						$children = Hash::merge($children, $newChildren);
328					}
329				}
330				if ($optionKey && isset($children[$key])) {
331					if (!empty($keep[$name][$key]) && is_array($keep[$name][$key])) {
332						$keep[$name][$key] = array_merge((isset($keep[$name][$key]) ? $keep[$name][$key] : array()), (array)$children[$key]);
333					} else {
334						$keep[$name][$key] = $children[$key];
335					}
336					unset($children[$key]);
337				}
338			}
339
340			if (!isset($Model->{$name}) || !is_object($Model->{$name})) {
341				if ($throwErrors) {
342					trigger_error(__d('cake_dev', 'Model "%s" is not associated with model "%s"', $Model->alias, $name), E_USER_WARNING);
343				}
344				continue;
345			}
346
347			$containments = $this->containments($Model->{$name}, $children, $containments);
348			$depths[] = $containments['depth'] + 1;
349			if (!isset($keep[$name])) {
350				$keep[$name] = array();
351			}
352		}
353
354		if (!isset($containments['models'][$Model->alias])) {
355			$containments['models'][$Model->alias] = array('keep' => array(), 'instance' => &$Model);
356		}
357
358		$containments['models'][$Model->alias]['keep'] = array_merge($containments['models'][$Model->alias]['keep'], $keep);
359		$containments['depth'] = empty($depths) ? 0 : max($depths);
360		return $containments;
361	}
362
363/**
364 * Calculate needed fields to fetch the required bindings for the given model.
365 *
366 * @param Model $Model Model
367 * @param array $map Map of relations for given model
368 * @param array|bool $fields If array, fields to initially load, if false use $Model as primary model
369 * @return array Fields
370 */
371	public function fieldDependencies(Model $Model, $map, $fields = array()) {
372		if ($fields === false) {
373			foreach ($map as $parent => $children) {
374				foreach ($children as $type => $bindings) {
375					foreach ($bindings as $dependency) {
376						if ($type === 'hasAndBelongsToMany') {
377							$fields[$parent][] = '--primaryKey--';
378						} elseif ($type === 'belongsTo') {
379							$fields[$parent][] = $dependency . '.--primaryKey--';
380						}
381					}
382				}
383			}
384			return $fields;
385		}
386		if (empty($map[$Model->alias])) {
387			return $fields;
388		}
389		foreach ($map[$Model->alias] as $type => $bindings) {
390			foreach ($bindings as $dependency) {
391				$innerFields = array();
392				switch ($type) {
393					case 'belongsTo':
394						$fields[] = $Model->{$type}[$dependency]['foreignKey'];
395						break;
396					case 'hasOne':
397					case 'hasMany':
398						$innerFields[] = $Model->$dependency->primaryKey;
399						$fields[] = $Model->primaryKey;
400						break;
401				}
402				if (!empty($innerFields) && !empty($Model->{$type}[$dependency]['fields'])) {
403					$Model->{$type}[$dependency]['fields'] = array_unique(array_merge($Model->{$type}[$dependency]['fields'], $innerFields));
404				}
405			}
406		}
407		return array_unique($fields);
408	}
409
410/**
411 * Build the map of containments
412 *
413 * @param array $containments Containments
414 * @return array Built containments
415 */
416	public function containmentsMap($containments) {
417		$map = array();
418		foreach ($containments['models'] as $name => $model) {
419			$instance = $model['instance'];
420			foreach ($this->types as $type) {
421				foreach ($instance->{$type} as $assoc => $options) {
422					if (isset($model['keep'][$assoc])) {
423						$map[$name][$type] = isset($map[$name][$type]) ? array_merge($map[$name][$type], (array)$assoc) : (array)$assoc;
424					}
425				}
426			}
427		}
428		return $map;
429	}
430
431}
432