README

此库提供了解析、更新和编写 Laravel 风格 PHP 配置文件的实用工具和功能。

安装

要安装 Proteus，请执行以下命令，或在您的 composer.json 文件中添加 stillat/proteus

composer require stillat/proteus

基本用法

ConfigWriter 门面将自动加载和管理您的现有 Laravel 配置文件，并大大简化了配置编写器的使用。

<?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');

您也可以一次写入许多配置项。

<?php

Stillat\Proteus\Support\Facades\ConfigWriter;


ConfigWriter::writeMany('app', [
    'locale' => 'fr',
    'timezone' => 'Europe/Paris'
]);

如果您只想获取文档内容（不写入磁盘），您可以使用 preview 和 previewMany 对应的选项。

<?php

Stillat\Proteus\Support\Facades\ConfigWriter;

$document = ConfigWriter::preview('app.locale', 'fr');

$document = ConfigWriter::previewMany('app', [
    'locale' => 'fr',
    'timezone' => 'Europe/Paris'
]);

防止更改配置项

您可以使用 guard 方法防止更改特定的配置条目。

<?php

Stillat\Proteus\Support\Facades\ConfigWriter;

ConfigWriter::guard('app.key');

如果检测到 app.key 的更改，将抛出一个 GuardedConfigurationMutationException 实例。

您也可以限制对整个配置命名空间的更改。

<?php

Stillat\Proteus\Support\Facades\ConfigWriter;

ConfigWriter::guard('app.*');

或者只限制对配置的子部分的更改。

<?php

Stillat\Proteus\Support\Facades\ConfigWriter;

ConfigWriter::guard('app.providers*');

启用函数重写

默认情况下禁用函数调用（如 env）。要启用它们，您可以通过调用 ignoreFunctionCalls 方法并传递 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'
]);

保留配置值

您可以使用 preserve 方法忽略某些配置值更新。该方法接受一个字符串数组（也支持点表示法！）。

<?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'
]);

中级用法

为了更精确地删除、替换甚至合并数组值与现有配置值，我们可以使用 edit 辅助方法。此辅助方法期望一个配置命名空间，并返回对便捷包装器的访问，以便执行各种配置更改。

在以下示例中，我们将为 app 配置命名空间启动一个编辑实例，修改一些值，并将结果保存到 $document 变量中。

<?php

use Stillat\Proteus\Support\Facades\ConfigWriter;

$document = ConfigWriter::edit('app')
    ->set('locale', 'fr')
    ->set('timezone', 'Europe/Paris')
    ->preview();

我们可以通过向 set 方法提供键值对来节省一些按键。

<?php

use Stillat\Proteus\Support\Facades\ConfigWriter;

$document = ConfigWriter::edit('app')
    ->set([
        'locale' => 'fr',
        'timezone' => 'Europe/Paris'  
    ])->preview();

要保存更改而不是分配给值，我们可以调用 save 而不是 preview。

<?php

use Stillat\Proteus\Support\Facades\ConfigWriter;

ConfigWriter::edit('app')
    ->set([
        'locale' => 'fr',
        'timezone' => 'Europe/Paris'  
    ])->save();

删除现有配置值

您可以使用 remove 方法删除现有的配置项。

<?php

use Stillat\Proteus\Support\Facades\ConfigWriter;

ConfigWriter::edit('app')->remove('locale')->save();

此方法将从配置文件中删除配置键 - 而不仅仅是值！

替换现有配置值

您可以使用 replace 方法完全替换现有的配置项。

<?php

use Stillat\Proteus\Support\Facades\ConfigWriter;

ConfigWriter::edit('app')->replace('providers', [
    // The new list of providers.
])->save();

合并数组配置项

您可以使用 merge 方法向现有配置项添加新值。例如，以下会将 SomeProvider 和 SomeOtherProvider 类提供者添加到应用程序提供者列表中。

<?php

use Stillat\Proteus\Support\Facades\ConfigWriter;

ConfigWriter::edit('app')->merge('providers', [
    SomeProvider::class,
    SomeOtherProvider::class
])->save();

merge 方法将确保结果配置值中没有重复。

执行多个操作

您可以通过链接它们来同时执行多个操作。链式操作按指定顺序执行。

<?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();

将函数调用写入配置文件

您还可以使用 f 辅助方法将 Laravel 函数调用作为生成配置的一部分。

<?php

use Stillat\Proteus\Support\Facades\ConfigWriter;

ConfigWriter::write('custom.path', ConfigWriter::f()->basePath('relative'));

配置输出将类似于以下内容

return [

    'path' => base_path('relative'),

];

以下功能可用：

<?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'));

高级用法

给定以下输入配置文件

return [

    'key' => env('APP_KEY'),

];

我们可以手动创建配置更新器并手动应用我们的更改

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();

运行后，$newConfigContents将包含类似于以下内容的输出

<?php

return [

    'key' => env('APP_KEY', 'new-key'),
    'new' => [
        'deeply' => [
            'nested' => [
                'key' => [
                    'hello',
                    'world',
                ],
            ],
        ],
    ],

];

是的，它确实添加了new-key值作为对env调用的默认值，而不是替换查找键 :)

功能

• 尝试保留大多数文件格式
• 处理添加新的简单键
• 处理添加新的深层嵌套键
• 允许将配置文件追加到现有的配置数组中
• 允许覆盖现有配置数组中的配置文件
• 简单的ConfigWriter外观

路线图

随着时间的推移，无疑会需要一些更改，如果您发现某些功能无法正常工作，请提交一个包含您提供的输入和预期结果的issue。如果您为它添加了一个测试用例，那么您将获得额外的加分 :)

许可证

MIT许可证。请参阅LICENSE.MD文件