[Enhancement] Add ArrayFile & EnvFile Parsing, replace ConfigWriter internal logic

[jaxwilko]

This is a POC PR proposing a replacement for ConfigWriter. Currently, ConfigWriter is used to update php config files, for example during winter install.

In this PR I've added a new class ConfigFile, which can be used to modify any php config file without risking the same kind of corruption that can be caused using ConfigWriter. The reason for this improvement is due to the fundemental differences in approach, where ConfigWriter modifies the file contents as a string, ConfigFile uses nikic/php-parser to generate an ast of the config file and allows us to modify the code as php objects before "printing" them back out using the WinterPrinter (an exstension to PhpParser\PrettyPrinter\Standard).

Example

Config file:

<?php

return [
    'foo' => env('ENV_VALUE', 'bar'),
    'bar' => [
         'winter' => 'cms'
    ]
];

Sample usage:

use Winter\Storm\Config\ConfigFile;

$config = ConfigFile::read('/path/to/file');
$config->set('foo', 'foo')
    ->set('bar.winter', 'is coming');
$config->write();

Will update the config file to:

<?php

return [
    'foo' => env('ENV_VALUE', 'foo'),
    'bar' => [
         'winter' => 'is coming'
    ]
];

There are currently some issues when node types are swapped by setting a value that differs in type from the originally parsed value, but they should be simple to fix. I have modified the winter:install command to use ConfigFile over ConfigWriter and it works nicely, however it would be good to get some feed back on this core peice before opening a PR for the install command.

Please let me know any thoughts or suggestions you have :)

[LukeTowers]

Oooh shiny :) Can't wait to review this :) 👀

[mjauvin]

Would it be possible to add a comma after the last item of an array when writing the results to the file (to ease manual maintainability)?

[jaxwilko]

@mjauvin ah, it already does, my example just doesn't show it.

For reference here is a config I just saved using winter:install:

Also new line padding on single line comments has now been fixed as of 524561f

[bennothommo]

This is awesome @jaxwilko. Well done :)

[jaxwilko]

The issues relating to updating a value from one type to another (i.e. int -> bool) has now be resolved. I added a load of code and so that we would:

• Check if note is same type as incoming value (i.e. currently string, updating to string).
• If match, update the node in place.
• If not match, create a new node of the correct type and replace the original node.

Rather than doing all that extra work, it's far simpiler if we just:

• Create a new node of the correct type and replace the original node

This solves the casting issue and cuts down on code / processing.

[jaxwilko]

The following is documentation I'm writing now while it's fresh in my head.

Documentation

ConfigFile provides the ability to update php config files in place. A side effect it can also be used to reformat a config file in the Winter style.

Init

To initalize the ConfigFile object, you can use the static read() method:

$config = ConfigFile::read('/path/to/file');

Alternatively, you can directly initalize the object:

$config = new ConfigFile($ast, $filePath = null, $printer = null);

However initalizing the object this way requires you to parse the config file manually using PhpParser\Parser and pass the result as the first argument.

Updating a value

To update a value in the config, call the set() method:

$config->set('property.key', $value);

If you have multiple properties to update, you can also pass an array:

$config->set([
    'property.key' => $value,
    'property.other_key' => $otherValue
]);

Saving

To retrieve the "printed" result as a string you can use the render() method:

$string = $config->render();

If you set use the ConfigFile::read() method for initialization or set the $filePath property when initing the object, you can call the write() method to overwrite the original file:

$config = ConfigFile::read('/path/to/config.php');
$config->write(); // saves to /path/to/config.php

Alternatively you can pass write() a file path to save to:

$config = ConfigFile::read('/path/to/config.php');
$config->write('/path/to/config.new.php'); // saves to /path/to/config.new.php

[bennothommo]

In addition to the below changes, could you provide some details in the docblocks for the main class methods? I assume these were auto-generated through PHPStorm, but don't really describe what the methods are doing.