Build graphical desktop (GUI) applications in PHP
Clone or download
clue Merge pull request #51 from andreybolonin/patch-1
Improve test suite by testing against PHP 7.2
Latest commit 2b9ef12 Jul 4, 2018

README.md

clue/zenity-react Build Status

Zenity is a small program that allows creating simple GTK+ dialogs from within command line scripts. This library provides an easy to use wrapper to spawn Zenity processes to build graphical desktop applications with PHP.

Zenity already ships with Ubuntu-based distributions and does not require any installation there - so this library should work out of the box. Otherwise you may have to install Zenity yourself.

https://help.gnome.org/users/zenity/stable/question.html

Table of contents

Quickstart example

Once installed, you can use the following code to open a prompt asking the user for his name and presenting it in another info dialog.

$loop = Factory::create();
$launcher = new Launcher($loop);

$entry = new EntryDialog();
$entry->setText('What\'s your name?');
$entry->setEntryText(getenv('USER')); // prefill with current user

$launcher->launch($entry)->then(function ($name) use ($launcher) {
    $launcher->launch(new InfoDialog('Welcome to zenity-react, ' . $name .'!'));
});

$loop->run();

Looking for more examples? Take a look at the examples folder.

Usage

Launcher

As shown in the above example, a Launcher has to be instantiated once and is responsible for launching each Zenity dialog. It manages running the underlying zenity process and reports back its state and user interaction.

It uses the react/event-loop component to enable an async workflow where you can launch multiple dialogs while simultaneously doing more I/O work. This library exposes both a simple blocking API and a more advanced async API.

$loop = React\EventLoop\Factory::create();
$launcher = new Launcher($loop);

setBin()

For launching the process it assumes your zenity binary is located in your system $PATH. If it's not, you can explicitly set its path like this:

$launcher->setBin('/some/other/path/zenity');

waitFor()

The waitFor($dialog) method can be used to launch a given dialog and wait for the Zenity process to return its result. This simple blocking API allows you to get started quickly without exposing all nifty async details - and lacking some of its advanced features:

$result = $launcher->waitFor($dialog);

launch()

The launch($dialog) method can be used to asynchronously launch a given dialog and return a Promise that will be fulfilled when the Zenity process returns. This async API enables you to launch multiple dialogs simultaneously while simultaneously doing more I/O work.

$launcher->launch($dialog)->then(
    function ($result) {
        // info dialogs complete with a boolean true result
        // text dialogs complete with their respective text
    },
    function ($reason) {
        // dialog was cancelled or there was an error launching the process
    }
});

launchZen()

The launchZen($dialog) method can be used to asynchronously launch a given dialog and return an instance of the BaseZen class. This instance exposes methods to control the Zenity process while waiting for the results. Some dialog types also support modifying the information presented to the user.

$zen = $launcher->launchZen($dialog);
$loop->addTimer(3.0, function () use ($zen) {
    $zen->close();
});

$zen->promise()->then(function ($result) {
    // dialog completed
});

Mixing synchronous and asynchronous PHP

ReactPHP expects all PHP to be non-blocking. Therefore it's not easily possible to use launch or launchZen followed by regular blocking events in PHP. Currently there is a simple but dirty workaround. It's possible to manually tick the loop to have changes on zen-objects take effect.

$progress = new ProgressDialog('Step 1');
$progress->setPulsate(TRUE);
$progress->setAutoClose(TRUE);
$progress_zen = $launcher->launchZen($progress);

// This regular command is blocking and breaks the asynchronous workflow
$hostname = gethostname();

$progress_zen->setText('Step 2');
$loop->tick();

// SQL is also regular blocking PHP
$get_sync = $db_serv->prepare('SELECT last_sync FROM tbl_sync WHERE hostname=?');
$get_sync->execute(array($hostname));
$result_sync = $get_sync->fetch();

Builder

Additionally, the Builder implements an even simpler interface for commonly used dialogs. This is mostly for convenience, so you can get started easier. The methods should be fairly self-explanatory and map directly to the Zenity dialogs listed below.

$builder = new Builder();
$dialog = $builder->info('Hello world');

For anything more complex, you can also instantiate the below classes directly.

Dialog

The Dialog API is modelled closely after Zenity's command line API, so it should be familar if you're already using it from within any other command line script.

AbstractDialog

Abstract base class for all Zenity dialogs (see below for details on each concrete type).

CalendarDialog

https://help.gnome.org/users/zenity/stable/calendar.html

ColorSelectionDialog

https://help.gnome.org/users/zenity/stable/colorselection.html

EntryDialog

$builder->entry($prompt = null, $prefill = null);

https://help.gnome.org/users/zenity/stable/entry.html

ErrorDialog

$builder->error($text, $title = null);

https://help.gnome.org/users/zenity/stable/error.html

FileSelectionDialog

$builder->fileSelection($title = null, $multiple = false);
$builder->fileSave($title = null, $previous = null);
$builder->directorySelection($title = null, $multiple = false);

https://help.gnome.org/users/zenity/stable/fileselection.html

FormsDialog

https://help.gnome.org/users/zenity/stable/forms.html

InfoDialog

$builder->info($text, $title = null);

https://help.gnome.org/users/zenity/stable/info.html

ListDialog

$builder->listCheck(array $list, $text = null, array $selected = null);
$builder->listMenu(array $list, $text = null);
$builder->listRadio(array $list, $text = null, $selected = null);
$builder->table(array $rows, array $columns = null, $text = null);

Where $selected in case of listCheck is an array of keys of the items from $list you want to preselect. Where $selected in case of listRadio is the key of the item from $list you want to preselect.

https://help.gnome.org/users/zenity/stable/list.html

NotificationDialog

$builder->notification($text);
$builder->notifier();

https://help.gnome.org/users/zenity/stable/notification.html

PasswordDialog

https://help.gnome.org/users/zenity/stable/password.html

ProgressDialog

$builder->progress($text = null);
$builder->pulsate($text = null);

https://help.gnome.org/users/zenity/stable/progress.html

QuestionDialog

$builder->question($question, $title = null);

https://help.gnome.org/users/zenity/stable/question.html

ScaleDialog

https://help.gnome.org/users/zenity/stable/scale.html

TextInfoDialog

$builder->text($filename, $title = null);
$builder->editable($filename, $title = null);
$builder->confirmLicense($filename, $confirmation, $title = null);

https://help.gnome.org/users/zenity/stable/text.html

WarningDialog

$builder->warning($text, $title = null);

https://help.gnome.org/users/zenity/stable/warning.html

Install

The recommended way to install this library is through Composer. New to Composer?

This will install the latest supported version:

$ composer require clue/zenity-react:^0.4.2

See also the CHANGELOG for details about version upgrades.

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+ and HHVM.

Obviously, this library requires the Zenity binary itself. Zenity already ships with Ubuntu-based distributions and should not require any installation there. On Debian- and Ubuntu-based distributions you can make sure it's installed like this:

# usually not required
$ sudo apt-get install zenity

Otherwise you may have to install Zenity yourself (use your favorite search engine, download the appropriate realease tarball or compile from soure). Zenity it not officially supported on other platforms, however several non-official releases exist.

Running on Windows is currently not supported

This library assumes Zenity is installed in your PATH. If it is not, you can explicitly set its path like this:

$launcher = new Launcher($loop);
$launcher->setBin('/path/to/zenity');

Tests

To run the test suite, you first need to clone this repo and then install all dependencies through Composer:

$ composer install

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

$ php vendor/bin/phpunit

License

MIT