|
| 1 | +## Basic Configuration |
| 2 | + |
| 3 | +### Static call on Win32Model class |
| 4 | +``` php |
| 5 | +$connection = Connection::simple('computer-one', 'admin', 'password'); |
| 6 | + |
| 7 | +// Returns an instance of Query\Builder |
| 8 | +$builder = LoggedOnUser::query($connection); |
| 9 | + |
| 10 | +// Returns a ModelCollection of Models\LoggedOnUsers |
| 11 | +$loggedOnUsers = $builder->get(); |
| 12 | +``` |
| 13 | + |
| 14 | +A connection defined in this way will not be stored in the `Config` container. This is useful when you need to reference |
| 15 | +many connections in an array to poll many computers across your network. |
| 16 | + |
| 17 | +``` php |
| 18 | +$username = 'admin'; |
| 19 | +$password = 'password'; |
| 20 | +$computers = ['computer_one', 'computer_two']; |
| 21 | + |
| 22 | +$results = []; |
| 23 | + |
| 24 | +foreach ($computers as $computer) { |
| 25 | + // $results becomes an array of ModelCollections |
| 26 | + $results[] = LoggedOnUser::query(Connection::simple($computer, $user $password)); |
| 27 | +} |
| 28 | +``` |
| 29 | + |
| 30 | +### Instance of Scripting |
| 31 | +``` php |
| 32 | +$scripting = new Scripting(Connection::simple('computer-one', 'admin', 'password)); |
| 33 | + |
| 34 | +// Returns and instance of Query\Builder (same as above) |
| 35 | +$builder = $scripting->query()->loggedOnUser(); |
| 36 | +``` |
| 37 | + |
| 38 | +This will set the given connection as the default connection. All models queried without a given connection will use |
| 39 | +this connection. |
| 40 | + |
| 41 | +``` php |
| 42 | +$scripting = new Scripting; |
| 43 | +$scripting->addConnection( |
| 44 | + 'computer-one', |
| 45 | + Connection::simple('computer-one', 'admin', 'password) |
| 46 | +); |
| 47 | + |
| 48 | +$builder = $scripting->query('computer-one)->loggedOnUser(); |
| 49 | + |
| 50 | +// This connection is also available to the Models |
| 51 | +$builder = LoggedOnUser::query('computer-one'); |
| 52 | +``` |
| 53 | + |
| 54 | +Adding a connection in this way will store the connection for later and repeated use. |
| 55 | + |
| 56 | +### No Configuration |
| 57 | +``` php |
| 58 | +// Returns a ModelCollection of LoggedOnUser models from the local machine |
| 59 | +$local = LoggedOnUser::query()->get(); |
| 60 | + |
| 61 | +$scripting = new Scripting; |
| 62 | +// Same as above |
| 63 | +$local = $scripting->query()->loggedOnUser()->get(); |
| 64 | +``` |
| 65 | + |
| 66 | +If no configuration is provided then the library's default connection is localhost. |
| 67 | + |
| 68 | +::: danger |
| 69 | +`Scripting` should only be instantiated once. If it is instantiated more than once then the last configuration options |
| 70 | +will be used. |
| 71 | +::: |
| 72 | + |
| 73 | +## The Configuration Instance |
| 74 | + |
| 75 | +The configuration instance, `Config`, is the core of this library. Upon instantiation of, either a model or `Scripting`, |
| 76 | +an instance of `Config` gets created. |
| 77 | + |
| 78 | +`Config` uses a singleton-like pattern to make querying on a model directly possible. |
| 79 | +Due to the usage of this pattern you typically would not `new` the `Config` object directly. However, if you feel |
| 80 | +you need to access the `Config` directly you should do so using the `::instance()` static method. |
| 81 | + |
| 82 | +### Defaults |
| 83 | + |
| 84 | +The only default that is currently expected to be used is the default `Connection`. This is set to the local machine |
| 85 | +that `PHP` is running on. |
| 86 | + |
| 87 | +``` php |
| 88 | +# config/connections.php |
| 89 | + |
| 90 | +return [ |
| 91 | + 'default' => 'local', |
| 92 | + |
| 93 | + 'servers' => [ |
| 94 | + 'local' => [ |
| 95 | + 'server' => '.', |
| 96 | + 'namespace' => 'Root\CIMv2', |
| 97 | + 'user' => null, |
| 98 | + 'password' => null, |
| 99 | + 'locale' => null, |
| 100 | + 'authority' => null, |
| 101 | + 'security_flags' => null, |
| 102 | + ], |
| 103 | + ], |
| 104 | +]; |
| 105 | +``` |
| 106 | + |
| 107 | +If you would like to define a list of connections from a file or array you should construct the array and |
| 108 | +instantiate `Config` as follows: |
| 109 | + |
| 110 | +``` php |
| 111 | +$connections = [ |
| 112 | + 'wmi' => [ |
| 113 | + 'connections' => [ |
| 114 | + 'default' => 'computer-two', |
| 115 | + |
| 116 | + 'servers' => [ |
| 117 | + 'computer-one' => [ |
| 118 | + 'server' => 'computer1', |
| 119 | + 'user' => 'admin', |
| 120 | + 'password' => 'password', |
| 121 | + ], |
| 122 | + |
| 123 | + 'computer-two' => [ |
| 124 | + 'server' => 'computer2', |
| 125 | + 'user' => 'admin', |
| 126 | + 'password' => 'password', |
| 127 | + ], |
| 128 | + ] |
| 129 | + ] |
| 130 | + ] |
| 131 | +]; |
| 132 | + |
| 133 | +Config::instance($connections); |
| 134 | +// or |
| 135 | +new Config($connections); |
| 136 | +``` |
| 137 | + |
| 138 | +Either method above will instantiate the `Config` object to be used later. Again, be sure to do this prior to any |
| 139 | +calls to assure predictable behavior. If you use `Config::instance($connections)` the new connections will simply be |
| 140 | +merged in to an already started instance. |
| 141 | + |
| 142 | +Accessing the configuration object in the following way keeps you from trampling over the current configuration and |
| 143 | +allows you to make global changes. |
| 144 | + |
| 145 | +``` php |
| 146 | +// This is how the library accesses the Config object. |
| 147 | +$config = Config::instance(); |
| 148 | +``` |
| 149 | + |
| 150 | +### Config Methods |
| 151 | + |
| 152 | +While not all of the `Config` methods are outlined here below are the ones that may be most useful to you. |
| 153 | + |
| 154 | +#### `Config::instance(array $items = [], Resolver $resolver = null)` |
| 155 | + |
| 156 | +If called without any arguments this will either return the currently instantiated instance or return a new instance |
| 157 | +with default setting. |
| 158 | + |
| 159 | +If called with the `$items` array set this will merge the given configuration into the currently existing configuration. |
| 160 | + |
| 161 | +If called with `$resolver` set then it will replace the current `Resolver` instance with the one given. You shouldn't |
| 162 | +need to override this, but it could be useful when testing. |
| 163 | + |
| 164 | +#### `Config::newInstance(array $items = [], Resolver $resolver = null)` |
| 165 | + |
| 166 | +Operates the same as above with the exception that this will always return a brand new instance. This is also useful |
| 167 | +when testing to assure that previously set configuration options do not leak into other tests. |
| 168 | + |
| 169 | +```php |
| 170 | +class FeatureTest extends TestCase |
| 171 | +{ |
| 172 | + /** @var Config */ |
| 173 | + protected $config; |
| 174 | + |
| 175 | + protected function setUp(): void |
| 176 | + { |
| 177 | + $this->config = Config::newInstance(); |
| 178 | + } |
| 179 | +} |
| 180 | +``` |
| 181 | + |
| 182 | +#### `$config->getConnection(string $name = null)` |
| 183 | + |
| 184 | +Returns a connection from the `Config` container by name. If `$name` is not provided or set to `'default`` then it will |
| 185 | +return the default connection. |
| 186 | + |
| 187 | +If a connection is not found it will simply return `null`. |
| 188 | + |
| 189 | +#### `$config->addConnection(string $name, Connection $connection)` |
| 190 | + |
| 191 | +Add a connection to the `Config` instance. |
| 192 | + |
| 193 | +#### `$config->setDefaultConnection(string $name)` |
| 194 | + |
| 195 | +This will set the default connection by its name. If the connection name does not exist then it will throw an |
| 196 | +`InvalidConnectionException`. |
| 197 | + |
| 198 | +#### `$config->getDefaultConnection()` |
| 199 | + |
| 200 | +Returns the currently set default connection. |
| 201 | + |
| 202 | +#### `$config->getDefaultConnectionName()` |
| 203 | + |
| 204 | +Returns the currently set default connection name. |
0 commit comments