PHPackages                             clue/confgen - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. clue/confgen

ActiveLibrary[Utility & Helpers](/categories/utility)

clue/confgen
============

Configuration file generator (confgen) – an easy way to generate structured (configuration) files on the fly by processing a Twig template and an arbitrary input data structure.

v0.6.0(8y ago)112707[7 issues](https://github.com/clue/php-confgen/issues)MITPHPPHP >=5.3CI failing

Since Jul 20Pushed 4y ago5 watchersCompare

[ Source](https://github.com/clue/php-confgen)[ Packagist](https://packagist.org/packages/clue/confgen)[ Docs](https://github.com/clue/php-confgen)[ RSS](/packages/clue-confgen/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (6)Dependencies (4)Versions (7)Used By (0)

clue/confgen
============

[](#clueconfgen)

[![Build Status](https://camo.githubusercontent.com/c86420e430232aed6ab81fcfbe938469ba5a4a0d27ab21e998ff4c83d03b3dc7/68747470733a2f2f7472617669732d63692e6f72672f636c75652f636f6e6667656e2e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/clue/confgen)[![installs on Packagist](https://camo.githubusercontent.com/a35fa9c013fb0e10b21e7d49384408972c8a176ba87c508e19f4e01793e80a33/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636c75652f636f6e6667656e3f636f6c6f723d626c7565266c6162656c3d696e7374616c6c2532306f6e2532305061636b6167697374)](https://packagist.org/packages/clue/confgen)

Configuration file generator (confgen) – an easy way to generate structured (configuration) files on the fly by processing a *Twig template* and an arbitrary input data structure.

**Table of contents**

- [Input data](#input-data)
- [Templates](#templates)
- [Meta variables](#meta-variables)
- [Configuration](#configuration)
- [Bin Usage](#bin-usage)
- [Lib Usage](#lib-usage)
    - [Factory](#factory)
        - [Twig\_Environment](#twig_environment)
        - [createConfgen()](#createconfgen)
    - [Confgen](#confgen)
        - [processTemplate()](#processtemplate)
        - [processDefinition()](#processdefinition)
- [Install](#install)
- [Tests](#tests)
- [License](#license)

Input data
----------

[](#input-data)

This project is all about transforming *your input data* structure.

As such, it makes no assumptions as to what kind of input data you're dealing with, as long as it can be expressed in a simple JSON structure. This project focuses on JSON input data for a few key reasons:

- Arbitrary data structure
    - Can contain pretty much any data structure
    - Simple, sane, strict data types
    - Flat or deeply nested structures
    - Schemaless by default – but offers options for using schema
- Ease of consuming (simple to read)
    - For both humans and machines alike
    - Easy to reason about
    - Maps well into dotted notation used in template files
- Ease of producing (simple to write)
    - Simple to convert into from many other common formats, such as YAML, XML, CSV, INI etc.
    - Very easy to write in PHP and many other languages
- Widespread use

Chances are, your input data *might* already be in a JSON file. If it's not, then it's very easy to either convert with one of the many existing tools or libraries or use some code similar to the following example:

```
// $data = loadFromYaml('input.yml');
// $data = parseFromIni('input.ini');
$data = fetchFromDatabase();
file_put_contents('data.json', json_encode($data));
```

The structure of your input data file is entirely left up to you. This library allows you to use any arbitrary input data structure. For the following examples, this document assumes the following (totally arbitrary) input data structure:

```
{
    "timeout": 120,
    "interfaces": [
        {
            "name": "eth0",
            "address": "192.168.1.1"
        }
    ]
}
```

Templates
---------

[](#templates)

Each (configuration) template file is essentially a plaintext (output) configuration file with some placeholders.

The template file uses the *Twig template language* and can hence take full advantage of its variable substitution and advanced template control logic.

In its most simple form, an arbitrary template would look something like this:

```
timeout = {{ data.timeout }}
{% for interface in data.interfaces %}
auto {{ interface.name }}
    address {{ interface.address }}
{% endfor %}

```

The input variables will be accessible under the `data` key.

You can generate the output (configuration) file by [invoking confgen](#bin-usage) like this:

```
$ confgen -t template.twig -d data.json
```

In this example, it will write the resulting file to the template file name without extension (i.e. `template`).

With the above example template and input data, the resulting output (configuration) file will look something like this:

```
timeout = 120
auto eth0
    address 192.168.1.1

```

Meta variables
--------------

[](#meta-variables)

Optionally, you can prefix the template file contents with the meta-data in the form of a YAML front matter. This syntax is quite simple and is pretty common for template processors and static site generators such as [Jekyll](http://jekyllrb.com/docs/frontmatter/).

This means that if you want to include *meta-data* variables, then each section starts with a three-hyphen divider (`---`), so that a full file would look something like this:

```
---
target: /etc/network/interfaces
chmod: 644
reload: /etc/init.d/networking reload
---
timeout = {{ data.timeout }}
{% for interface in data.interfaces %}
auto {{ interface.name }}
    address {{ interface.address }}
{% endfor %}

```

Documented variables:

- `target` target path to write the resulting file to. Can be an abolute or relative path that will be resolved relative to the directory confgen is called in (i.e. not relative to this template file).
- `chmod` file permissions (decimal) for the target file
- `reload` command to execute after writing the target file
- `description` human readable description

You can also pass arbitrary custom meta-data. See [meta-data schema](res/schema-template.json) for more details.

The meta variables will be accessible under the `meta` key in the Twig template. If no *meta-data* variables are present, then this key defaults to an empty array.

You can generate the output (configuration) file by [invoking confgen](#bin-usage) like this:

```
$ confgen -t template.twig -d data.json
```

If the [template meta-data](#meta-variables) contains a `target` key, it will write the resulting file to this location.

In the above example, this means the following actions will be performed:

- Write output (configuration) file to `/etc/network/interfaces`
- Set file permissions to `0644`
- Execute the reload script `/etc/init.d/network restart`

Sometimes it is useful to skip the execution of the scripts/commands defined by the meta variable `reload`. To do so you can use the optional parameter `--no-scripts` like this:

```
$ confgen --no-scripts -t template.twig -d data.json
```

Configuration
-------------

[](#configuration)

You can either parse/process individual template files or use a configuration definition that allows you to process a number of files in one go.

In its most simple form, a JSON configuration structure looks like this:

```
{
    "templates": "example/*.twig"
}
```

Documented variables:

- `templates`Can be an absolute or relative path that will be resolved relative to this definition (i.e. not necessarily the $PWD)

See [configuration schema](res/schema-confgen.json) for more details.

You can generate the output (configuration) files by [invoking confgen](#bin-usage) like this:

```
$ confgen [--no-scripts] -c confgen.json -d data.json
```

This works similar to invoking with individual [template files](#templates).

Bin Usage
---------

[](#bin-usage)

Once [installed](#install), you can use this tool as a bin(ary) executable.

Some usage examples are given above.

If you want to see the usage help, simply invoke its help by calling like this:

```
$ confgen
```

If you have installed this via `$ composer require`, then you may have to invoke it like this:

```
$ ./vendor/bin/confgen
```

Lib Usage
---------

[](#lib-usage)

See the above section for [bin usage](#bin-usage) which is usually easier to get started.

If you want to integrate this into another tool, you may also use this project as a lib(rary). The same also applies if you want to use custom twig extensions, functions or filters.

### Factory

[](#factory)

The `Factory` class is a helper class that can be used to *easily* create a new `Confgen` instance.

```
$factory = new Factory();
```

#### Twig\_Environment

[](#twig_environment)

Internally, the `Factory` will create a `Twig_Environment` instance that will be used to process the template files.

You may want to explicitly pass an instance if you want to use any of the following:

- custom twig extensions
- custom twig functions
- custom twig filters

```
$twig = new Twig_Environment();
$twig->addFilter(new Twig_SimpleFilter('backwards', function ($value) {
    return strrev($value);
});

$factory = new Factory($twig);
```

#### createConfgen()

[](#createconfgen)

The `createConfgen()` method can be used to create a new `Confgen` instance. Usually, there should be no need to call this more than once.

```
$confgen = $factory->createConfgen();
```

### Confgen

[](#confgen)

The `Confgen` class is responsible for processing the templates (*this is where the magic happens*).

#### processTemplate

[](#processtemplate)

The `processTemplate($templateFile, $dataFile)` method can be used to generate a output (configuration) file from the given [template file](#templates).

```
$confgen->processTemplate('template.twig', 'data.json');
```

The `processTemplate($templateFile, $dataFile)` method throws a `RuntimeException` when a `reload` command fail. See also [Meta variables](#meta-variables) section for more details on `reload`.

See also [templates section](#templates) above for more details on the The [input data](#input-data).

#### processDefinition

[](#processdefinition)

The `processDefinition($definitionFile, $dataFile)` method can be used to generate any number of output (configuration) files from the given [configuration file](#configuration).

```
$confgen->processDefinition('confgen.json', 'data.json');
```

The `processDefinition($definitionFile, $dataFile)` method throws a `RuntimeException` when a `reload` command fail. See also [Meta variables](#meta-variables) section for more details on `reload`.

See also [configuration section](#configuration) above for more details.

Install
-------

[](#install)

You can simply download a pre-compiled and ready-to-use version as a Phar to any directory. Simply download the latest `confgen.phar` file from our [releases page](https://github.com/clue/confgen/releases):

[Latest release](https://github.com/clue/confgen/releases/latest)

That's it already. You can now verify everything works by running this:

```
$ cd ~/Downloads
$ php confgen.phar -h

$ chmod +x confgen.phar
$ sudo mv confgen.phar /usr/local/bin/confgen
```

Alternatively, you can also use this project as a library to integrate this into an existing application. The recommended way to install this library is [through Composer](https://getcomposer.org). [New to Composer?](https://getcomposer.org/doc/00-intro.md)

```
$ composer require clue/confgen:^0.6
```

This project aims to run on any platform and thus does not require any PHP extensions and supports running on legacy PHP 5.3 through current PHP 7+. It's *highly recommended to use PHP 7+* for this project.

> If you want to create the above `confgen.phar` locally, you have to clone this repository and run `composer build`.

Tests
-----

[](#tests)

To run the test suite, you first need to clone this repo and then install all dependencies [through Composer](http://getcomposer.org):

```
$ composer install
```

To run the test suite, go to the project root and run:

```
$ php vendor/bin/phpunit
```

License
-------

[](#license)

MIT

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance7

Infrequent updates — may be unmaintained

Popularity21

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 91.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~170 days

Recently: every ~212 days

Total

6

Last Release

3105d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/776829?v=4)[Christian Lück](/maintainers/clue)[@clue](https://github.com/clue)

---

Top Contributors

[![clue](https://avatars.githubusercontent.com/u/776829?v=4)](https://github.com/clue "clue (64 commits)")[![SimonFrings](https://avatars.githubusercontent.com/u/44357440?v=4)](https://github.com/SimonFrings "SimonFrings (3 commits)")[![carusogabriel](https://avatars.githubusercontent.com/u/16328050?v=4)](https://github.com/carusogabriel "carusogabriel (2 commits)")[![PaulRotmann](https://avatars.githubusercontent.com/u/85174210?v=4)](https://github.com/PaulRotmann "PaulRotmann (1 commits)")

---

Tags

confgenConfiguration generatorTwig templateYAML front matter

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/clue-confgen/health.svg)

```
[![Health](https://phpackages.com/badges/clue-confgen/health.svg)](https://phpackages.com/packages/clue-confgen)
```

###  Alternatives

[stfalcon/tinymce-bundle

This Bundle integrates TinyMCE WYSIWYG editor into a Symfony2 project.

2692.9M24](/packages/stfalcon-tinymce-bundle)[codefog/contao-haste

haste extension for Contao Open Source CMS

42650.8k139](/packages/codefog-contao-haste)[netgen/layouts-core

Netgen Layouts enables you to build and manage complex web pages in a simpler way and with less coding. This is the core of Netgen Layouts, its heart and soul.

3689.4k10](/packages/netgen-layouts-core)[spomky-labs/pwa-bundle

Progressive Web App Manifest Generator Bundle for Symfony.

6144.4k1](/packages/spomky-labs-pwa-bundle)[leapt/core-bundle

Symfony LeaptCoreBundle

2529.1k4](/packages/leapt-core-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)