{"id":24764105,"url":"https://github.com/stillat/proteus","last_synced_at":"2025-10-11T13:30:16.324Z","repository":{"id":40262656,"uuid":"305856235","full_name":"Stillat/proteus","owner":"Stillat","description":"A library to read, modify, and write Laravel-style PHP configuration files.","archived":false,"fork":false,"pushed_at":"2025-04-02T01:27:17.000Z","size":204,"stargazers_count":14,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-26T13:28:36.147Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stillat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"JohnathonKoster"}},"created_at":"2020-10-20T23:23:34.000Z","updated_at":"2025-04-19T18:49:00.000Z","dependencies_parsed_at":"2023-02-17T00:25:27.808Z","dependency_job_id":"3eff6377-cee6-42f3-ae47-d9ebba00df9c","html_url":"https://github.com/Stillat/proteus","commit_stats":{"total_commits":101,"total_committers":4,"mean_commits":25.25,"dds":0.05940594059405946,"last_synced_commit":"d20a40d0935440a0a4cafad2b61a1622092ae928"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/Stillat/proteus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fproteus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fproteus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fproteus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fproteus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stillat","download_url":"https://codeload.github.com/Stillat/proteus/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fproteus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007341,"owners_count":26084282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-28T21:32:50.266Z","updated_at":"2025-10-11T13:30:16.317Z","avatar_url":"https://github.com/Stillat.png","language":"PHP","funding_links":["https://github.com/sponsors/JohnathonKoster"],"categories":[],"sub_categories":[],"readme":"This library provides utilities and features for parsing, updating, and writing Laravel style PHP configuration files.\n\n## Installation\n\nTo install Proteus issue the following command, or at `stillat/proteus` to your `composer.json` file:\n\n```\ncomposer require stillat/proteus\n```\n\n## Basic Usage\n\nThe `ConfigWriter` facade will automatically load and manage your existing Laravel configuration files, and dramatically simplifies the usage of the configuration writer:\n\n```php\n\u003c?php\n\nStillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\n// Change the default locale to 'fr' and save to disk:\nConfigWriter::write('app.locale', 'fr');\n\n// Add a new nested entry:\nConfigWriter::write('app.new.entry', 'new-value');\n\n// And then update that new entry:\nConfigWriter::write('app.new.entry', 'updated-value');\n\n```\n\nYou may also write many configuration items at once:\n\n```php\n\u003c?php\n\nStillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\n\nConfigWriter::writeMany('app', [\n    'locale' =\u003e 'fr',\n    'timezone' =\u003e 'Europe/Paris'\n]);\n\n\n```\n\nIf you only want the document contents (without writing to disk), you may use the `preview` and `previewMany` counterparts:\n\n```php\n\u003c?php\n\nStillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\n$document = ConfigWriter::preview('app.locale', 'fr');\n\n$document = ConfigWriter::previewMany('app', [\n    'locale' =\u003e 'fr',\n    'timezone' =\u003e 'Europe/Paris'\n]);\n\n\n```\n\n## Preventing Changes to Configuration Items\n\nYou may use the `guard` method to prevent changes to specific configuration entries:\n\n```php\n\u003c?php\n\nStillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::guard('app.key');\n\n```\n\nIf a change is detected for `app.key`, an instance of `GuardedConfigurationMutationException` will be thrown.\n\nYou may also restrict changes on entire configuration namespaces:\n\n\n```php\n\u003c?php\n\nStillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::guard('app.*');\n\n```\n\nOr to just a sub-section of the configuration:\n\n\n```php\n\u003c?php\n\nStillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::guard('app.providers*');\n\n```\n\n## Enabling Function Rewrites\n\nChanges to function calls (such as `env`) can are disabled by default. To enable them, you may call the `ignoreFunctionCalls` method with `false`:\n\n```php\n\u003c?php\n\nStillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\n// Calls to env, and other functions, will be updated.\nConfigWriter::ignoreFunctionCalls(false)-\u003ewriteMany('app', [\n    'key' =\u003e 'new-value',\n    'locale' =\u003e 'fr',\n    'timezone' =\u003e 'Europe/Paris'\n]);\n```\n\n## Preserving Configuration Values\n\nYou may ignore certain configuration value updates by using the `preserve` method. The `preserve` method accepts an array of strings (dot notation is also supported!).\n\n```php\n\u003c?php\n\nStillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\n// Changes to locale and timezone will be ignored, since they will be preserved.\nConfigWriter::preserve([\n    'locale', 'timezone'\n])-\u003ewriteMany('app', [\n    'locale' =\u003e 'fr',\n    'timezone' =\u003e 'Europe/Paris'\n]);\n```\n\n## Intermediate Usage\n\nFor 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.\n\nIn 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:\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\n$document = ConfigWriter::edit('app')\n    -\u003eset('locale', 'fr')\n    -\u003eset('timezone', 'Europe/Paris')\n    -\u003epreview();\n```\n\nWe can save ourselves some keystrokes by supplying a key/value pair to the `set` method:\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\n$document = ConfigWriter::edit('app')\n    -\u003eset([\n        'locale' =\u003e 'fr',\n        'timezone' =\u003e 'Europe/Paris'\n    ])-\u003epreview();\n```\n\nTo save the changes instead of assigning them to a value, we can call `save` instead of `preview`:\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::edit('app')\n    -\u003eset([\n        'locale' =\u003e 'fr',\n        'timezone' =\u003e 'Europe/Paris'\n    ])-\u003esave();\n```\n\n### Removing Existing Configuration Values\n\nYou may use the `remove` method to remove an existing configuration item:\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::edit('app')-\u003eremove('locale')-\u003esave();\n```\n\nThis method will also remove the configuration key from the configuration file - not just the value!\n\n### Replacing an Existing Configuration Value\n\nYou may use the `replace` method to completely replace an existing configuration item:\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::edit('app')-\u003ereplace('providers', [\n    // The new list of providers.\n])-\u003esave();\n```\n\n### Merging Array Configuration Items\n\nYou 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:\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::edit('app')-\u003emerge('providers', [\n    SomeProvider::class,\n    SomeOtherProvider::class\n])-\u003esave();\n```\n\nThe `merge` method will make sure there are no duplicates in the resulting configuration values.\n\n### Performing Multiple Actions\n\nYou may perform multiple actions at once by chaining them. Chained actions are performed in the order they are specified.\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::edit('app')\n    -\u003eset([\n        'locale' =\u003e 'fr',\n        'timezone' =\u003e 'Europe/Paris'\n    ])-\u003emerge('providers', [\n        SomeProvider::class,\n        SomeOtherProvider::class\n    ])-\u003eset('fallback_locale', 'fr')-\u003esave();\n````\n\n### Writing Function Calls to Configuration Files\n\nYou may also write Laravel function calls as part of the generated configuration by using the `f` helper method:\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003ebasePath('relative'));\n```\n\nThe configuration output would then be similar to the following:\n\n```php\nreturn [\n\n    'path' =\u003e base_path('relative'),\n\n];\n```\n\nThe following functions are available:\n\n```php\n\u003c?php\n\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\n// base_path\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003ebasePath('relative'));\n\n// storage_path\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003estoragePath('relative'));\n\n// app_path\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003eappPath('relative'));\n\n// config_path\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003econfigPath('relative'));\n\n// database_path\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003edatabasePath('relative'));\n\n// public_path\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003epublicPath('relative'));\n\n// resource_path\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003eresourcePath('relative'));\n```\n\nYou may also call other **globally registered** functions:\n\n```php\n\u003c?php\nuse Stillat\\Proteus\\Support\\Facades\\ConfigWriter;\n\nfunction my_custom_function($paramOne, $paramTwo) {\n    ...\n}\n\nConfigWriter::write('custom.path', ConfigWriter::f()-\u003emakeSimpleFunctionCall('my_custom_function', [$one, $two]));\n```\n\n## Advanced Usage\n\nGiven the following input configuration file:\n\n```php\nreturn [\n\n    'key' =\u003e env('APP_KEY'),\n\n];\n```\n\nWe can manually create a configuration updater and apply our changes manually:\n\n```php\nuse Stillat\\Proteus\\ConfigUpdater;\n\n$updater = new ConfigUpdater();\n$updater-\u003eopen('./path/to/config.php');\n$updater-\u003eupdate([\n    'key' =\u003e 'new-key',\n    'new' =\u003e [\n        'deeply' =\u003e [\n            'nested' =\u003e [\n                'key' =\u003e [\n                    'hello',\n                    'world'\n                ]\n            ]\n        ]\n    ]\n]);\n\n$newConfigContents = $updater-\u003egetDocument();\n```\n\nAfter running, `$newConfigContents` would contain output similar to the following:\n\n```php\n\u003c?php\n\nreturn [\n\n    'key' =\u003e env('APP_KEY', 'new-key'),\n    'new' =\u003e [\n        'deeply' =\u003e [\n            'nested' =\u003e [\n                'key' =\u003e [\n                    'hello',\n                    'world',\n                ],\n            ],\n        ],\n    ],\n\n];\n```\n\nAnd yes, it did add the `new-key` value as the default value for the `env` call instead of replacing the lookup key :)\n\n## Features\n\n* Attempts to preserve most file formatting,\n* Handles adding new simple keys,\n* Handles adding new deeply nested keys,\n* Allows for appending configuration files to an existing configuration array,\n* Allows for overwriting configuration files in an existing configuration array,\n* Simple `ConfigWriter` facade\n\n## Road Map\n\nThere will undoubtedly be changes required overtime, and if you find something not working, please open an issue with\nthe input you are supplying and the expected results. Bonus points if you add a test case for it :)\n\n## License\n\nMIT License. See LICENSE.MD\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstillat%2Fproteus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstillat%2Fproteus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstillat%2Fproteus/lists"}