1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 3.0.0
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\Database;
16:
17: /**
18: * Implements default and single-use mappings for columns to their associated types
19: */
20: class TypeMap
21: {
22:
23: /**
24: * Associative array with the default fields and the related types this query might contain.
25: *
26: * Used to avoid repetition when calling multiple functions inside this class that
27: * may require a custom type for a specific field.
28: *
29: * @var array
30: */
31: protected $_defaults;
32:
33: /**
34: * Associative array with the fields and the related types that override defaults this query might contain
35: *
36: * Used to avoid repetition when calling multiple functions inside this class that
37: * may require a custom type for a specific field.
38: *
39: * @var array
40: */
41: protected $_types = [];
42:
43: /**
44: * Creates an instance with the given defaults
45: *
46: * @param array $defaults The defaults to use.
47: */
48: public function __construct(array $defaults = [])
49: {
50: $this->setDefaults($defaults);
51: }
52:
53: /**
54: * Configures a map of default fields and their associated types to be
55: * used as the default list of types for every function in this class
56: * with a $types param. Useful to avoid repetition when calling the same
57: * functions using the same fields and types.
58: *
59: * ### Example
60: *
61: * ```
62: * $query->setDefaults(['created' => 'datetime', 'is_visible' => 'boolean']);
63: * ```
64: *
65: * This method will replace all the existing type maps with the ones provided.
66: *
67: * @param array $defaults Associative array where keys are field names and values
68: * are the correspondent type.
69: * @return $this
70: */
71: public function setDefaults(array $defaults)
72: {
73: $this->_defaults = $defaults;
74:
75: return $this;
76: }
77:
78: /**
79: * Returns the currently configured types.
80: *
81: * @return array
82: */
83: public function getDefaults()
84: {
85: return $this->_defaults;
86: }
87:
88: /**
89: * Configures a map of default fields and their associated types to be
90: * used as the default list of types for every function in this class
91: * with a $types param. Useful to avoid repetition when calling the same
92: * functions using the same fields and types.
93: *
94: * If called with no arguments it will return the currently configured types.
95: *
96: * ### Example
97: *
98: * ```
99: * $query->defaults(['created' => 'datetime', 'is_visible' => 'boolean']);
100: * ```
101: *
102: * This method will replace all the existing type maps with the ones provided.
103: *
104: * @deprecated 3.4.0 Use setDefaults()/getDefaults() instead.
105: * @param array|null $defaults associative array where keys are field names and values
106: * are the correspondent type.
107: * @return $this|array
108: */
109: public function defaults(array $defaults = null)
110: {
111: deprecationWarning(
112: 'TypeMap::defaults() is deprecated. ' .
113: 'Use TypeMap::setDefaults()/getDefaults() instead.'
114: );
115: if ($defaults !== null) {
116: return $this->setDefaults($defaults);
117: }
118:
119: return $this->getDefaults();
120: }
121:
122: /**
123: * Add additional default types into the type map.
124: *
125: * If a key already exists it will not be overwritten.
126: *
127: * @param array $types The additional types to add.
128: * @return void
129: */
130: public function addDefaults(array $types)
131: {
132: $this->_defaults += $types;
133: }
134:
135: /**
136: * Sets a map of fields and their associated types for single-use.
137: *
138: * ### Example
139: *
140: * ```
141: * $query->setTypes(['created' => 'time']);
142: * ```
143: *
144: * This method will replace all the existing type maps with the ones provided.
145: *
146: * @param array $types Associative array where keys are field names and values
147: * are the correspondent type.
148: * @return $this
149: */
150: public function setTypes(array $types)
151: {
152: $this->_types = $types;
153:
154: return $this;
155: }
156:
157: /**
158: * Gets a map of fields and their associated types for single-use.
159: *
160: * @return array
161: */
162: public function getTypes()
163: {
164: return $this->_types;
165: }
166:
167: /**
168: * Sets a map of fields and their associated types for single-use.
169: *
170: * If called with no arguments it will return the currently configured types.
171: *
172: * ### Example
173: *
174: * ```
175: * $query->types(['created' => 'time']);
176: * ```
177: *
178: * This method will replace all the existing type maps with the ones provided.
179: *
180: * @deprecated 3.4.0 Use setTypes()/getTypes() instead.
181: * @param array|null $types associative array where keys are field names and values
182: * are the correspondent type.
183: * @return $this|array
184: */
185: public function types(array $types = null)
186: {
187: deprecationWarning(
188: 'TypeMap::types() is deprecated. ' .
189: 'Use TypeMap::setTypes()/getTypes() instead.'
190: );
191: if ($types !== null) {
192: return $this->setTypes($types);
193: }
194:
195: return $this->getTypes();
196: }
197:
198: /**
199: * Returns the type of the given column. If there is no single use type is configured,
200: * the column type will be looked for inside the default mapping. If neither exist,
201: * null will be returned.
202: *
203: * @param string $column The type for a given column
204: * @return null|string
205: */
206: public function type($column)
207: {
208: if (isset($this->_types[$column])) {
209: return $this->_types[$column];
210: }
211: if (isset($this->_defaults[$column])) {
212: return $this->_defaults[$column];
213: }
214:
215: return null;
216: }
217:
218: /**
219: * Returns an array of all types mapped types
220: *
221: * @return array
222: */
223: public function toArray()
224: {
225: return $this->_types + $this->_defaults;
226: }
227: }
228: