1: <?php
 2: /**
 3:  * This file contains the declaration of the interface IShardManager for managing connections to the DB shards.
 4:  *
 5:  * @package Database
 6:  *
 7:  * @author Oleg Schildt
 8:  */
 9: 
10: namespace SmartFactory\Interfaces;
11: 
12: /**
13:  * Interface for managing connections to the DB shards.
14:  *
15:  * @author Oleg Schildt
16:  */
17: interface IShardManager
18: {
19:     /**
20:      * Registers a new shard.
21:      *
22:      * @param string $shard_name
23:      * Unique shard name.
24:      *
25:      * @param array $parameters
26:      * The connection parameters to the shard as an associative array in the form key => value:
27:      *
28:      * - $parameters["db_type"] - type of the database (MySQL or MSSQL)
29:      *
30:      * - $parameters["db_server"] - server address
31:      *
32:      * - $parameters["db_name"] - database name
33:      *
34:      * - $parameters["db_user"] - user name
35:      *
36:      * - $parameters["db_password"] - user password
37:      *
38:      * - $parameters["autoconnect"] - should true if the connection should be established automatically
39:      *                 upon creation.
40:      *
41:      * - $parameters["read_only"] - this parameter sets the connection to the read only mode.
42:      *
43:      * @param string $load_balancing_group
44:      * The name of the load balancing group, if the shard should be part of it.
45:      *
46:      * @return bool
47:      * It should return true if the registering was successful, otherwise false.
48:      *
49:      * @throws \Exception
50:      * It might throw an exception in the case of any errors.
51:      *
52:      * @author Oleg Schildt
53:      */
54:     public function registerShard(string $shard_name, array $parameters, string $load_balancing_group = ""): bool;
55:     
56:     /**
57:      * The method provides the DBWorker object for working with the shard.
58:      *
59:      * If the parameters are omitted, the system takes the parameters from the configuration
60:      * settings and reuses the single instance of the DBWorker for all requests.
61:      * If the user passes the parameters explicitly, a new instance of the DBWorker is created upon each new request.
62:      *
63:      * Currently supported: MySQL und MS SQL.
64:      *
65:      * @param string $shard_name
66:      * The name of the shard.
67:      *
68:      * @return ?\SmartFactory\DatabaseWorkers\DBWorker
69:      * returns DBWorker object or null if the object could not be created.
70:      *
71:      * @throws \Exception
72:      * It might throw an exception in the case of any errors.
73:      *
74:      * @author Oleg Schildt
75:      */
76:     public function dbshard(string $shard_name): ?\SmartFactory\DatabaseWorkers\DBWorker;
77:     
78:     /**
79:      * The method provides the DBWorker object for working with the shard, that is chosen randomly
80:      * for load balancing reason.
81:      *
82:      * @param string $load_balancing_group
83:      * The name of the load balancing group, from which the shard should be randomly picked.
84:      *
85:      * @return ?\SmartFactory\DatabaseWorkers\DBWorker
86:      * returns DBWorker object or null if the object could not be created.
87:      *
88:      * @throws \Exception
89:      * It might throw an exception in the case of any errors.
90:      *
91:      * @author Oleg Schildt
92:      */
93:     public function randomDBShard(string $load_balancing_group): ?\SmartFactory\DatabaseWorkers\DBWorker;
94: } // IShardManager