Using augeas (in PHP)

Warning: This blogpost has been posted over two years ago. That is a long time in development-world! The story here may not be relevant, complete or secure. Code might not be complete or obsoleted, and even my current vision might have (completely) changed on the subject. So please do read further, but use it with caution.
Posted on 04 Jun 2012
Tagged with:

Even though I really like using sed and awk, sometimes its hard to change or add parameters in configuration files. Big sed statements that may or may not work, double checking if everything has been done correctly etc. Augeas is a really cool tool that lets you view / add / modify and delete all kind of data from configuration files. If you are using Puppet, you are probably aware of this tool, but I notice that a lot of PHP developers have never heard of it.. Let’s explore..

So Augeas is a very cool library that has a command line interface (augtool) and lots of bindings, including a PHP binding. To install, simply install it through the PECL library by using a “pecl install augeas”, or maybe a “pecl install augeas-0.6.1”.

A big array of all your /etc settings

Basically augeas makes a big array of all your configuration settings, which normally live in /etc/, but can be other directories as well if you like. For instance, suppose you want to explore the entries inside my host file. To be exact, I want to see the third line in my hostfile:

jthijssen@debian-jth:~$ augtool ls /files/etc/hosts/3
ipaddr = ::1
canonical = localhost
alias[1] = ip6-localhost
alias[2] = ip6-loopback

As you can see, my third host entry from /etc/hosts has got an ip(v6) address of ::1, canonical name of localhost and 2 aliases. Sounds about right, since this is a snippet of my actual host file:    localhost    debian-jth

# The following lines are desirable for IPv6 capable hosts
::1     localhost ip6-localhost ip6-loopback
fe00::0 ip6-localnet
ff00::0 ip6-mcastprefix

Let’s change our second alias:

augtool -s set /files/etc/hosts/3/alias[2] ipv6host

If the command didn’t work, it’s most probably because you have a 0.7.x version of augeas/augtool. Try to upgrade to at least 0.8, or try it this way:

echo -e "set /files/etc/hosts/3/alias[2] ipv6host \n save \n " | sudo augtool

This is because the “save” functionality does not exists in the older versions, and you are not able to update your files without the save (mutations happen in memory only and need to be flushed to disk with the save command). By using the interactive shell from augtool (just start it without any arguments), you can easily input commands for yourself.

Inserting new “data” is easy as well. With the “ins” command you can create room for a new variable, and afterwards set it with the “set” command just like above. Easy!

Using augeas in PHP

Since augeas has got many binding, including one for PHP, it’s easy to use it inside your own applications as well:

$au = new Augeas();
print $au->get("/files/etc/php.ini/Date/date.timezone");
$au->set("/files/etc/php.ini/Date/date.timezone", "America/New York");

This would print “Europe/Amsterdam” in my case. Again, the PHP bindings has mapped most of the functionality from the underlying library, so you can get/set/insert/move/delete and off course search your configuration files.

Using your own configuration structure

Augeas makes uses of “lenses”, which basically are simple parsers for your configuration to turn the specific configuration into an array. As long as the lens for your specific configuration structure is present, you can use it with augeas. But it doesn’t have to stop at configuration. It might be possible (although I haven’t tested it yet) to do other stuff with it: how about having your PHP class files and be able to add/insert new methods. For more information, see documentation at