Config

You'll probably also want to do some configuration. The framework supports two primary sources of configuration, the YAML configuration files, or the environment overrides.

The app.yml config files are mostly intended to be checked into version control and set up basic configuration. The env overrides are intended for sensitive configuration required for the deployments themselves, in particular for containerized environments.

A good rule of thumb is to make sure that your baseline app.yml configuration is all that is needed to actually start your API, this will make onboarding new developers much easier.

Cheatsheet

Quick overview of the configuration sources, and the load order from lowest to highest precedence.

Source	Description
./app.yml	Default configuration, should always be in version control.
./app.[profile].yml	Configuration for a specific environment, should probably be in version control.
./app.[profile].local.yml	Local overrides for a specific environment, should not be in version control.
System Environment	Environment variables have the highest precedence, use these for deployments.

TIP

Looking for .env files? In cloud environments there are several toolchains to build environment variables based on .env/.properties files for deployment pipelines, we recommend leveraging those to dynamically build your environment overrides instead.

Config options

The configuration system leverages Sugoi's internal DTO parsing and schema registry. This means you can generate complete schemas for all configuration classes in the code-base, including third-party.

./app dump:config

$schema: .sugoi/app.schema.json # Refer to the dumped configuration schema for full auto-complete and documentation.

sugoi:
    application:
        name: my-namespace-api # Application name to show in the log output
        prod: false # Production mode
    http:
        address: 0.0.0.0 # Address to bind to, generally should be kept to 0.0.0.0 for non-windows environments.
        port: 8080 # Override the default port.
        path: /api # Relative base path for the entire service.
    database: # Optional, configures the Illuminate DB Facade for you.
        driver: pgsql
        host: localhost
        port: 5432
        database: sugoi
        username: sugoi
        password: secret
    messaging: # Optional, messaging/broker configuration.
        kafka: # Kafka is already here!
            brokers: localhost:9092
            group-id: my-namespace-api
    swagger-ui: # Optional, if you'd like to customize Swagger-UI
        display-operation-id: false

Environment overrides can be applied through UPPER_CASE variable names and are automatically parsed on startup. Dashes should also be replaced by underscores.

SUGOI_APPLICATION_NAME=my-namespace-api-001
SUGOI_HTTP_PORT=3000
SUGOI_SWAGGER_UI_DEEP_LINKING=false

Custom config options

Need your own configuration options? These are simple to add, all you need to do add a configuration data class and annotate it with the Config attribute. That's it! Now this class will be automatically parsed and validated on startup, and the config can be injected on demand.

Make sure to namespace configuration using the prefix, this way you'll avoid conflicts later down the line.

All configuration is piped through the same DTO parsing and schema registry regardless of where it came from. This means if you use the Tensei DTO / Schema attributes you can properly document all your configuration, and it will be included in the ./app dump:config schemas.

#[Config(prefix: 'myapi.myorder')
readonly class MyOrder {
    public function __construct(
        #[Property(example: 'Pizza', required: true)]
        public string $dish,
        public int $cost,
        public ?string $optional,
        public bool $noPickles = true,
    ) {
    }
}

To supply your configuration, simply add it to the relevant app.yml file, or supply it through the environment.

sugoi:
    application:
        name: my-namespace-api
myapi:
    myorder:
        dish: Cheeseburger
        cost: 70
        no-pickles: false