1: 2: 3: 4: 5: 6: 7: 8: 9: 10: 11: 12: 13: 14: 15: 16: 17: 18: 19: 20: 21: 22: 23: 24: 25: 26: 27: 28: 29: 30: 31: 32: 33: 34: 35: 36: 37: 38: 39: 40: 41: 42: 43: 44: 45: 46: 47: 48: 49: 50: 51: 52: 53: 54: 55: 56: 57: 58: 59: 60: 61: 62: 63: 64: 65: 66: 67: 68: 69: 70: 71: 72: 73: 74: 75: 76: 77: 78: 79: 80: 81: 82: 83: 84: 85: 86: 87: 88: 89: 90: 91: 92: 93: 94: 95: 96: 97: 98: 99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: <?php
/**
* MvcCore
*
* This source file is subject to the BSD 3 License
* For the full copyright and license information, please view
* the LICENSE.md file that are distributed with this source code.
*
* @copyright Copyright (c) 2016 Tom Flidr (https://github.com/mvccore)
* @license https://mvccore.github.io/docs/mvccore/5.0.0/LICENCE.md
*/
namespace MvcCore;
/**
* Responsibility - static methods for connections, configuration
* and for active record properties manipulation.
* - Database `\PDO` connecting by config settings.
* - Reading `db` section configuration(s) from system `config.ini` file.
* - Resource class with SQL queries localization, instancing and caching.
* - Data methods for manipulating properties based on active record pattern.
* - Meta data about properties parsing and caching.
* - Magic methods handling.
*/
interface IModel extends \MvcCore\Model\IConstants {
/**
* Returns (or creates if necessary) model resource instance.
* @param array|NULL $args Values array with variables to pass into resource `__construct()` method.
* @param string $resourceClassPath Automatically initialized with string replaced with `%SELF%` by `static::class` (or by `get_called_class()`).
* @return \MvcCore\Model
*/
public static function GetResource ($args = [], $resourceClassPath = '%SELF%s\Resource');
/**
* Return system configuration file database section properties names.
* @return \stdClass
*/
public static function GetSysConfigProperties ();
/**
* Returns `\PDO` database connection by connection name/index,
* usually by system config values (cached by local store)
* or create new connection if no connection cached.
* @param string|int|array|\stdClass|NULL $connectionNameOrConfig
* @param bool $strict If `TRUE` and no connection under given name or given
* index found, exception is thrown. `TRUE` by default.
* If `FALSE`, there could be returned connection by
* first available configuration.
* @throws \InvalidArgumentException
* @return \PDO
*/
public static function GetConnection ($connectionNameOrConfig = NULL, $strict = TRUE);
/**
* Get all known database connection config records as indexed/named array with `\stdClass` objects.
* Keys in array are connection config names/indexes and `\stdClass` values are config values.
* @return \stdClass[]
*/
public static function & GetConfigs ();
/**
* Set all known configuration at once, optionally set default connection name/index.
* Example:
* `\MvcCore\Model::SetConfigs([
* // connection name: 'mysql-cdcol':
* 'mysql-cdcol' => [
* 'driver' => 'mysql', 'host' => 'localhost',
* 'user' => 'root', 'password' => '1234', 'database' => 'cdcol',
* ],
* // connection name: 'mssql-tests':
* 'mssql-tests' => [
* 'driver' => 'sqlsrv', 'host' => '.\SQLEXPRESS',
* 'user' => 'sa', 'password' => '1234', 'database' => 'tests',
* ]
* ]);`
* or:
* `\MvcCore\Model::SetConfigs([
* // connection index: 0:
* [
* 'driver' => 'mysql', 'host' => 'localhost',
* 'user' => 'root', 'password' => '1234', 'database' => 'cdcol',
* ],
* // connection index: 1:
* [
* 'driver' => 'sqlsrv', 'host' => '.\SQLEXPRESS',
* 'user' => 'sa', 'password' => '1234', 'database' => 'tests',
* ]
* ]);`
* @param \stdClass[]|array[] $configs Configuration array with `\stdClass` objects or arrays with configuration data.
* @param string|int $defaultConnectionName
* @return bool
*/
public static function SetConfigs (array $configs = []);
/**
* Returns database connection config by connection index (integer)
* or by connection name (string) as `\stdClass` (cached by local store).
* @param int|string|NULL $connectionName
* @return \stdClass
*/
public static function & GetConfig ($connectionName = NULL);
/**
* Set configuration array with optional connection name/index.
* If there is array key `name` or `index` inside config `array` or `\stdClass`,
* it's value is used for connection name or index or there is no param `$connectionName` defined.
* Example:
* `\MvcCore\Model::SetConfig(array(
* 'name' => 'mysql-cdcol',
* 'driver' => 'mysql', 'host' => 'localhost',
* 'user' => 'root', 'password' => '1234', 'database' => 'cdcol',
* ));`
* or:
* `\MvcCore\Model::SetConfig(array(
* 'index' => 0,
* 'driver' => 'mysql', 'host' => 'localhost',
* 'user' => 'root', 'password' => '1234', 'database' => 'cdcol',
* ));`
* or:
* `\MvcCore\Model::SetConfig(array(
* 'driver' => 'mysql', 'host' => 'localhost',
* 'user' => 'root', 'password' => '1234', 'database' => 'cdcol',
* ), 'mysql-cdcol');`
* or:
* `\MvcCore\Model::SetConfig(array(
* 'driver' => 'mysql', 'host' => 'localhost',
* 'user' => 'root', 'password' => '1234', 'database' => 'cdcol',
* ), 0);`
* @param \stdClass[]|array[] $config
* @param string|int|NULL $connectionName
* @return string|int
*/
public static function SetConfig (array $config = [], $connectionName = NULL);
/**
* Collect all model class properties values into array.
* Result keys could be converted by any conversion flag.
* @param int $propsFlags All properties flags are available except flags:
* - `\MvcCore\IModel::PROPS_INITIAL_VALUES`,
* - `\MvcCore\IModel::PROPS_CONVERT_CASE_INSENSITIVE`,
* - `\MvcCore\IModel::PROPS_NAMES_BY_*`.
* @param bool $getNullValues If `TRUE`, include also values with `NULL`s,
* `FALSE` by default.
* @throws \InvalidArgumentException
* @return array
*/
public function GetValues ($propsFlags = 0, $getNullValues = FALSE);
/**
* Set up given `$data` items into `$this` instance context
* as typed properties by PHP types (or by PhpDocs comments in PHP < 7.4)
* as properties with the same names as `$data` array keys or converted
* by properties flags. Case sensitivelly by default.
* Any `$data` items, which are not declared in `$this` context are
* initialized by `__set()` method.
* @param array $data Raw data from database (row) or from form fields.
* @param int $propsFlags All properties flags are available.
* @throws \InvalidArgumentException
* @return \MvcCore\Model Current `$this` context.
*/
public function SetValues ($data = [], $propsFlags = 0);
/**
* Get touched properties from `$this` context.
* Touched properties are properties with different value than value under
* property name key in `$this->initialValues` (initial array is optionally
* completed in `SetValues()` method). Result keys could be converted by any
* conversion flag.
* @param int $propsFlags All properties flags are available except flags:
* - `\MvcCore\IModel::PROPS_INITIAL_VALUES`,
* - `\MvcCore\IModel::PROPS_CONVERT_CASE_INSENSITIVE`.
* @throws \InvalidArgumentException
* @return array
*/
public function GetTouched ($propsFlags = 0);
/**
* Sets any custom property `"PropertyName"` by `\MvcCore\Model::SetPropertyName("value")`,
* which is not necessary to define previously or gets previously defined
* property `"PropertyName"` by `\MvcCore\Model::GetPropertyName();`.
* Throws exception if no property defined by get call
* or if virtual call begins with anything different from `Set` or `Get`.
* This method returns custom value for get and `\MvcCore\Model` instance for set.
* @param string $rawName
* @param array $arguments
* @throws \InvalidArgumentException If `strtolower($rawName)` doesn't begin with `"get"` or with `"set"`.
* @return mixed|\MvcCore\Model
*/
public function __call ($rawName, $arguments = []);
/**
* Set any custom property, not necessary to previously defined.
* @param string $name
* @param mixed $value
* @throws \InvalidArgumentException If name is `initialValues` or any custom name in extended class.
* @return bool
*/
public function __set ($name, $value);
/**
* Get any custom property, not necessary to previously defined,
* if property is not defined, NULL is returned.
* @param string $name
* @throws \InvalidArgumentException If name is `initialValues` or any custom name in extended class.
* @return mixed
*/
public function __get ($name);
/**
* Collect all properties names to serialize them by `serialize()` method.
* Collect all instance properties declared as private, protected and public
* and if there is configured in `static::$protectedProperties` anything as
* `TRUE` (under key by property name), also return those properties in
* result array.
* @return \string[]
*/
public function __sleep ();
}