Utopia Config

Important

This repository is a read-only mirror of the utopia-php monorepo. Development happens in packages/config — please open issues and pull requests there.

Utopia Config library is simple and lite library for managing application configuration. This library is aiming to be as simple and easy to learn and use. This library is maintained by the Appwrite team.

Although this library is part of the Utopia Framework project it is dependency free and can be used as standalone with any other PHP project or framework.

Getting started

Install using Composer:

composer require utopia-php/config

<?phprequire_once'./vendor/autoload.php';
useUtopia\Config\Parser\JSON;
useUtopia\Config\Attribute\Key;
useUtopia\Config\Config;
useUtopia\Config\Exception\Load;
useUtopia\Config\Exception\Parse;
useUtopia\Config\Source\File;
useUtopia\Validator\ArrayList;
useUtopia\Validator\Integer;
useUtopia\Validator\JSONasJSONValidator;
useUtopia\Validator\Nullable;
useUtopia\Validator\Text;
class DatabaseConfig
{
#[Key('db.host', newText(length: 1024), required: true)]
publicstring$host;
#[Key('db.port', newInteger(loose: true), required: false)]
public ?int$port;
#[Key('db.username', newText(length: 1024), required: true)]
publicstring$username;
#[Key('db.password', newText(length: 1024), required: true)]
publicstring$password;
#[Key('db.name', newNullable(newText(length: 1024)), required: true)]
public ?string$name;
/** * @var array<string, mixed> $config */
#[Key('db.config', newNullable(newJSONValidator), required: true)]
public ?array$config;
/** * @var array<string> $whitelistIps */
#[Key('db.whitelistIps', newArrayList(newText(length: 100), length: 100), required: true)]
publicarray$whitelistIps;
}
$source = newFile(__DIR__.'/config.json');
$parser = newJSON();
try {
$config = Config::load($source, $parser, DatabaseConfig::class);
} catch (Load$err) {
exit('Config could not be loaded from a file: ' . $err->getMessage());
} catch (Parse$err) {
exit('Config could not be parsed as JSON: ' . $err->getMessage());
}
\var_dump($config);
// $config->host// $config->port// $config->username// ...

For above example to work, make sure to setup config.json file too:

{
"db": {
"host": "127.0.0.1",
"port": 3306,
"username": "root",
"password": "password",
"name": "utopia",
"config": {
"timeout": 3000,
"handshakeTimeout": 5000
},
"whitelistIps": [
"127.0.0.1",
"172.17.0.0/16"
]
},
}

Notice dot notation is supported, and automatically finds nested objects.

Alternatively, you can load configs directly from a variable:

<?phprequire_once'./vendor/autoload.php';
useUtopia\Config\Attribute\Key;
useUtopia\Config\Config;
useUtopia\Config\Source\Variable;
useUtopia\Config\Parser\None;
useUtopia\Validator\Whitelist;
class FirewallConfig
{
#[Key('security-level', newWhitelist('high', 'low'), required: true)]
publicstring$securityLevel;
}
$config = Config::load(
source: newVariable([
'security-level' => 'high',
]),
parser: newNone(),
FirewallConfig::class
);
\var_dump($config);
// $config->securityLevel

Below is example how to combine multiple configs into one:

<?phpclass FirewallConfig
{
/** * @var array<string> $allowIps */
#[Key('ALLOW_IPS', newArrayList(newText(length: 100), length: 100), required: true)]
publicarray$allowIps;
#[Key('CAPTCHA', newWhitelist(['enabled', 'disabled']), required: true)]
publicstring$captcha;
}
class CredentialsConfig
{
#[Key('DATABASE_PASSWORD', newText(length: 1024), required: true)]
publicstring$dbPass;
#[Key('CACHE_PASSWORD', newText(length: 1024), required: true)]
publicstring$cachePass;
}
class EnvironmentConfig
{
#[Key('RATE_LIMIT_HITS', newInteger(loose: true), required: true)]
publicint$abuseHits;
#[Key('RATE_LIMIT_SECONDS', newInteger(loose: true), required: true)]
publicint$abuseTime; }
class AppConfig
{
#[ConfigKey]
publicFirewallConfig$firewall;
#[ConfigKey]
publicCredentialsConfig$credentials;
#[ConfigKey]
publicEnvironmentConfig$environment;
}
$config = Config::load(
newVariable([
'firewall' => Config::load(newFile('firewall.json'), newJSON(), FirewallConfig::class),
'credentials' => Config::load(newFile('credentials.yml'), newYAML(), CredentialsConfig::class),
'environment' => Config::load(newFile('.env'), newDotenv(), EnvironmentConfig::class),
]),
newNone(),
AppConfig::class
);
\var_dump($config);
// $config->firewall->allowIps// $config->credentials->dbPass// $config->environment->abuseHits

You can also load environment variables instead of reading dotenv file:

<?phpuseUtopia\Config\Config;
useUtopia\Config\Source\Environment;
useUtopia\Config\Parser\None;
class CredentialsConfig
{
#[Key('DATABASE_PASSWORD', newText(length: 1024), required: true)]
publicstring$dbPass;
#[Key('CACHE_PASSWORD', newText(length: 1024), required: true)]
publicstring$cachePass;
}
$config = Config::load(newEnvironment(), newNone(), CredentialsConfig::class);
\var_dump($config);
// $config->dbPass// $config->$cachePass

System requirements

Utopia Framework requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.

When using YAML adapter, or running tests with it, you need to install the YAML extension for PHP.

Copyright and license

The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php