Introduction

ZEUS for PHP is an event-driven, preemptive _Multitasking Runtime Environment_ and _Service Management System_ integrated with Zend Framework 3. It's main purpose is to perform multiple tasks (processes) concurrently.

To guarantee true parallelism and resource isolation ZEUS employs preemptive schedulers and an Inter-Process Communication mechanism to allow its processes to share the data .

*ZEUS for PHP is not a standalone service, in order to use it, it must be installed as a module on-top of any Zend Framework application!.*

It's designed to be compliant with any ZF3 application such as Apigility or ZendSkeleton. Custom applications must provide index.php file which starts the Zend Framework MVC Application class.

Features

• Preemptive schedulers allowing to run multiple services asynchronously
• Built-in IPC server with various IPC Adapters suitable for different Operating Systems or usage characteristics
• Server service manager allowing to start, stop and track the status of ZEUS server services
• Well defined, extensive Server Service life-cycle based on Zend Framework `EventManager` functionality and events such as `SchedulerEvent` and `ManagerEvent`
• Possibility to write your own asynchronous Server Services by using just few lines of boilerplate code
• Advanced status reporting tools tracking the life-cycle and usage statistics of each service and its processes
• Deep integration with Zend Framework 3+ and its services such as `EventManager` and `ServiceManager`
• Plugin support allowing to extend functionality of ZEUS Schedulers and Server Services
• Attachable, event-driven Server Services, Processes and Schedulers, allowing to react on and alter each step of their life-cycle
• Customizable, user friendly Logger functionality based on and compatible with Zend Framework 3 `Logger` module
• Easy configuration and customization of ZEUS components provided by Zend Framework 3 `Config` module
• Built-in `async()` controller plugin and the Async Server Service which allow to run multiple anonymous function/closures asynchronously
• Self hosted - ZEUS comes equipped with its own, high-speed HTTP Server Service implementation supporting HTTP/1.0 and HTTP/1.1 protocols, keep-alive connections and a deflate compression
• Can be integrated with any Zend Framework 3 Application with just few commands issued in a terminal
• Compatible with Zend Framework `MVC` module, enabling ZEUS to dispatch HTTP requests both for static files as well as any Zend Framework Application controller
• Equipped with its own, customizable Memcached Server Service that is integrated with Zend Framework 3 `Cache` module, allowing to use any of its `Cache` adapters as a Memcached key storage
• Compatible with any UNIX/Linux/BSD platform
• Well documented and unit tested (with at least 90% code coverage)
• Stress tested, shipped with its own benchmark tests
• Compatible with and tested against PHP 5.6, PHP 7.0, PHP 7.1 and HHVM

Documentation

Full documentation can be found here.

Sample usage

Supported command line options

