Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/phlak/config
PHP library for simple configuration management
https://github.com/phlak/config
config config-management ini json php php-library xml yaml
Last synced: 4 days ago
JSON representation
PHP library for simple configuration management
- Host: GitHub
- URL: https://github.com/phlak/config
- Owner: PHLAK
- License: mit
- Created: 2016-08-20T21:09:30.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-01-01T19:24:32.000Z (about 1 year ago)
- Last Synced: 2025-01-08T22:24:12.403Z (12 days ago)
- Topics: config, config-management, ini, json, php, php-library, xml, yaml
- Language: PHP
- Homepage: https://packagist.org/packages/phlak/config
- Size: 254 KB
- Stars: 51
- Watchers: 6
- Forks: 11
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
PHP library for simple configuration management
-- Created by Chris Kankiewicz
(@PHLAK)
---
Introduction
------------
Config is a simple PHP configuration management library supporting multiple
configuration file formats and an expressive API.
Supported file formats:
- PHP
- INI
- JSON
- [TOML](https://github.com/toml-lang/toml)
- YAML
- XML
Requirements
------------
- [PHP](https://php.net) >= 7.1
Install with Composer
---------------------
```bash
composer require phlak/config
```
Initializing the Client
-----------------------
First, import Config:
```php
use PHLAK\Config\Config;
```
Then instantiate the class:
```php
$config = new Config($context, $prefix = null);
```
Where `$context` is one of the following:
- A path to a supported file type
- A directory path containing one or more supported file types
- An array of configuration options
And `$prefix` is a string to be used as a key prefix for options of this Config object.
Configuration File Formats
--------------------------
### PHP
A PHP configuration file must have the `.php` file extension, be a valid PHP
file and and return a valid PHP array.
Example PHP file
```php
'mysql',
'drivers' => [
'sqlite' => [
'database' => 'database.sqlite',
'prefix' => ''
],
'mysql' => [
'host' => 'localhost',
'database' => 'blog',
'username' => 'blogger',
'password' => 'hunter2',
'charset' => 'utf8',
'prefix' => ''
]
]
];
```
### INI
An INI configuration file must have the `.ini` file extension and be a valid INI
file.
Example INI file
```ini
driver = mysql
[drivers]
sqlite[database] = database.sqlite
sqlite[prefix] =
mysql[host] = localhost
mysql[database] = blog
mysql[username] = blogger
mysql[password] = hunter2
mysql[charset] = utf8
mysql[prefix] =
```
### JSON
A JSON configuration file must have the `.json` file extension and contain a
valid JSON object.
Example JSON file
```json
{
"driver": "mysql",
"drivers": {
"sqlite": {
"database": "database.sqlite",
"prefix": ""
},
"mysql": {
"host": "localhost",
"database": "blog",
"username": "blogger",
"password": "hunter2",
"charset": "utf8",
"prefix": ""
}
}
}
```
### TOML
A TOML configuration file must have the `.toml` file extension and be a valid
TOML file.
Example TOML file
```toml
driver = 'mysql'
[drivers.sqlite]
database = 'database.sqlite'
prefix = ''
[drivers.mysql]
host = 'localhost'
database = 'blog'
username = 'blogger'
password = 'hunter2'
charset = 'utf8'
prefix = ''
```
### YAML
A YAML configuration file must have the `.yaml` file extension, be a valid YAML
file.
Example YAML file
```yaml
driver: mysql
drivers:
sqlite:
database: database.sqlite
prefix:
mysql:
host: localhost
database: blog
username: blogger
password: hunter2
charset: utf8
prefix:
```
### XML
A XML configuration file must have the `.xml` file extension and contain valid
XML.
Example XML file
```xml
mysql
database.sqlite
localhost
blog
blogger
hunter2
utf8
```
Usage
-----
### __construct
> Create a new Config object.
```php
Config::__construct( mixed $context [, string $prefix = null ] ) : Config
```
$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
Create a new Config object from a YAML file.
```php
$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.
```php
$config = new Config([
'hostname' => 'localhost',
'port' => 12345
]);
```
---
### set
> Store a config value with a specified key.
```php
Config::set( string $key, mixed $value ) : bool
```
$key- Unique configuration option key
$value- Config item value
#### Example
```php
$config->set('hostname', 'localhost');
$config->set('port', 12345);
```
---
### get
> Retrieve a configuration option via a provided key.
```php
Config::get( string $key [, mixed $default = null ] ) : mixed
```
$key- Unique configuration option key
$value- Config item value
#### Examples
```php
// Return the hostname option value or null if not found.
$config->get('hostname');
```
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');
```
---
### has
> Check for the existence of a configuration item.
```php
Config::has( string $key ) : bool
```
$key- Unique configuration option key
#### Example
```php
$config = new Config([
'hostname' => 'localhost'
]);
$config->has('hostname'); // Returns true
$config->has('port'); // Returns false
```
---
### append
> Append a value onto an existing array configuration option.
```php
Config::append( string $key, mixed $value ) : bool
```
$key- Unique configuration option key
$value- Config item value
#### Example
Append `baz` to the `tags` config item array.
```php
$config->set('tags', ['foo', 'bar'])
$config->append('tags', 'baz'); // ['foo', 'bar', 'baz']
```
---
### prepend
> Prepend a value onto an existing array configuration option.
```php
Config::append( string $key, mixed $value ) : bool
```
$key- Unique configuration option key
$value- Config item value
#### Example
Prepend `baz` to the `tags` config item array.
```php
$config->set('tags', ['foo', 'bar'])
$config->append('tags', 'baz'); // ['baz', 'foo', 'bar']
```
---
### unset
> Unset a configuration option via a provided key.
```php
Config::unset( string $key ) : bool
```
$key- Unique configuration option key
#### Example
```php
$config->unset('hostname');
```
---
### load
> Load configuration options from a file or directory.
```php
Config::load( string $path [, string $prefix = null [, bool $override = true ]] ) : self
```
$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
#### Examples
Load a single additional file.
```php
$conifg->load('path/to/config.php');
```
Load an additional file with a prefix.
```php
$config->load('databaes.php', 'database');
```
Load an additional file without overriding existing values.
```php
$config->load('additional-options.php', null, false);
```
---
### merge
> Merge another Config object into this one.
```php
Config::merge( Config $config [, bool $override = true ] ) : self
```
$config- Instance of Config
$override- Whether or not to override existing options with values from the merged config object
#### Examples
Merge $anotherConfig into $config and override values in `$config` with values
from `$anotherConfig`.
```php
$anotherConfig = new Config('some/config.php');
$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');
$config->merge($anotherConfig, false);
```
---
### split
> Split a sub-array of configuration options into it's own Config object.
```php
Config::split( string $key ) : Config
```
$key- Unique configuration option key
#### Example
```php
$config = new Config([
'foo' => 'foo',
'bar' => [
'baz' => 'barbaz'
],
]);
$barConfig = $config->split('bar');
$barConfig->get('baz'); // Returns 'barbaz'
```
---
### toArray
> Return the entire configuration as an array.
```php
Config::toArray( void ) : array
```
#### Example
```php
$config = new Config(['foo' => 'foo']);
$config->toArray(); // Returns ['foo' => 'foo']
```
---
Troubleshooting
---------------
For general help and support join our [GitHub Discussion](https://github.com/PHLAK/Config/discussions) or reach out on [Twitter](https://twitter.com/PHLAK).
Please report bugs to the [GitHub Issue Tracker](https://github.com/PHLAK/Config/issues).
Copyright
---------
This project is liscensed under the [MIT License](https://github.com/PHLAK/Config/blob/master/LICENSE).