jasonterando/config-validator

Utility to collect and validate configuration information

0.1.0 2018-04-04 05:46 UTC

This package is not auto-updated.

Last update: 2024-03-17 02:37:06 UTC


README

Overview

This is an Autoload implemented utility that provides a mechanism to ensure that deployed configuration files meet the requirements of any dependencies. It is meant to be executed in development or at the time of deployment.

An application and/or its dependencies each define a configuration definition file. When the Configuration Validation utility is executed, the utility compares the Application Configuration versus and Configuration Definitions inlcuded in dependencies.

Currently, Configuration Definition files are located using directories included Autoload PSR-4 and Classmap directories. Application Configuration files are retrieved using Zend's module manager convention (module_listener_options/module_paths). It's envisioned that additional mechanisms to retrieve Configuration Definitions and Application Configurations will be added in the future.

Installation and Usage

Installation

To use this:

  1. Run composer require jasonterando/configuration-validator
  2. Add the composer script lines to composer.json
{
    "scripts": {
        "config-validate": "ConfigurationValidator\\Scripts::ConfigValidate",
        "config-save-template": "ConfigurationValidator\\Scripts::ConfigSaveTemplate"
    }
}

Usage

From the application's main directory, run composer config-validate to run the validation. If everything checks out, a success message will be displayed and the exit code will be zero.

If the validation fails, due to missing or invalid configuration entries, warnings will be displayed and the exit code will be -2.

If the validation cannot run due to a fatal error, the exception message will be displayed and the exit code will be -1.

If you need to create a configuration validation file from scratch, you can run composer config-save-template which will create a definition file, based upon the application's current configuration, that you can refine and include with your module/library. Note that this file will include all application configuration, so you will want to remove entries that aren't required by your specific module, and likely set some types, before moving the file to your module's folder.

Both of the Composer scripts shown above can be run with the debug argument to provide more information about what files are being accessed.

CI/CD Integration

During deployment, after installing/updating configuration files, run composer config-validate to validate the configuration. Any exit code other than zero should be treated as a failure and stop the deployment.

Configuration Definitions

Configuration Definition File Format

Configuration Definition files are in YAML format. They can be named config-definition.yaml or config-definition.yml, and located in any directory defined as a PSR-4 or Classmap path in an Autoload project's composer.json. For example:

service1:
   endpoint: url
   credentials:
      key: string
      secret: string
options:
   timeout:
      type: integer
      required: false
   logo: file
   logs: directory
   copyright

Every leaf in the tree corresponds to a Configuration Item, located with the hiearchy of its parent nodes. Configuration Items have two properties, type and required. By default, Configuration Items can be of any type, and are required.

In the example above, the final Configuration Item, "copyright" can be any value, but must exist in the Application Configuration. The "timeout" property is not requiredto exist in the Application Configuration file, but must be an integer (whole number) if it is.

There are two entries, "logo" and "logs" which must be an existing file and directory, respectively. Note that this check is done withing the user context that the test is run, which may not be the same as the context the application itself runs in, so this isn't a 100% foolproof check.

For "service1", its endpoint Configuration Item is required and must be a valid URL. The "key" and "secret" Configuration Items are required to be defined (under "credentials") and be non-empty strings.

For this example, a working configuration file may look something like this:

<?php
return [
   'service1' => [
       'endpoint' => 'https://foo.com/service1',
       'credentials' => [
           'key' => 'abc',
           'secret' => 'def'
       ]
   ],
   'options' => [
       'copyright' => '(c) Me 2018',
       'logo' => '/var/shared/company.jpg',
       'logs' => '/var/log/foo',
   ]
]

Configuration Definition Item Types

The following types are currently supported:

  • any: can be any value, including empty
  • string: can be anything that PHP can render as a string, but not empty
  • number: any numeric value
  • integer: any whole value (positive or negative) but without a decimal portion
  • boolean: any boolean-ish value (true/value, y/n, yes/no)
  • url: any well-structured URL
  • directory: an existing, accessible directory
  • file: an existing, accessible file

Development

Unit Testing

Unit tests, including code coverage, can be executed by running vendor/bin/phpunit from the library's main folder.

Todo's

  • Add support for PSR-0
  • Add support for other frameworks' Application Configuration file stores (Symphony?)
  • Add more aggressive location and/or configuration settings (somewhere) for things like Autoload and Application Configuration files