README

perm offers a simple way to save and retrieve "native" php configuration files in the filesystem.

For example, if writing a cms like Vessel, you might want to save fast configuration values (like a site title or url) perm-anently from an admin interface. This is easy with perm.

Requirements

PHP 5.3+ or HHVM
Laravel 4
Composer

Installation

perm installs with Composer through Packagist.

Add the following to your composer.json:

{
	"require": {
		"andrewsuzuki/perm": "dev-master",
	}
}

Then run composer update.

Now add the following to your providers array in config/app.php:

'Andrewsuzuki\Perm\PermServiceProvider',

Now add the facade alias to the aliases array:

'Perm' => 'Andrewsuzuki\Perm\Facades\Perm',

And that's it.

Configuration

If you'd like to load/save files from a base directory other than app/config, publish the package's configuration:

php artisan config:publish hokeo/vessel

Then modify the basepath in app/config/packages/andrewsuzuki/perm/config.php.

Usage

Load a config file, or mark a non-existing file/directory for creation. chainable

// dot notation from base path (see above for configuration)
$perm = Perm::load('profile.andrew');
// ...or absolute path (no extension)
$perm = Perm::load('/path/to/file');

If the file's directory does not exist, it will be created.

Get a config value.

$location   = $perm->get('location');
$location   = $perm->location; // for the first level, you can use magic properties
$first_name = $perm->get('name.first'); // use dot notation for nested values

Get multiple values in one go (returns array).

$locationAndFirstName = $perm->get(array('location', 'name.first'));
// or...
list($location, $firstName) = $perm->get(array('location', 'name.first'));

Get all config values.

$config = $perm->all();

Set a value. chainable

$perm->set('timezone', 'UTC');
// for the first level, you can use magic properties
$perm->timezone = 'UTC';

Set a value if and only if it doesn't exist. chainable

$perm->setIf('timezone', 'UTC');

Set multiple values in one go. chainable

$perm->set(array('timezone' => 'UTC', 'location' => 'Earth'));

Check if a key exists.

$exists = $perm->has('location'); // true/false
$exists = $perm->has('name.first'); // true/false

Forget a key. chainable

$perm->forget('location');

Reset (forget all key/values). chainable

$perm->reset();

Save updated config. chainable

$perm->save();

Update current loaded filename (will not update loaded config). Filename basename must not contain dots. chainable

$perm->setFilename('/path/to/new/file');
// then you might set some more values, then call ->save() again, etc...

Method chaining

Chaining methods is an easy way to consolidate, and improve readability. You can combine any of the above methods marked as chainable. For example:

Perm::load('profile.andrew')->set('name', 'Andrew')->forget('location')->save();

Contributors

Andrew Suzuki

To contribute, please fork and submit a pull request. Otherwise, feel free to submit possible enhancements/issues on the issues page.

License

Vessel is open-sourced software licensed under the MIT license

andrewsuzuki / perm

Maintainers

Details