configlib/README.md

ConfigLib

ConfigLib is a PHP library for managing configuration files and storing it in NCC's data, while providing a command line interface for running functions such as editing configuration files inline or importing/exporting configuration files.

One of the biggest advantages of using something like ConfigLib is that it will allow for more complicated software to be configured more easily by following the documented instructions on how to alter configuration files, optionally you could use a builtin editor to edit the configuration file manually.

Community

This project and many others from Nosial are available on multiple publicly available and free git repositories at

• n64
• GitHub
• Codeberg

Issues & Pull Requests are frequently checked and to be referenced accordingly in commits and changes, Nosial remains dedicated to keep these repositories up to date when possible.

For questions & discussions see the public Telegram community at @NosialDiscussions. We do encourage community support and discussions, please be respectful and follow the rules of the community.

Table of contents

• ConfigLib
  • Community
  • Table of contents
  • Installation
  • Compile from source
  • Requirements
  • Documentation
    • Storage Location
    • Creating a new configuration file
    • Setting default values
  • Command-line usage
    • Exporting a configuration file
    • Importing a configuration file
    • Editing a configuration file
      • Using an external editor
      • Inline command line editor
    • Environment Variables
      • Importing a YAML file
      • Overriding configuration values
  • License

Installation

The library can be installed using ncc:

ncc install -p "nosial/libs.config=latest@n64"

or by adding the following to your project.json file under the build.dependencies section:

{
  "name": "net.nosial.configlib",
  "version": "latest",
  "source_type": "remote",
  "source": "nosial/libs.config=latest@n64"
}

If you don't have the n64 source configured, you can add it by running the following command:

ncc source add --name n64 --type gitlab --host git.n64.cc

Compile from source

To compile the library from source, you need to have ncc installed, then run the following command:

ncc build

Requirements

The library requires PHP 8.0 or higher.

Documentation

ConfigLib is both a library and a command line tool, the library can be used within your program to create a new configuration file and load in default entries, either on the first run or automatically during the installation process.

The goal to ConfigLib is to make it easy to setup configuration parameters for your program and to make it easy for a user to edit the configuration file without having to manually edit the file. This part of the documentation will explain both how to implement the library into your program and how to use the command line tool to edit the configuration file.

Storage Location

Configuration files are stored as json files in the data directory of ConfigLib which is located at /var/ncc/data/net.nosial.configlib, this directory is created automatically when the library is installed.

Creating a new configuration file

To create a new configuration file, you can create a new \ConfigLib\Configuration() object and pass in the name of the configuration file, for example:

require 'ncc';
import('net.nosial.configlib');

$config = new \ConfigLib\Configuration('myconfig');

This will only initialize the object, to save the configuration file you need to call the save() method:

$config->save();

Setting default values

You can set default values for the configuration file which will be created if the values do not exist in the configuration file,

require 'ncc';
import('net.nosial.configlib');

$config = new \ConfigLib\Configuration('com.symfony.yaml');

$config->setDefault('database.host', '127.0.0.1');
$config->setDefault('database.port', 3306);
$config->setDefault('database.username', 'root');
$config->setDefault('database.password', null);
$config->setDefault('database.name', 'test');

$config->save();

Command-line usage

The command line interface can be executed by running configlib from the command line or by running ncc exec --package="net.nosial.configlib if configlib isn't in your global path.

For the rest of this documentation, we will assume that you have the configlib command in your global path.

Exporting a configuration file

To export a configuration file, run the following command:

configlib --config <config_name> --export <filename>

Exported configuration files are stored as YAML files.

Note: if the filename is not specified, the configuration file will be exported to the current working directory with the name <config_name>.yaml

Importing a configuration file

To import a configuration file, you must specify a valid yaml file, run the following command:

configlib --config <config_name> --import <filename>

Editing a configuration file

There are two ways to edit a configuration file using ConfigLib

1. Using an external editor
2. Inline command line editor

Using an external editor

When you use an external editor, ConfigLib will create a temporary YAML file and open it in the specified editor, when you save and close the file, ConfigLib will parse the YAML file and save the configuration file. If the YAML file is invalid, ConfigLib will not save the configuration file.

This is the recommended way to edit configuration files as it allows you to use your preferred editor and it allows you to use the full power of YAML.

To edit a configuration file using an external editor, run the following command:

configlib --config <config_name> --editor nano

Note: Changes will only be applied if you save the file and close the editor.

Inline command line editor

The inline command line editor is a simple editor that allows you to edit the configuration file from the command line, this is useful for automated scripts.

To view the contents of a configuration file, run the following command:

configlib --config <config_name>

To view the value of a specific property, use the --property option:

configlib --config <config_name> --property database.username

To edit a property, specify both the --property and --value options:

configlib --config <config_name> --property database.username --value root

Environment Variables

ConfigLib can be interacted with using environment variables with two functions

• Import a YAML file
• Override configuration values

Importing a YAML file

You can tell ConfigLib to load a YAML file by setting the CONFIGLIB_<CONFIG_NAME> environment variable with the path to the YAML file as the value, for example:

export CONFIGLIB_MYCONFIG=/path/to/myconfig.yaml

Overriding configuration values

If loading an entire YAML file is too much, you can override specific configuration values by setting the environment variable CONFIGLIB_<CONFIG_NAME>_<PROPERTY_NAME> with the value you want to set, for example:

export CONFIGLIB_MYCONFIG_DATABASE_USERNAME=root

This would override the database.username property in the myconfig configuration file even if the property is already set, the environment variable will take precedence.

License

This project is licensed under the MIT License - see the LICENSE file for details