This library provides utilities and features for parsing, updating, and writing Laravel style PHP configuration files.
To install Proteus issue the following command, or at stillat/proteus
to your composer.json
file:
composer require stillat/proteus
The ConfigWriter
facade will automatically load and manage your existing Laravel configuration files, and dramatically simplifies the usage of the configuration writer:
<?php
Stillat\Proteus\Support\Facades\ConfigWriter;
// Change the default locale to 'fr' and save to disk:
ConfigWriter::write('app.locale', 'fr');
// Add a new nested entry:
ConfigWriter::write('app.new.entry', 'new-value');
// And then update that new entry:
ConfigWriter::write('app.new.entry', 'updated-value');
You may also write many configuration items at once:
<?php
Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::writeMany('app', [
'locale' => 'fr',
'timezone' => 'Europe/Paris'
]);
If you only want the document contents (without writing to disk), you may use the preview
and previewMany
counterparts:
<?php
Stillat\Proteus\Support\Facades\ConfigWriter;
$document = ConfigWriter::preview('app.locale', 'fr');
$document = ConfigWriter::previewMany('app', [
'locale' => 'fr',
'timezone' => 'Europe/Paris'
]);
You may use the guard
method to prevent changes to specific configuration entries:
<?php
Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::guard('app.key');
If a change is detected for app.key
, an instance of GuardedConfigurationMutationException
will be thrown.
You may also restrict changes on entire configuration namespaces:
<?php
Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::guard('app.*');
Or to just a sub-section of the configuration:
<?php
Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::guard('app.providers*');
Changes to function calls (such as env
) can are disabled by default. To enable them, you may call the ignoreFunctionCalls
method with false
:
<?php
Stillat\Proteus\Support\Facades\ConfigWriter;
// Calls to env, and other functions, will be updated.
ConfigWriter::ignoreFunctionCalls(false)->writeMany('app', [
'key' => 'new-value',
'locale' => 'fr',
'timezone' => 'Europe/Paris'
]);
You may ignore certain configuration value updates by using the preserve
method. The preserve
method accepts an array of strings (dot notation is also supported!).
<?php
Stillat\Proteus\Support\Facades\ConfigWriter;
// Changes to locale and timezone will be ignored, since they will be preserved.
ConfigWriter::preserve([
'locale', 'timezone'
])->writeMany('app', [
'locale' => 'fr',
'timezone' => 'Europe/Paris'
]);
For more control to remove, replace, and even merge array values with existing configuration values, we can use the edit
helper method. This helper method expects a configuration namespace, and returns access to a convenient wrapper to perform a variety of configuration changes.
In the following example, we will start an edit instance for the app
configuration namespace, modify a few values, and save the results to a $document
variable:
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
$document = ConfigWriter::edit('app')
->set('locale', 'fr')
->set('timezone', 'Europe/Paris')
->preview();
We can save ourselves some keystrokes by supplying a key/value pair to the set
method:
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
$document = ConfigWriter::edit('app')
->set([
'locale' => 'fr',
'timezone' => 'Europe/Paris'
])->preview();
To save the changes instead of assigning them to a value, we can call save
instead of preview
:
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::edit('app')
->set([
'locale' => 'fr',
'timezone' => 'Europe/Paris'
])->save();
You may use the remove
method to remove an existing configuration item:
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::edit('app')->remove('locale')->save();
This method will also remove the configuration key from the configuration file - not just the value!
You may use the replace
method to completely replace an existing configuration item:
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::edit('app')->replace('providers', [
// The new list of providers.
])->save();
You may use the merge
method to add new values to an existing configuration item. For example, the following would add the SomeProvider
and SomeOtherProvider
class providers to the list of application providers:
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::edit('app')->merge('providers', [
SomeProvider::class,
SomeOtherProvider::class
])->save();
The merge
method will make sure there are no duplicates in the resulting configuration values.
You may perform multiple actions at once by chaining them. Chained actions are performed in the order they are specified.
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::edit('app')
->set([
'locale' => 'fr',
'timezone' => 'Europe/Paris'
])->merge('providers', [
SomeProvider::class,
SomeOtherProvider::class
])->set('fallback_locale', 'fr')->save();
You may also write Laravel function calls as part of the generated configuration by using the f
helper method:
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
ConfigWriter::write('custom.path', ConfigWriter::f()->basePath('relative'));
The configuration output would then be similar to the following:
return [
'path' => base_path('relative'),
];
The following functions are available:
<?php
use Stillat\Proteus\Support\Facades\ConfigWriter;
// base_path
ConfigWriter::write('custom.path', ConfigWriter::f()->basePath('relative'));
// storage_path
ConfigWriter::write('custom.path', ConfigWriter::f()->storagePath('relative'));
// app_path
ConfigWriter::write('custom.path', ConfigWriter::f()->appPath('relative'));
// config_path
ConfigWriter::write('custom.path', ConfigWriter::f()->configPath('relative'));
// database_path
ConfigWriter::write('custom.path', ConfigWriter::f()->databasePath('relative'));
// public_path
ConfigWriter::write('custom.path', ConfigWriter::f()->publicPath('relative'));
// resource_path
ConfigWriter::write('custom.path', ConfigWriter::f()->resourcePath('relative'));
Given the following input configuration file:
return [
'key' => env('APP_KEY'),
];
We can manually create a configuration updater and apply our changes manually:
use Stillat\Proteus\ConfigUpdater;
$updater = new ConfigUpdater();
$updater->open('./path/to/config.php');
$updater->update([
'key' => 'new-key',
'new' => [
'deeply' => [
'nested' => [
'key' => [
'hello',
'world'
]
]
]
]
]);
$newConfigContents = $updater->getDocument();
After running, $newConfigContents
would contain output similar to the following:
<?php
return [
'key' => env('APP_KEY', 'new-key'),
'new' => [
'deeply' => [
'nested' => [
'key' => [
'hello',
'world',
],
],
],
],
];
And yes, it did add the new-key
value as the default value for the env
call instead of replacing the lookup key :)
- Attempts to preserve most file formatting,
- Handles adding new simple keys,
- Handles adding new deeply nested keys,
- Allows for appending configuration files to an existing configuration array,
- Allows for overwriting configuration files in an existing configuration array,
- Simple
ConfigWriter
facade
There will undoubtedly be changes required overtime, and if you find something not working, please open an issue with the input you are supplying and the expected results. Bonus points if you add a test case for it :)
MIT License. See LICENSE.MD