graste/environaut

Define, configure and protect your application environment and its requirements.

0.5.3 2015-08-31 09:44 UTC

This package is auto-updated.

Last update: 2024-03-04 22:02:49 UTC


README

  • Latest Version: Latest Stable Version
  • Build: Build Status

Please have a look at the available releases.

Purpose

Environaut should enable and help developers to define the environment of an application and check if all defined constraints are met. This includes assertions and requirements of the application environment as well as some configuration that may be necessary to make an application run. See the docs/ folder or the wiki for more information.

When you plan to use Environaut to create settings files for your application please skip to the Requirements and installation section.

Quickstart for curious users

  1. Download the environaut.phar file of the release you prefer
  2. Make it executable via chmod u+x environaut.phar
  3. Run ./environaut.phar check
  4. Notice the error message for a missing configuration file
  5. Create a minimal config file (e.g. as xml or json) next to the environaut.phar file.
  6. Run ./environaut.phar check again (with --config ... if the file is not named environaut.(xml|json|php))
  7. Notice the output and created settings and cache file that is used when you run Environaut another time.

Short introduction for interested developers

Environaut parses a configuration file that contains defined environment checks. After that, each check is processed and the results of each check are compiled into a report. Each check can emit messages and settings. The messages will be printed to the shell and the settings can be exported in specified formats.

For a verbose example configuration file do this:

  1. Clone this repository and change into that directory
  2. Run make install-dependencies-dev
  3. Run bin/environaut check

Notice the checks and questions and that there's an environaut-config.xml afterwards in your working directory. Change the sample environaut.xml to use environaut-config.json instead of the XML variant as the settings export formatter and re-run the checks to get your settings as JSON.

Requirements and installation

  • Non-Windows operating system (tested on Ubuntu 12.04/13.04 and MacOS X)
  • PHP v5.3+
  • libxml when XML configuration files are used

There are multiple ways to use and run environaut:

  • download and use the PHAR file
  • install via Composer CLI
  • install via Composer (composer.json)

PHAR

The easiest way to use environaut is to download the environaut.phar of the latest stable release, make it executable and put a configuration file next to the php archive and then run ./environaut.phar check

Composer CLI

Install Environaut via Composer:

  1. Install Composer (if it's not already installed or available via PATH environment): curl -sS https://getcomposer.org/installer | php.
  2. Install Environaut: ./composer.phar require graste/environaut [optional version]
  3. Create a Environaut configuration file (see environaut.xml or examples)
  4. Run it: ./vendor/bin/environaut.phar check

Composer project vendor dependency

Another way to install Environaut is via composer as a vendor dependency of your project. Create or update a composer.json file and run the php composer.phar install command to get Environaut:

{
    "require": {
        "graste/environaut": "~0.5"
    }
}

Alternatively, you can download the environaut.zip file and extract it. The bin/environaut.phar file is a standalone and self-executable binary.

$ environaut.phar --help

When you got environaut.phar by cloning this repository it should already be executable. Otherwise chmod u+x environaut.phar should be sufficient to make it work. It is advisable to have a php executable available via the PATH environment variable as the phar uses a #!/usr/bin/env php shebang. Use something like alias php="/usr/local/bin/php53" if your executable is not in the PATH. To get the Makefile working you can try a simple export PHP_PATH = "/usr/local/bin/php53" as that will be used instead of the default php for make.

Usage examples

You may combine multiple commandline options:

environaut.phar help check
environaut.phar check --verbose --profile
environaut.phar check --config path/to/environaut.json
environaut.phar check --autoload-dir path/to/custom/files/src
environaut.phar check --no-cache

The check commandline options are:

  • --autoload-dir="…" (-a): Folder for autoloading of custom .php classes.
  • --config="…" (-c): Path to configuration file with check definitions.
  • --config-handler="…": Namespaced classname of custom IConfigHandler (will be autoloaded from the autoload_dir).
  • --include-path="…" (-i): Path to prepend to PHP include_path.
  • --bootstrap="…" (-b): File to require before running the checks.
  • --no-cache: Don't read, write or use cache files (Disables caching).
  • --cache-location="…": Read and write cache from and to that file.

Other available and useful options are:

  • --verbose (-v): Increase the verbosity of messages.
  • --version (-V):` Display Environaut version.
  • --ansi: Force ANSI output.
  • --no-ansi Disable ANSI output.
  • --profile Display timing and memory usage information.

For the help command the following works:

  • --xml: To output help as XML.
  • --format: To output help in other formats.
  • --raw: To output raw command help.
  • --help (-h): Display the help message.

Documentation

Checks can be configured via configuration files and settings may afterwards be exported via different formatters into different formats.

Supported (input) configuration file formats:

  • XML
  • JSON
  • PHP

Supported (output) settings file formats:

  • XML (agavi xml config format; can be customized via template strings)
  • JSON (json object literal)
  • PHP (settings as array to include)
  • SH (shell variables in a file that may be sourced)
  • TEXT (settings with or without their group name in a plain text file)

The input and output file formats may be completely customized by replacing the default classes with custom implementations.

Community

None, but you may join the freenode IRC #honeybee channel anytime. :-)

Please contribute by forking and sending a pull request. More information can be found in the CONTRIBUTING.md file.

Contributors

See AUTHORS.md for a list of contributors.

Changelog

See CHANGELOG.md for more information about changes.

License

MIT license – see linked license for details.

  • Total Composer Downloads: Composer Downloads