{"id":15481697,"url":"https://github.com/charcoalphp/config","last_synced_at":"2025-08-18T03:36:46.331Z","repository":{"id":37492672,"uuid":"505905893","full_name":"charcoalphp/config","owner":"charcoalphp","description":"[READ-ONLY] Configuration container for all things Charcoal","archived":false,"fork":false,"pushed_at":"2024-03-13T15:05:14.000Z","size":1122,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-07T00:09:34.462Z","etag":null,"topics":["charcoal","config","configuration","php","read-only-repository"],"latest_commit_sha":null,"homepage":"https://github.com/charcoalphp/charcoal","language":"PHP","has_issues":false,"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/charcoalphp.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,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-06-21T15:43:19.000Z","updated_at":"2022-06-21T19:26:53.000Z","dependencies_parsed_at":"2024-03-13T16:29:38.688Z","dependency_job_id":"0098a3af-2989-4b0f-888d-93a5f3e02dc3","html_url":"https://github.com/charcoalphp/config","commit_stats":{"total_commits":126,"total_committers":6,"mean_commits":21.0,"dds":0.4920634920634921,"last_synced_commit":"1e1d20461f342dd415372ee9d5e351dd17f86a7b"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/charcoalphp/config","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fconfig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fconfig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fconfig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fconfig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charcoalphp","download_url":"https://codeload.github.com/charcoalphp/config/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fconfig/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270603267,"owners_count":24614458,"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-08-15T02:00:12.559Z","response_time":110,"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":["charcoal","config","configuration","php","read-only-repository"],"created_at":"2024-10-02T05:05:37.614Z","updated_at":"2025-08-18T03:36:46.267Z","avatar_url":"https://github.com/charcoalphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Charcoal Config\n===============\n\nThe Config package provides abstract tools for organizing configuration data and designing object data models.\n\n## Installation\n\n```shell\ncomposer require charcoal/config\n```\n\n## Overview\n\n### Entity \u0026 Config\n\nThe Config component simplifies access to object data. It provides a property-based user interface for retrieving and storing arbitrary data within application code. Data is organized into two primary object types: _Entity_ and _Config_.\n\n#### Entity\n\nEntities represent simple data-object containers designed as a flexible foundation for domain model objects.  \nExamples: a single result from a repository or serve as the basis for each component of an MVC system.\n\n* **Class**: [`Charcoal\\Config\\AbstractEntity`](src/Charcoal/Config/AbstractEntity.php)\n* **Methods**: `keys`, `data`, `setData`, `has`, `get`, `set`\n* **Interface**: [`Charcoal\\Config\\EntityInterface`](src/Charcoal/Config/EntityInterface.php)\n  * `ArrayAccess`\n  * `JsonSerializable`\n  * `Serializable`\n\n#### Config\n\nConfigs are advanced _Entities_ designed for runtime configuration values with support for loading files and storing hierarchical data.  \nExamples: application preferences, service options, and factory settings.\n\n* **Class**: [`Charcoal\\Config\\AbstractConfig`](src/Charcoal/Config/AbstractConfig.php)\n  * `IteratorAggregate`\n  * `Psr\\Container\\ContainerInterface`\n* **Methods**: `defaults`, `merge`, `addFile`\n* **Interface**: [`Charcoal\\Config\\ConfigInterface`](src/Charcoal/Config/ConfigInterface.php)\n  * `Charcoal\\Config\\EntityInterface`\n  * `Charcoal\\Config\\FileAwareInterface`\n  * `Charcoal\\Config\\SeparatorAwareInterface`\n  * `Charcoal\\Config\\DelegatesAwareInterface`\n\n### Features\n\n* [Read data from INI, JSON, PHP, and YAML files](#file-loader)\n* [Customizable separator for nested lookup](#key-separator-lookup)\n* [Share configuration entries](#delegates-lookup)\n* [Array accessible entities](#array-access)\n* [Interoperable datasets](#interoperability)\n* [Configurable objects](#configurable-objects)\n\n#### File Loader\n\nThe _Config_ container currently supports four file formats: INI, JSON, PHP, and YAML.\n\nA configuration file can be imported into a Config object via the `addFile($path)` method, or by direct instantiation:\n\n```php\nuse Charcoal\\Config\\GenericConfig as Config;\n\n$cfg = new Config('config.json');\n$cfg-\u003eaddFile('config.yml');\n```\n\nThe file's extension will be used to determine how to import the file.\nThe file will be parsed and, if its an array, will be merged into the container.\n\nIf you want to load a configuration file _without_ adding its content to the Config, use `loadFile($path)` instead.\nThe file will be parsed and returned regardless if its an array.\n\n```php\n$data = $cfg-\u003eloadFile('config.php');\n```\n\nCheck out the [documentation](docs/file-loader.md) and [examples](tests/Charcoal/Config/Fixture/pass) for more information.\n\n#### Key Separator Lookup\n\nIt is possible to lookup, retrieve, assign, or merge values in multi-dimensional arrays using _key separators_.\n\nIn Config objects, the default separator is the period character (`.`). The token can be retrieved with the `separator()` method and customized using the `setSeparator()` method.\n\n```php\nuse Charcoal\\Config\\GenericConfig as Config;\n\n$cfg = new Config();\n$cfg-\u003esetSeparator('/');\n$cfg-\u003esetData([\n    'database' =\u003e [\n        'params' =\u003e [\n            'name' =\u003e 'mydb',\n            'user' =\u003e 'myname',\n            'pass' =\u003e 'secret',\n        ]\n    ]\n]);\n\necho $cfg['database/params/name']; // \"mydb\"\n```\n\nCheck out the [documentation](docs/separator-lookup.md) for more information.\n\n#### Delegates Lookup\n\nDelegates allow several objects to share values and act as fallbacks when the current object cannot resolve a given data key.\n\nIn Config objects, _delegate objects_ are regsitered to an internal stack. If a data key cannot be resolved, the Config iterates over each delegate in the stack and stops on\nthe first match containing a value that is not `NULL`.\n\n```php\nuse Charcoal\\Config\\GenericConfig as Config;\n\n$cfg = new Config([\n    'driver' =\u003e null,\n    'host'   =\u003e 'localhost',\n]);\n$delegate = new Config([\n    'driver' =\u003e 'pdo_mysql',\n    'host'   =\u003e 'example.com',\n    'port'   =\u003e 11211,\n]);\n\n$cfg-\u003eaddDelegate($delegate);\n\necho $cfg['driver']; // \"pdo_mysql\"\necho $cfg['host']; // \"localhost\"\necho $cfg['port']; // 11211\n```\n\nCheck out the [documentation](docs/delegates-lookup.md) for more information.\n\n#### Array Access\n\nThe Entity object implements the `ArrayAccess` interface and therefore can be used with array style:\n\n```php\n$cfg = new \\Charcoal\\Config\\GenericConfig();\n\n// Assigns a value to \"foobar\"\n$cfg['foobar'] = 42;\n\n// Returns 42\necho $cfg['foobar'];\n\n// Returns TRUE\nisset($cfg['foobar']);\n\n// Returns FALSE\nisset($cfg['xyzzy']);\n\n// Invalidates the \"foobar\" key\nunset($cfg['foobar']);\n```\n\n\u003e 👉 A data key MUST be a string otherwise `InvalidArgumentException` is thrown.\n\n#### Interoperability\n\nThe Config object implements [PSR-11](psr-11): `Psr\\Container\\ContainerInterface`.\n\nThis interface exposes two methods: `get()` and `has()`. These methods are implemented by the Entity object as aliases of `ArrayAccess::offsetGet()` and `ArrayAccess::offsetExists()`.\n\n```php\n$config = new \\Charcoal\\Config\\GenericConfig([\n    'foobar' =\u003e 42\n]);\n\n// Returns 42\n$config-\u003eget('foobar');\n\n// Returns TRUE\n$config-\u003ehas('foobar');\n\n// Returns FALSE\n$config-\u003ehas('xyzzy');\n```\n\n\u003e 👉 A call to the `get()` method with a non-existing key DOES NOT throw an exception.\n\n#### Configurable Objects\n\nAlso provided in this package is a _Configurable_ mixin:\n\n* `Charcoal\\Config\\ConfigrableInterface`\n* `Charcoal\\Config\\ConfigurableTrait`\n\nConfigurable objects (which could have been called \"_Config Aware_\") can have an associated Config object that can help define various properties, states, or other.\n\nThe Config object can be assigned with `setConfig()` and retrieved with `config()`.\n\nAn added benefit of `ConfigurableTrait` is the `createConfig($data)` method which is used to create a Config object if one is not assigned. This method can be overridden in sub-classes to customize the instance returned and whatever initial state might be needed.\n\nCheck out the [documentation](docs/configurable-objects.md) for examples and more information.\n\n## Resources\n\n* [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)\n* [Report issues](https://github.com/charcoalphp/charcoal/issues) and\n  [send pull requests](https://github.com/charcoalphp/charcoal/pulls)\n  in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fconfig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharcoalphp%2Fconfig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fconfig/lists"}