{"id":18879733,"url":"https://github.com/loilo/simple-config","last_synced_at":"2026-02-20T04:30:19.445Z","repository":{"id":62518773,"uuid":"198389187","full_name":"loilo/simple-config","owner":"loilo","description":"⚙️ Simple persistent configuration for your app or module","archived":false,"fork":false,"pushed_at":"2020-12-23T23:05:00.000Z","size":27,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-31T03:12:38.079Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/loilo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-23T08:41:58.000Z","updated_at":"2020-12-23T23:05:03.000Z","dependencies_parsed_at":"2022-11-02T13:46:14.014Z","dependency_job_id":null,"html_url":"https://github.com/loilo/simple-config","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loilo%2Fsimple-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loilo%2Fsimple-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loilo%2Fsimple-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loilo%2Fsimple-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loilo","download_url":"https://codeload.github.com/loilo/simple-config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239841742,"owners_count":19705981,"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","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":"2024-11-08T06:39:05.523Z","updated_at":"2026-02-20T04:30:17.382Z","avatar_url":"https://github.com/loilo.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"Simple Config logo: two interleaved gears, representing a typical \u0026quot;settings\u0026quot; icon\" src=\"simple-config.svg\" width=\"280\" height=\"220\"\u003e\n\u003c/div\u003e\n\n# Simple Config\n[![Tests](https://badgen.net/github/checks/loilo/simple-config/master)](https://github.com/loilo/simple-config/actions)\n[![Version on packagist.org](https://badgen.net/packagist/v/loilo/simple-config)](https://packagist.org/packages/loilo/simple-config)\n\n\u003e Simple persistent configuration for your app or module, heavily inspired by Sindre Sorhus' [conf](https://www.npmjs.com/package/conf) package.\n\n## Installation\n```bash\ncomposer require loilo/simple-config\n```\n\n## Usage\n```php\nuse Loilo\\SimpleConfig\\Config;\n\n$config = new Config();\n\n$config-\u003eset('foo', 'bar');\n$config-\u003eget('foo') === 'bar';\n \n// Use dot notation to access nested options\n$config-\u003eset('baz.qux', true);\n$config-\u003eget('baz') === [ 'qux' =\u003e true ];\n \n$config-\u003edelete('foo');\n$config-\u003eget('foo') === null;\n```\n\n### Methods\nThere are four methods on the `Config` object that you may use to work with the data store — `get`, `set`, `has` and `delete`:\n\n* To **check for presence of an option**, use `has`:\n\n  ```php\n  $config-\u003ehas('option')\n  ```\n\n* To **read an option**, use `get`:\n\n  ```php\n  $config-\u003eget('option')\n  ```\n\n  You may also pass a second argument to use as a fallback if the option is not found (defaults to `null`):\n\n  ```php\n  $config-\u003eget('nonexistent_option', 'fallback value')\n  ```\n\n* To **read the whole configuration**, use `get` with no arguments:\n\n  ```php\n  $config-\u003eget()\n  ```\n\n* To **write an option** (immediately synced with the config file), use `set`:\n\n  ```php\n  $config-\u003eset('option', 'value')\n  ```\n\n* To **write multiple options**, use `set` with an associative array:\n\n  ```php\n  $config-\u003eset([\n      'option-1' =\u003e 'value-1',\n      'option-2' =\u003e 'value-2'\n  ])\n  ```\n\n* To **remove an option**, use `delete`:\n\n  ```php\n  $config-\u003edelete('option')\n  ```\n\n* To **clear the config file**, use `delete` with no arguments:\n\n  ```php\n  $config-\u003edelete()\n  ```\n\n### Static Access\nSince app-wide configuration usually only ever requires one `Config` instance, you may not want to manually pass around that instance everywhere.\n\nIn most frameworks, a dependency injection container solves this task for you. However, for cases where no such mechanism is set up, this package provides the `StaticConfig` class.\n\nIt's an abstract class which you can extend in your project. The only thing you have to provide is a method to actually create a `Config` object. The simplest possible implementation therefore looks like this:\n\n```php\nuse Loilo\\SimpleConfig\\StaticConfig;\nuse Loilo\\SimpleConfig\\Config;\n\nclass AppConfig extends StaticConfig\n{\n    public static function createConfig(): Config\n    {\n        return new Config();\n    }\n}\n```\n\nNow you can work with your configuration like this:\n\n```php\nAppConfig::set('foo', 'bar');\nAppConfig::get('foo') === 'bar';\n```\n\n### Options\nThe `Config` object can be initialized with an associative array of options documented below.\n\n```php\n$config = new Config([\n  // options go here\n]);\n```\n\n### `defaults`\n\n**Type:** `array`\u003cbr\u003e\n**Default:** `null`\n\nDefault values for config items\n\n\u003e **Note 1:** Default values are applied with shallow (not recursive) merging: only missing *top level* options in the data are supplemented by defaults.\n\u003e\n\u003e **Note 2:** Defaults are never written to the config file so if you change your app's defaults and users have not overridden them explicitly, they will also change for all users.\n\n### `schema`\n\n**Type:** `array`\u003cbr\u003e\n**Default:** `null`\n\nA [JSON Schema](https://json-schema.org) to validate your config data. [JSON Schema draft-07](http://json-schema.org/latest/json-schema-validation.html) is used as far as it's supported by the underlying [validator package](https://github.com/justinrainbow/json-schema).\n\n\u003e **Note 1:** Your top-level schema definition is enforced to be of `\"type\": \"object\"`.\n\u003e\n\u003e **Note 2:** Default values defined in your schema are applied during validation, but are not returned when requested via `Config::get()`. This is a limitation of the underlying validator, as there's currently no JSON schema validator in PHP that applies default values to validated data and then allows access to them.\n\u003e\n\u003e **Note 3:** If your schema defines any mandatory top-level fields, you'll need to provide [defaults](#defaults) that satisfy the schema. This avoids schema violation errors when initializing an empty configuration.\n\n### `configName`\n\n**Type:** `string`\u003cbr\u003e\n**Default:** `\"config\"`\n\nName of the config file (without extension).\n\nUseful if you need multiple config files for your app or module (e.g. different config files between two major versions).\n\n### `projectName`\n\n**Type:** `string`\u003cbr\u003e\n**Default:** The `name` field in the `composer.json` closest to where `new Config()` is called.\n\nYou only need to specify this if you don't have a `composer.json` file in your project.\n\n### `configDir`\n\n**Type:** `string`\u003cbr\u003e\n**Default:** System default [user config directory](https://github.com/loilo/storage-paths#result)\n\nThe place where your config file is stored. You may override this to store configuration locally in your app's folder.\n\n\u003e **Note:** If you define this, the `projectName` option will be ignored.\n\n### `format`\n**Type:** `array`\u003cbr\u003e\n\nSettings regarding the configuration format. This is an associative array with the following possible keys:\n\n* `serialize`\n  \n  **Type:** `callable`\u003cbr\u003e\n  **Default:** `function ($data) { return json_encode($data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT); }`\n  \n  Function to serialize the config object to a UTF-8 string when writing the config file.\n  \n  You would usually not need this, but it could be useful if you want to use a format other than JSON.\n  \n* `deserialize`\n  \n  **Type:** `callable`\u003cbr\u003e\n  **Default:** `function ($string) {  return json_decode($string, true); }`\n  \n  Function to deserialize the config object from a UTF-8 string when reading the config file.\n  \n  You would usually not need this, but it could be useful if you want to use a format other than JSON.\n\n* `extension`\n  \n  **Type:** `string`\u003cbr\u003e\n  **Default:** `\"json\"`\n  \n  File extension of the config file. This may be reasonable to set if you changed your `serialize`/`deserialize` options.\n\n  \u003e **Note:** If you encrypt the configuration with a [password](#password), the config file will be saved in a binary format and this option will be ignored.\n\n### `password`\n\n**Type:** `string`\u003cbr\u003e\n**Default:** `null`\n\nA password to encrypt/decrypt the configuration file with. This can secure sensitive data, however it's naturally only as secure as your way of managing the password itself.\n\n\u003e **Note:** If you encrypt the configuration with a password, the config file will be saved in a binary format and the [`format.extension`](#format) option will be ignored.\n\n### `dotNotation`\n**Type:** `boolean`\u003cbr\u003e\n**Default:** `true`\n\nWhether to access options by dot notation.\n\n```js\n$config-\u003eset([\n    'foo' =\u003e [\n        'bar' =\u003e [\n            'foobar' =\u003e 'qux'\n        ]\n    ]\n]);\n\n// With dot notation enabled:\n$config-\u003eget('foo.bar.foobar') === 'qux';\n$config-\u003eget('foo')['bar']['foobar'] === 'qux';\n\n// With dot notation disabled:\n$config-\u003eget('foo.bar.foobar') === null;\n$config-\u003eget('foo')['bar']['foobar'] === 'qux';\n```\n\n### `clearInvalidConfig`\n\n**Type:** `boolean`\u003cbr\u003e\n**Default:** `true`\n\nIf set to `true`, the configuration is cleared if reading it raises an exception of any sort:\n\nException | Cause\n-|-\n| [`IOException`](https://github.com/symfony/symfony/blob/4.0/src/Symfony/Component/Filesystem/Exception/IOException.php) | The config file exists but could not be read.\n[`EnvironmentIsBrokenException`](https://github.com/defuse/php-encryption/blob/v2.0.0/src/Exception/EnvironmentIsBrokenException.php)\u003cbr\u003e[`WrongKeyOrModifiedCiphertextException`](https://github.com/defuse/php-encryption/blob/v2.0.0/src/Exception/WrongKeyOrModifiedCiphertextException.php) | File decryption failed (when using a [password](#password)).\n[`DeserializationException`](src/Exception/DeserializationException.php) | Deserialization failed (e.g. if the [deserialization function](#deserialize) changed or if someone or something meddled with the file).\n[`InvalidConfigException`](src/Exception/InvalidConfigException.php) | The configuration is invalid according to the [schema](#schema).\n\nEnabling this option is a good default, as the config file is not intended to be hand-edited, so this usually means the config is corrupt and there's nothing your app can do about it anyway. However, if you let the user edit the config file directly, mistakes might happen and it could be useful to throw an error when the config is invalid instead of clearing it.\n\nDisabling this option will cause the exceptions listed above to be re-thrown and handled manually.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floilo%2Fsimple-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floilo%2Fsimple-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floilo%2Fsimple-config/lists"}