1: <?php
  2: /**
  3:  * This file contains the definition of the factory functions.
  4:  *
  5:  * @author Oleg Schildt
  6:  *
  7:  * @package Factory
  8:  */
  9: 
 10: namespace SmartFactory;
 11: 
 12: use \SmartFactory\DatabaseWorkers\DBWorker;
 13: 
 14: /**
 15:  * The method singleton creates an object that supports the specified interface and ensures
 16:  * that only one instance of this object exists.
 17:  *
 18:  * The singleton is a usual pattern for the action objects like SessionManager, EventManager,
 19:  * DBWorker etc. It makes no sense to produce many instances of such classes,
 20:  * it wastes the computer resources and might cause errors.
 21:  *
 22:  * @param string|object $interface_or_class
 23:  * Name of the class/interface as string or the class/interface.
 24:  *
 25:  * @param string $context
 26:  * The context of binding. You can introduce a different context, and bind another implementation.
 27:  * Then, you can request another instance specifying the context explicitly.
 28:  *
 29:  * @return object
 30:  * Returns object of the class bound to the interfase.
 31:  *
 32:  * @throws \Exception
 33:  * It might throw the following exceptions in the case of any errors:
 34:  *
 35:  * - if the interface or class is not specified.
 36:  * - if the interface or class does not exist.
 37:  * - if the check of the classes and interfaces fails.
 38:  *
 39:  * @see \SmartFactory\instance()
 40:  *
 41:  * @author Oleg Schildt
 42:  */
 43: function singleton(string|object $interface_or_class, string $context = "default"): object
 44: {
 45:     return ObjectFactory::getInstance($interface_or_class, true, $context);
 46: } // singleton
 47: 
 48: /**
 49:  * The method instance creates an object that support the specified interface.
 50:  *
 51:  * By each request, a new object is created. If you request data objects like User,
 52:  * a separate instance must be created for each item.
 53:  *
 54:  * @param string|object $interface_or_class
 55:  * Name of the class/interface as string or the class/interface.
 56:  *
 57:  * @param string $context
 58:  * The context of binding. You can introduce a different context, and bind another implementation.
 59:  * Then, you can request another instance specifying the context explicitly.
 60:  *
 61:  * @return object
 62:  * Returns object of the class bound to the interface.
 63:  *
 64:  * @throws \Exception
 65:  * It might throw the following exceptions in the case of any errors:
 66:  *
 67:  * - if the interface or class is not specified.
 68:  * - if the interface or class does not exist.
 69:  * - if the check of the classes and interfaces fails.
 70:  *
 71:  * @see \SmartFactory\singleton()
 72:  *
 73:  * @author Oleg Schildt
 74:  */
 75: function instance(string|object $interface_or_class, string  $context = "default"): object
 76: {
 77:     return ObjectFactory::getInstance($interface_or_class, false, $context);
 78: } // instance
 79: 
 80: /**
 81:  * The method dbworker provides the DBWorker object for working with the database.
 82:  *
 83:  * Currently supported: MySQL und MS SQL.
 84:  *
 85:  * @param array $parameters
 86:  * Connection settings as an associative array in the form key => value:
 87:  *
 88:  * - $parameters["db_type"] - type of the database (MySQL or MSSQL)
 89:  *
 90:  * - $parameters["db_server"] - server address
 91:  *
 92:  * - $parameters["db_name"] - database name
 93:  *
 94:  * - $parameters["db_user"] - user name
 95:  *
 96:  * - $parameters["db_password"] - user password
 97:  *
 98:  * - $parameters["autoconnect"] - should true if the connection should be established automatically
 99:  *                 upon creation.
100:  *
101:  * - $parameters["read_only"] - this paramter sets the connection to the read only mode.
102:  *
103:  * Example:
104:  * ```php
105:  * $dbw = dbworker(["db_type" => "MySQL",
106:  *                  "db_server" => "localhost",
107:  *                  "db_name" => "framework_demo",
108:  *                  "db_user" => "root",
109:  *                  "db_password" => "root",
110:  *                  "autoconnect" => true
111:  *                 ]);
112:  * ```
113:  *
114:  * @param bool $singleton
115:  * If the parameter is true, it ensures that only one instance of this object exists.
116:  *
117:  * @return ?DatabaseWorkers\DBWorker
118:  * returns DBWorker object or null if the object could not be created.
119:  *
120:  * @throws \Exception
121:  * It might throw the following exceptions in the case of any errors.
122:  *
123:  * @author Oleg Schildt
124:  */
125: function dbworker(array $parameters = [], bool $singleton = true) : ?DatabaseWorkers\DBWorker
126: {
127:     if (empty($parameters["db_type"])) {
128:         throw new \Exception("Database type is not specified!");
129:     }
130: 
131:     $class_name = "SmartFactory\\DatabaseWorkers\\" . $parameters["db_type"] . "_DBWorker";
132: 
133:     $dbworker = ObjectFactory::getInstance($class_name, $singleton);
134: 
135:     if (!$dbworker->is_extension_installed()) {
136:         throw new \Exception(sprintf("PHP extension '%s' is not installed or is too old. Work with the database '%s' is not possible!", $dbworker->get_extension_name(), $dbworker->get_rdbms_name()));
137:     }
138: 
139:     // instance already connected
140:     if ($dbworker->is_connected()) {
141:         return $dbworker;
142:     }
143: 
144:     $dbworker->init($parameters);
145: 
146:     // do not connect, only object required
147:     // user will do connect by itself
148:     if (empty($parameters["autoconnect"])) {
149:         return $dbworker;
150:     }
151: 
152:     $dbworker->connect();
153: 
154:     return $dbworker;
155: } // dbworker