Zenity allows you to build graphical desktop (GUI) applications in PHP, built on top of ReactPHP.
Zenity is a small program that allows creating simple GTK+ dialogs from within command line scripts. 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. This library provides an easy to use wrapper to spawn Zenity processes to build graphical desktop applications with PHP.
Table of contents
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.
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);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');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);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
}
});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
});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();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.
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.
Abstract base class for all Zenity dialogs (see below for details on each concrete type).
$builder->entry($prompt = null, $prefill = null);
$builder->error($text, $title = null);
$builder->fileSelection($title = null, $multiple = false);
$builder->fileSave($title = null, $previous = null);
$builder->directorySelection($title = null, $multiple = false);
$builder->info($text, $title = null);
$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.
$builder->notification($text);
$builder->notifier();
$builder->progress($text = null);
$builder->pulsate($text = null);
$builder->question($question, $title = null);
$builder->text($filename, $title = null);
$builder->editable($filename, $title = null);
$builder->confirmLicense($filename, $confirmation, $title = null);
$builder->warning($text, $title = null);
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.3See 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 zenityOtherwise 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');To run the test suite, you first need to clone this repo and then install all dependencies through Composer:
$ composer installTo run the test suite, go to the project root and run:
$ php vendor/bin/phpunitMIT
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent