From 7542c4bf3a4761233239d34104edff99abea1550 Mon Sep 17 00:00:00 2001 From: Chris Kankiewicz Date: Fri, 3 Aug 2018 22:52:46 -0700 Subject: [PATCH] Updated README documentation --- README.md | 185 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 139 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 6436888..d044a52 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ And `$prefix` is a string to be used as a key prefix for options of this Config Configuration File Formats -------------------------- -#### PHP +### PHP A PHP configuration file must have the `.php` file extension, be a valid PHP file and and return a valid PHP array. @@ -92,7 +92,7 @@ return [ ``` -#### INI +### INI An INI configuration file must have the `.ini` file extension and be a valid INI file. @@ -113,7 +113,7 @@ mysql[charset] = utf8 mysql[prefix] = ``` -#### JSON +### JSON A JSON configuration file must have the `.json` file extension and contain a valid JSON object. @@ -139,7 +139,7 @@ valid JSON object. ``` -#### TOML +### TOML A TOML configuration file must have the `.toml` file extension and be a valid TOML file. @@ -160,7 +160,7 @@ charset = 'utf8' prefix = '' ``` -#### YAML +### YAML A YAML configuration file must have the `.yaml` file extension, be a valid YAML file. @@ -183,7 +183,7 @@ drivers: prefix: ``` -#### XML +### XML A XML configuration file must have the `.xml` file extension and contain valid XML. @@ -213,17 +213,35 @@ XML. Usage ----- -### `Config::__construct( mixed $context [, string $prefix = null ] )` +### __construct +> Create a new Config object. -Create a new Config object. +```php +Config::__construct( mixed $context [, string $prefix = null ] ) : Config +``` + +| Parameter | Description | +| ---------- | --------------------------------------------------------------------------------------------------------------------------- | +| `$context` | Raw array of configuration options or path to a configuration file or directory containing one or more configuration files | +| `$prefix` | A key under which the loaded config will be nested | + +#### Examples -##### Example +Create a new Config object from a YAML file. ```php -// Create a new Config object from a YAML file $config = new Config('path/to/conifg.yaml'); +``` + +Create a new Config object from a directory of config files. + +```php +$config = new Config('path/to/conifgs/'); +``` -// Create a new Config object from an array +Create a new Config object from an array. + +```php $config = new Config([ 'hostname' => 'localhost', 'port' => 12345 @@ -232,11 +250,19 @@ $config = new Config([ --- -### `Config::set( string $key, mixed $value ) : bool` +### set +> Store a config value with a specified key. + +```php +Config::set( string $key, mixed $value ) : bool +``` -Set a configuration option. +| Parameter | Description | +| --------- | -------------------------------- | +| `$key` | Unique configuration option key | +| `$value` | Config item value | -##### Examples +#### Example ```php $config->set('hostname', 'localhost'); @@ -245,78 +271,141 @@ $config->set('port', 12345); --- -### `Config::get( string $key [, mixed $default = null ] ) : mixed` +### get +> Retrieve a configuration option via a provided key. -Retrieve a configuration option. +```php +Config::get( string $key [, mixed $default = null ] ) : mixed +``` -##### Examples +| Parameter | Description | +| --------- | ------------------------------------------------ | +| `$key` | Unique configuration option key | +| `$value` | Default value to return if option does not exist | + +#### Examples ```php -// Returns null if 'hostname' options is not set +// Return the hostname option value or null if not found. $config->get('hostname'); +``` -// Returns 'localhost' if 'hostname' option is not set +Define a default value to return if the option is not set. + +```php +// Returns 'localhost' if hostname option is not set $config->get('hostname', 'localhost'); ``` --- -### `Config::has( string $key ) : bool` +### has +> Check for the existence of a configuration item. + +```php +Config::has( string $key ) : bool +``` -Check if a configuration option exists. +| Parameter | Description | +| --------- | ------------------------------- | +| `$key` | Unique configuration option key | -##### Example +#### Example ```php -$config->has('hostname'); +$config = new Config([ + 'hostname' => 'localhost' +]); + +$config->has('hostname'); // Returns true +$config->has('port'); // Returns false ``` --- -### `Config::load( string $path [, string $prefix = null [, bool $override = true ]] ) : self` +### load +> Load configuration options from a file or directory. + +```php +Config::load( string $path [, string $prefix = null [, bool $override = true ]] ) : self +``` + +| Parameter | Description | +| ----------- | ---------------------------------------------------------------------------- | +| `$path` | Path to configuration file or directory | +| `$prefix` | A key under which the loaded config will be nested | +| `$override` | Whether or not to override existing options with values from the loaded file | -Load an additional configuration file: -##### Examples +#### Examples + +Load a single additional file. ```php -// Load a single additional file $conifg->load('path/to/config.php'); +``` -// Load an additional file with a prefix +Load an additional file with a prefix. + +```php $config->load('databaes.php', 'database'); +``` -// Load an additional file without overriding exising values +Load an additional file without overriding existing values. + +```php $config->load('additional-options.php', null, false); ``` --- -### `Config::merge( Config $config [, bool $override = true ] ) : self` +### merge +> Merge another Config object into this one. + +```php +Config::merge( Config $config [, bool $override = true ] ) : self +``` + +| Parameter | Description | +| ----------- | ------------------------------------------------------------------------------------- | +| `$config` | Instance of Config | +| `$override` | Whether or not to override existing options with values from the merged config object | + +#### Examples -Merge two Config objects into one. -##### Examples +Merge $anotherConfig into $config and override values in `$config` with values +from `$anotherConfig`. ```php $anotherConfig = new Config('some/config.php'); -// Merge $anotherConfig into $config and override values -// in $config with values from $anotherConfig. $config->merge($anotherConfig); +``` + +Merge `$anotherConfig` into `$config` without overriding any values. Duplicate +values in `$anotherConfig` will be lost. + +```php +$anotherConfig = new Config('some/config.php'); -// Merge $anotherConfig into $config without overriding any -// values. Duplicate values in $anotherConfig will be lost. $config->merge($anotherConfig, false); ``` --- -### `Config::split( string $key ) : Config` +### split +> Split a sub-array of configuration options into it's own Config object. + +```php +Config::split( string $key ) : Config +``` -Split a sub-array of options into it's own Config object. +| Parameter | Description | +| --------- | ------------------------------- | +| `$key` | Unique configuration option key | -##### Example +#### Example ```php $config = new Config([ @@ -326,9 +415,6 @@ $config = new Config([ ], ]); -$config->get('bar'); // Returns ['baz' => 'barbaz'] -$config->get('bar.baz'); // Returns 'barbaz' - $barConfig = $config->split('bar'); $barConfig->get('baz'); // Returns 'barbaz' @@ -336,16 +422,23 @@ $barConfig->get('baz'); // Returns 'barbaz' --- -### `Config::toArray() : array` +### toArray +> Return the entire configuration as an array. -Return the entire configuration as an array. +```php +Config::toArray( void ) : array +``` -##### Example +#### Example ```php -$config->toArray(); +$config = new Config(['foo' => 'foo']); + +$config->toArray(); // Returns ['foo' => 'foo'] ``` +--- + Troubleshooting ---------------