Since version 1.3.5, the following commands are supported (assuming that Zend Framework's index.php application bootstrap file is compatible with Zend Framework 3 MVC Module):

• `index.php zeus start` - Starts all ZEUS Server Services
• `index.php zeus start <service-name>` - Starts selected Server Service
• `index.php zeus list` - Lists all Server Services and their configuration
• `index.php zeus list <service-name>` - Shows the configuration of a selected Server Service
• `index.php zeus status` - Returns current status of all Server Services
• `index.php zeus status <service-name>` - Returns current status of the selected Server Service
• `index.php zeus stop` - Stops all ZEUS Server Services
• `index.php zeus stop <service-name>` - Stops selected Server Service

Starting built-in Web Server

Command:

user@host:/var/www/zf-application/public$ php index.php zeus start zeus_httpd

Output:

2017-04-15 14:10:48.769    INFO 24904 --- [           main] erverService\Shared\Logger\LoggerFactory :
 __________            _________
 \____    /____  __ __/   _____/ PHP
   /     // __ \|  |  \_____  \
  /     /\  ___/|  |  /        \
 /_______ \___  >____/_______  /
         \/   \/             \/
 ZEUS for PHP - ZF3 Edition   (1.6.1)

2017-04-15 14:10:48.769    INFO 24904 --- [           main] eus\ServerService\Factory\ManagerFactory : Scanning configuration for services...
2017-04-15 14:10:48.770    INFO 24904 --- [           main] eus\ServerService\Factory\ManagerFactory : Found 4 service(s): httpd, zeus_httpd, zeus_memcache, zeus_async
2017-04-15 14:10:48.771    INFO 24904 --- [           main] Zeus\ServerService\Manager               : Starting Server Service Manager with 0 plugins
2017-04-15 14:10:48.772    INFO 24904 --- [           main] ernel\IpcServer\Factory\IpcServerFactory : Using Zeus\Kernel\IpcServer\Adapter\FifoAdapter for zeus_httpd IPC
2017-04-15 14:10:48.773    INFO 24904 --- [           main] ernel\IpcServer\Factory\IpcServerFactory : Enumerating IPC capabilities:
2017-04-15 14:10:48.773    INFO 24904 --- [           main] ernel\IpcServer\Factory\IpcServerFactory : IPC message size limit: 65536 bytes
2017-04-15 14:10:48.783    INFO 24904 --- [     zeus_httpd] ervice\Shared\AbstractReactServerService : Launching server on 0.0.0.0:7070
2017-04-15 14:10:48.786    INFO 24904 --- [     zeus_httpd] Zeus\Kernel\ProcessManager\Scheduler     : Starting Scheduler with 1 plugin
2017-04-15 14:10:48.795    INFO 24905 --- [     zeus_httpd] Zeus\Kernel\ProcessManager\Scheduler     : Establishing IPC
2017-04-15 14:10:48.795    INFO 24905 --- [     zeus_httpd] Zeus\Kernel\ProcessManager\Scheduler     : Scheduler started
2017-04-15 14:10:48.797   DEBUG 24904 --- [           main] Zeus\ServerService\Manager               : Scheduler running as process #24905
2017-04-15 14:10:48.798    INFO 24904 --- [           main] Zeus\ServerService\Manager               : Started 1 services in 0.03 seconds (PHP running for 0.12s)

Checking any Server Service status

Command:

user@host:/var/www/zf-application/public$ php index.php zeus status zeus_httpd

Output:

2017-04-15 14:17:44.953    INFO 28567 --- [           main] erverService\Shared\Logger\LoggerFactory :
 __________            _________
 \____    /____  __ __/   _____/ PHP
   /     // __ \|  |  \_____  \
  /     /\  ___/|  |  /        \
 /_______ \___  >____/_______  /
         \/   \/             \/
 ZEUS for PHP - ZF3 Edition   (1.6.1)

2017-04-15 14:17:44.953    INFO 28567 --- [           main] eus\ServerService\Factory\ManagerFactory : Scanning configuration for services...
2017-04-15 14:17:44.954    INFO 28567 --- [           main] eus\ServerService\Factory\ManagerFactory : Found 4 service(s): httpd, zeus_httpd, zeus_memcache, zeus_async
2017-04-15 14:17:44.960    INFO 28567 --- [           main] ernel\IpcServer\Factory\IpcServerFactory : Using Zeus\Kernel\IpcServer\Adapter\FifoAdapter for zeus_httpd IPC
2017-04-15 14:17:44.961    INFO 28567 --- [           main] ernel\IpcServer\Factory\IpcServerFactory : Enumerating IPC capabilities:
2017-04-15 14:17:44.961    INFO 28567 --- [           main] ernel\IpcServer\Factory\IpcServerFactory : IPC message size limit: 65536 bytes
2017-04-15 14:17:44.984    INFO 28567 --- [           main] Zeus\Controller\ConsoleController        : Service Status:

Service: zeus_httpd

Current time: Saturday, 15-Apr-2017 14:17:44 UTC
Restart time: Saturday, 15-Apr-2017 14:16:54 UTC
Service uptime: 50 seconds
Total tasks finished: 185957, 3.72K requests/sec
6 tasks currently being processed, 6 idle processes

E_____EERE_R....................

Scoreboard Key:
"_" Waiting for task, "R" Currently running, "E" Exiting,
"T" Terminated, "." Open slot with no current process

Service zeus_httpd
 └─┬ Scheduler 26574, CPU: 46%
   ├── Process 28510 [E] CPU: 44%, RPS: 0, REQ: 100
   ├── Process 28517 [_] CPU: 33%, RPS: 0, REQ: 78
   ├── Process 28523 [_] CPU: 52%, RPS: 0, REQ: 19
   ├── Process 28521 [_] CPU: 33%, RPS: 0, REQ: 26
   ├── Process 28524 [_] CPU: 19%, RPS: 0, REQ: 8
   ├── Process 28513 [_] CPU: 35%, RPS: 0, REQ: 96
   ├── Process 28515 [E] CPU: 33%, RPS: 0, REQ: 100
   ├── Process 28514 [E] CPU: 35%, RPS: 0, REQ: 100
   ├── Process 28519 [R] CPU: 29%, RPS: 0, REQ: 68
   ├── Process 28516 [E] CPU: 42%, RPS: 0, REQ: 100
   ├── Process 28520 [_] CPU: 42%, RPS: 0, REQ: 58
   └── Process 28522 [R] CPU: 41%, RPS: 0, REQ: 31

Viewing process status using OS commands

Command:

user@host:/var/www/zf-application/public$ ps auxw|grep zeus|grep -v grep

osboxes   31259  0.6  2.7 639276 41972 pts/1    S+   15:43   0:00 zeus server zeus_httpd [start] 0 req done, 0 rps, 0% CPU usage
osboxes   31260 35.6  1.0 639276 16708 pts/1    S+   15:43   0:07 zeus scheduler zeus_httpd [loop] 58.78K req done, 3.97K rps, 35% CPU usage
osboxes   31862  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [waiting] 71 req done, 0 rps, 35% CPU usage
osboxes   31863  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [running] 70 req done, 0 rps, 48% CPU usage
osboxes   31864  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [waiting] 76 req done, 0 rps, 43% CPU usage
osboxes   31865  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [running] 55 req done, 0 rps, 34% CPU usage
osboxes   31866  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [waiting] 69 req done, 0 rps, 47% CPU usage
osboxes   31867  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [running] 52 req done, 0 rps, 39% CPU usage
osboxes   31868  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [running] 52 req done, 0 rps, 48% CPU usage
osboxes   31869  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [running] 61 req done, 0 rps, 51% CPU usage
osboxes   31870  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [running] 92 req done, 0 rps, 68% CPU usage
osboxes   31871  0.0  1.1 639276 18252 pts/1    R+   15:43   0:00 zeus process zeus_httpd [waiting] 12 req done, 0 rps, 37% CPU usage

Executing functions asynchronously in ZF3 controllers

First, the Async Server Service must be launched in order to execute anonymous functions.

Command:

user@host:/var/www/zf-application/public$ php index.php zeus status zeus_httpd

The following ZF3 Application code can be handled by any HTTP Server, such as Apache HTTPD or Nginx - such functions are serialized and send to Async Server Service for asynchronous execution.

<?php 
// contents of "zf3-application-directory/module/SomeModule/src/Controller/SomeController.php" file:

namespace Application\Controller;

use Zend\Mvc\Controller\AbstractActionController;
use Zend\View\Model\ViewModel;
use ZF\Apigility\Admin\Module as AdminModule;

class IndexController extends AbstractActionController
{
    public function indexAction()
    {
        for ($i = 0; $i < 12; $i++) {
            // each run() command immediately starts one task in the background and returns a handle ID
            $handles[$i] = $this->async()->run(function () use ($i) {
                sleep($i);
                return "OK $i";
            });
        }

        // join() accepts either an array of handle IDs or a single handle ID (without array)
        // - in case of array of handles, join will return an array of results,
        // - in case of a single handler, join will return a single result (not wrapped into the array)
        $results = $this->async()->join($handles);

        // because of the sleep(11) executed in a last callback, join() command will wait up to 11 seconds to fetch
        // results from all the handles, on success $result variable will contain the following data:
        // ["OK0","OK1","OK2","OK3","OK4","OK5","OK6","OK7","OK8","OK9","OK10","OK11"]

        // please keep in mind that each handle can be joined independently and join() blocks until the slowest
        // callback returns the data, therefore running $this->async()->join($handles[3]) command instead
        // would block this controller only for 3 seconds

        // usual Zend Framework stuff to return data to the view layer
        $view = new ViewModel();
        $view->setVariable('async_results', $results);
    }
}

Building HTML documentation

Please note, mkdocs must be installed first using the apt-get command, or any other OS-specific package-manager.

Command:

user@host:/var/www/zf-application/vendor/zeus-server/zf3-server$ make doc-server

Serving markdown documentation

Command:

user@host:/var/www/zf-application/vendor/zeus-server/zf3-server$ make doc-build

After executing above command, ZEUS documentation can be found under the following URL: http://127.0.0.1:8080/

Performance

Most of the ZEUS code was heavily optimized and thoroughly tested for speed and efficiency.

As the response times of most of ZEUS services dropped below 1 milisecond, its common for ZEUS to handle more than 17,000 requests/second on an average mobile Intel Core i7 processor:

Server Software:
Server Hostname:        127.0.0.1
Server Port:            7070

Document Path:          /apigility-ui/img/ag-hero.png
Document Length:        0 bytes

Concurrency Level:      16
Time taken for tests:   2.515 seconds
Complete requests:      50000
Failed requests:        0
Keep-Alive requests:    49513
Total transferred:      6942208 bytes
HTML transferred:       0 bytes
Requests per second:    19883.55 #/sec
Time per request:       0.805 ms
Time per request:       0.050 ms
Transfer rate:          2696.01 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.0      0       1
Processing:     0    1   1.2      1      70
Waiting:        0    1   1.2      1      70
Total:          0    1   1.2      1      70

Percentage of the requests served within a certain time (ms)
  50%      1
  66%      1
  75%      1
  80%      1
  90%      1
  95%      2
  98%      3
  99%      4
 100%     70 (longest request)

Or achieve transfer speeds higher than 8 Gbits/sec:

Server Software:
Server Hostname:        127.0.0.1
Server Port:            7070

Document Path:          /test.file.txt
Document Length:        1048576 bytes

Concurrency Level:      16
Time taken for tests:   51.878 seconds
Complete requests:      50000
Failed requests:        0
Keep-Alive requests:    49513
Total transferred:      52435892208 bytes
HTML transferred:       52428800000 bytes
Requests per second:    963.80 #/sec
Time per request:       16.601 ms
Time per request:       1.038 ms
Transfer rate:          987060.80 [Kbytes/sec] received

Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.0      0       1
Processing:     1   17   5.5     16     419
Waiting:        1    5   4.9      4     403
Total:          1   17   5.5     16     419

Percentage of the requests served within a certain time (ms)
  50%     16
  66%     17
  75%     17
  80%     18
  90%     20
  95%     23
  98%     30
  99%     35
 100%    419 (longest request)

Requirements

OS requirements

• Linux/Unix/BSD platform
• _Windows platform currently not supported_

PHP requirements

• PHP 5.6+ (HHVM or PHP 7+ is recommended for performance reasons as ZEUS can be up to 4x faster and use less memory)
• Posix module installed and enabled
• Pcntl module installed and enabled
• socket functions enabled for IPC purposes

Library requirements

• Zend Framework 3+ application (with the following modules installed: `zend-mvc`, `zend-mvc-console`, `zend-console`, `zend-log`, `zend-config`)
• Opis library (`opis/closure`)
• ReactPHP library

Installation

ZEUS for PHP can be installed in two different ways:

Downloading

via Composer:

user@host:/var/www/$ cd zf3-application-directory
user@host:/var/www/zf3-application-directory$ composer require zeus-server/zf3-server

by downloading source code

Source codes can be found in ZIP file under the following URL: https://github.com/artur-graniszewski/ZEUS-for-PHP/archive/master.zip

After downloading, contents of the compressed ZEUS-for-PHP-master directory in ZIP file must be unpacked into a ZF3 zf3-application-directory/module/Zeus directory.

Enabling ZEUS module

After installation, ZEUS for PHP must be activated in Zend Framework's config/modules.config.php file, like so:

<?php 
// contents of "zf3-application-directory/config/modules.config.php" file:

return [
    'Zend\\Log',
    'Zend\\Mvc\\Console',
    '...',
    'Zeus' // this line should be added
];

This can be achieved either by modifying configuration file in any text editor, or by issuing sed command in Application's root directory:

user@host:/var/www/zf3-application-directory$ sed -i "s/'Zend\\\Log',/'Zend\\\Log','Zeus',/g" config/modules.config.php

If ZEUS for PHP is installed correctly, the following terminal command will show ZEUS version and its services in console:

user@host:/var/www/zf-application/public$ php index.php zeus status zeus_httpd

Road map

Short-term

Documentation

• Improvement of ZEUS documentation
• Tutorials and How-to's

Web Server

• Code refactor and HTTP performance improvements
• Performance improvements in Application dispatcher when handling Zend Framework applications
• Removing dependency on ReactPHP
• More configuration options

Inter-Process Communication

• Various code improvements in IPC adapters
• Introduction of IPC strategy that will choose the most efficient IPC implementation depending on a platform.

Server Service Manager

• Additional `EventManager` events covering full application lifecycle
• (implemented) ~~More advanced Service reporting and control tools for terminal and remote use~~
• (implemented) ~~Add a plugin that drops user privileges on start of the _Server Service_~~
• Advanced, `systemd`-like handling of Server Service failures or remote shutdowns

Process Manager

• (implemented) ~~Configurable, more robust scheduling strategies (like terminating processes that handled the largest amount of request, etc)*~~

Tests

• More automatic tests

Long-Term

POSIX Threads

• Adding support for threads in PHP

Connection pooling

• NGINX like connection pooling in ZEUS Web Server (performance improvement)
• Abstract Server Service classes that will speed up the development of other types of connection pooling services
• Database connection pooling (?)

FastCGI/FPM

• Add possibility to execute Server Services in isolated PHP instances
• Allow ZEUS Web Server to host FastCGI/FPM applications

Experimental support for Windows platform

Other services

• (implemented Memcached instead) ~~Redis Server Service implementation PoC ~~
• More features introduced to ZEUS Web Server