mwgg/i3phtatus

A dead simple extensible i3status replacement written in PHP

dev-master 2017-07-04 06:26 UTC

GPLv3

• mwgg

README

i3phtatus is an easily extensible i3status replacement meant for i3bar, written in PHP.

Usage

Replace your current "status_command" setting in ~/.i3/config with i3phtatus:

status_command php /opt/i3phtatus/i3phtatus.php

By default, i3phtatus will expect the config file to be at ~/.i3/i3phtatus.conf.php. If you wish to specify a different location, use the -c flag:

status_command php /opt/i3phtatus/i3phtatus.php -c ~/my_i3phtatus.conf.php

Configuration

Configuration is stored in a PHP array. There you can configure the refresh rate (in milliseconds before the information is updated), "good", "bad" and "warn" colors for modules requiring colored output, as well as individual modules options.

Modules are displayed in the same order as they appear in the config. Unnecessary modules may simply be commented out or removed from the config file.

"amixer_volume" => array(
    "module" => "amixer_volume",
    "mode" => "percent",
    "label" => "VOL: "
),
"amixer_volume_bar" => array(
    "module" => "amixer_volume",
    "mode" => "bar",
    "width" => 10
)

The example above will output |VOL: 68%|-||||||    -|

"Key" for a particular module may be anything, as long as they are all unique. Each module config section must have at least the module parameter, which corresponds to the function name of a particular module. Some modules require additional parameters.

Optional label parameter in the module configuration will prepend a label to the output.

Writing modules

Modules are PHP functions, their names must be prefixed with module_ and they are automatically loaded from the modules subfolder. Each module function shall accept one argument, containing the module options, as specified in the config file.

function module_uname($module_options) {
    return array(
        "full_text" => php_uname($module_options["mode"])
    );
}

All modules must return an array with at least a full_text element, containing the desired output. Should it be necessary to color the output, an element color should be added, containing a hex value. Standard "good", "bad" and "warn" colors are defined in the config file and may be referenced by adding the $config variable to the function scope:

function module_awesome_stuff($module_options) {
    global $config;
    return array(
        "full_text" => "my awesome module",
        "color" => $config["color_good"]
    );
}

Should a module require storing temporary data (such as last refresh time for modules that pull remote data and don't need to do so every second), a global array called $module_tmp may be used:

   ...
   global $module_tmp;
   $module_tmp["awesome_stuff"]["last_update"] = time();
   ...

Pronunciation guide