README

File Config

This package provides a persistent config store as flat files with an easy to use and understand API. This is perfect if the config file should be stored in userland, or somewhere the user is allowed to edit it manually.

Installation

You'll have to follow a couple of simple steps to install this package.

Downloading

Via composer:

$ composer require sven/file-config:^3.1

Or add the package to your dependencies in composer.json and run composer update sven/file-config on the command line to download the package:

{
    "require": {
        "sven/file-config": "^3.1"
    }
}

Available drivers

Json - For .json files.
DotEnv - For .env files.
Env (deprecated)

You can also write your own driver to use in your own applications. To write your own, read writing your own driver in this document.

Usage

To get started, construct a new instance of \Sven\FileConfig\Store, providing it with a \Sven\FileConfig\File object, and an implementation of the \Sven\FileConfig\Drivers\Driver interface. We'll use the pre-installed Json driver in the examples.

use Sven\FileConfig\File;
use Sven\FileConfig\Store;
use Sven\FileConfig\Drivers\Json;

$file = new File('/path/to/file.json');
$config = new Store($file, new Json());

You can interact with your newly created $config object via the get, set, and delete methods.

Examples

Let's take a look at some examples.

Getting a value from the file

To retrieve a value from the configuration file, use the get method. Let's assume our (prettified) JSON configuration file looks like this:

{
    "database": {
        "name": "test",
        "host": "localhost",
        "user": "admin",
        "password": "root"
    }
}

We can get the entire database array:

$config->get('database'); 
// ~> ['name' => 'test', 'host' => 'localhost', 'user' => 'admin', 'password' => root']

... or get only the database.host property using dot-notation:

$config->get('database.host'); 
// ~> 'localhost'

If the given key can not be found, null is returned by default. You may override this by passing a second argument to get:

$config->get('database.does_not_exist', 'default');
// ~> 'default'

Setting a value in the file

To add or change a value in the configuration file, you may use the set method. Note that you have to call the persist method to write the changes you made to the file. You may also use the fresh method to retrieve a "fresh" instance of the Store, where the values will be read from the file again.

$config->set('database.user', 'new-username');
$config->persist();

$freshConfig = $config->fresh();
$freshConfig->get('database.user');
// ~> 'new-username'

The file will end up looking like this after you've called the persist method:

{
    "database": {
        "name": "test",
        "host": "localhost",
        "user": "new-username",
        "password": "root"
    }
}

Deleting an entry from the file

To remove one of the configuration options from the file, use the delete method. Again, don't forget to call persist to write the new contents to the file!

$config->delete('database.user');
$config->persist();

{
    "database": {
        "name": "test",
        "host": "localhost",
        "password": "root"
    }
}

Writing your own driver

You may want to use a file format for your configuration that's not (yet) included in this package. Thankfully, writing a driver is as straightforward as turning your file's contents into a PHP array.

To create a driver, create a class that implements the \Sven\FileConfig\Drivers\Driver interface. Then add 2 methods to your class: import and export. The import method will receive the contents of the file as an argument, and expects a PHP array to be returned.

The export method is the exact reverse: it receives a PHP array, and expects the new contents of the file to be returned (as a string). To see how this works in more detail, take a look at the pre-installed json driver.

Contributing

All contributions (pull requests, issues and feature requests) are welcome. Make sure to read through the CONTRIBUTING.md first, though. See the contributors page for all contributors.

License

sven/file-config is licensed under the MIT License (MIT). Please see the license file for more information.

sven / file-config

Maintainers

Details