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\ORM;
 16: 
 17: use Cake\ORM\Locator\LocatorInterface;
 18: 
 19: /**
 20:  * Provides a registry/factory for Table objects.
 21:  *
 22:  * This registry allows you to centralize the configuration for tables
 23:  * their connections and other meta-data.
 24:  *
 25:  * ### Configuring instances
 26:  *
 27:  * You may need to configure your table objects. Using the `TableLocator` you can
 28:  * centralize configuration. Any configuration set before instances are created
 29:  * will be used when creating instances. If you modify configuration after
 30:  * an instance is made, the instances *will not* be updated.
 31:  *
 32:  * ```
 33:  * TableRegistry::getTableLocator()->setConfig('Users', ['table' => 'my_users']);
 34:  *
 35:  * // Prior to 3.6.0
 36:  * TableRegistry::config('Users', ['table' => 'my_users']);
 37:  * ```
 38:  *
 39:  * Configuration data is stored *per alias* if you use the same table with
 40:  * multiple aliases you will need to set configuration multiple times.
 41:  *
 42:  * ### Getting instances
 43:  *
 44:  * You can fetch instances out of the registry through `TableLocator::get()`.
 45:  * One instance is stored per alias. Once an alias is populated the same
 46:  * instance will always be returned. This reduces the ORM memory cost and
 47:  * helps make cyclic references easier to solve.
 48:  *
 49:  * ```
 50:  * $table = TableRegistry::getTableLocator()->get('Users', $config);
 51:  *
 52:  * // Prior to 3.6.0
 53:  * $table = TableRegistry::get('Users', $config);
 54:  * ```
 55:  */
 56: class TableRegistry
 57: {
 58:     /**
 59:      * LocatorInterface implementation instance.
 60:      *
 61:      * @var \Cake\ORM\Locator\LocatorInterface
 62:      */
 63:     protected static $_locator;
 64: 
 65:     /**
 66:      * Default LocatorInterface implementation class.
 67:      *
 68:      * @var string
 69:      */
 70:     protected static $_defaultLocatorClass = 'Cake\ORM\Locator\TableLocator';
 71: 
 72:     /**
 73:      * Sets and returns a singleton instance of LocatorInterface implementation.
 74:      *
 75:      * @param \Cake\ORM\Locator\LocatorInterface|null $locator Instance of a locator to use.
 76:      * @return \Cake\ORM\Locator\LocatorInterface
 77:      * @deprecated 3.5.0 Use getTableLocator()/setTableLocator() instead.
 78:      */
 79:     public static function locator(LocatorInterface $locator = null)
 80:     {
 81:         deprecationWarning(
 82:             'TableRegistry::locator() is deprecated. ' .
 83:             'Use setTableLocator()/getTableLocator() instead.'
 84:         );
 85:         if ($locator) {
 86:             static::setTableLocator($locator);
 87:         }
 88: 
 89:         return static::getTableLocator();
 90:     }
 91: 
 92:     /**
 93:      * Returns a singleton instance of LocatorInterface implementation.
 94:      *
 95:      * @return \Cake\ORM\Locator\LocatorInterface
 96:      */
 97:     public static function getTableLocator()
 98:     {
 99:         if (!static::$_locator) {
100:             static::$_locator = new static::$_defaultLocatorClass();
101:         }
102: 
103:         return static::$_locator;
104:     }
105: 
106:     /**
107:      * Sets singleton instance of LocatorInterface implementation.
108:      *
109:      * @param \Cake\ORM\Locator\LocatorInterface $tableLocator Instance of a locator to use.
110:      * @return void
111:      */
112:     public static function setTableLocator(LocatorInterface $tableLocator)
113:     {
114:         static::$_locator = $tableLocator;
115:     }
116: 
117:     /**
118:      * Stores a list of options to be used when instantiating an object
119:      * with a matching alias.
120:      *
121:      * @param string|null $alias Name of the alias
122:      * @param array|null $options list of options for the alias
123:      * @return array The config data.
124:      * @deprecated 3.6.0 Use \Cake\ORM\Locator\TableLocator::getConfig()/setConfig() instead.
125:      */
126:     public static function config($alias = null, $options = null)
127:     {
128:         deprecationWarning(
129:             'TableRegistry::config() is deprecated. ' .
130:             'Use \Cake\ORM\Locator\TableLocator::getConfig()/setConfig() instead.'
131:         );
132: 
133:         return static::getTableLocator()->config($alias, $options);
134:     }
135: 
136:     /**
137:      * Get a table instance from the registry.
138:      *
139:      * See options specification in {@link TableLocator::get()}.
140:      *
141:      * @param string $alias The alias name you want to get.
142:      * @param array $options The options you want to build the table with.
143:      * @return \Cake\ORM\Table
144:      * @deprecated 3.6.0 Use \Cake\ORM\Locator\TableLocator::get() instead.
145:      */
146:     public static function get($alias, array $options = [])
147:     {
148:         return static::getTableLocator()->get($alias, $options);
149:     }
150: 
151:     /**
152:      * Check to see if an instance exists in the registry.
153:      *
154:      * @param string $alias The alias to check for.
155:      * @return bool
156:      * @deprecated 3.6.0 Use \Cake\ORM\Locator\TableLocator::exists() instead.
157:      */
158:     public static function exists($alias)
159:     {
160:         return static::getTableLocator()->exists($alias);
161:     }
162: 
163:     /**
164:      * Set an instance.
165:      *
166:      * @param string $alias The alias to set.
167:      * @param \Cake\ORM\Table $object The table to set.
168:      * @return \Cake\ORM\Table
169:      * @deprecated 3.6.0 Use \Cake\ORM\Locator\TableLocator::set() instead.
170:      */
171:     public static function set($alias, Table $object)
172:     {
173:         return static::getTableLocator()->set($alias, $object);
174:     }
175: 
176:     /**
177:      * Removes an instance from the registry.
178:      *
179:      * @param string $alias The alias to remove.
180:      * @return void
181:      * @deprecated 3.6.0 Use \Cake\ORM\Locator\TableLocator::remove() instead.
182:      */
183:     public static function remove($alias)
184:     {
185:         static::getTableLocator()->remove($alias);
186:     }
187: 
188:     /**
189:      * Clears the registry of configuration and instances.
190:      *
191:      * @return void
192:      * @deprecated 3.6.0 Use \Cake\ORM\Locator\TableLocator::clear() instead.
193:      */
194:     public static function clear()
195:     {
196:         static::getTableLocator()->clear();
197:     }
198: 
199:     /**
200:      * Proxy for static calls on a locator.
201:      *
202:      * @param string $name Method name.
203:      * @param array $arguments Method arguments.
204:      * @return mixed
205:      */
206:     public static function __callStatic($name, $arguments)
207:     {
208:         deprecationWarning(
209:             'TableRegistry::' . $name . '() is deprecated. ' .
210:             'Use \Cake\ORM\Locator\TableLocator::' . $name . '() instead.'
211:         );
212: 
213:         return static::getTableLocator()->$name(...$arguments);
214:     }
215: }
216: