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