README

 _ _ _    ___ ___  __  __                             ___ _  _ ___
| (_) |__/ __|   \|  \/  |__ _ _ _  __ _ __ _ ___ _ _| _ \ || | _ \
| | | '_ \__ \ |) | |\/| / _` | ' \/ _` / _` / -_) '_|  _/ __ |  _/
|_|_|_.__/___/___/|_|  |_\__,_|_||_\__,_\__, \___|_| |_| |_||_|_|
                                        |___/

libSDManagerPHP provides a portable daemon with a Sockets and Streams manager.

The DaemonManager can be used on its own, to create PHP daemons. The SocketManager can act as both client and server. It extends the DaemonManager class and can handle forked processes with IPC to transmit data between parent and child processes.

Daemon Features

• Only allow PHP cli execution
• Set the process title based on the script filename
• Set user/group ownsership
• Generate a PID file
• Limit number of forked processes
• Set max execution time to zero (unlimited)
• Enable asynchronous signals
• Setup a signal handler
• Cleanly remove the PID file on exit

Sockets and Streams Features

• Support for UNIX sockets
• Support for IPv4/IPv6 internet addresses
• Support for SSL/TLS streams
• Listen for connections
• Initiate remote connections
• Fork on incoming connection
• Read/write HTTP data
• Read/write null terminated data
• Read/write data prefixed by size (uint32)

Requirements

• PHP 8.0, 8.1, 8.2, 8.3, 8.4, 8.5
• posix module
• sockets module
• libLoggerPHP

Install with RPM packages

You may install libSDManagerPHP via the copr repository, for Alma/Rocky/Oracle Enterprise Linux and Fedora, simply use:

dnf copr enable mksanthi/noumenia
dnf install libSDManagerPHP

Install with Composer

You may install libSDManagerPHP with composer, to get the latest version use:

composer require noumenia/libsdmanagerphp

Install manually

Download the repository and copy the libSDManagerPHP project directory in the appropriate place within your project or within an accessibe location, for example under /usr/share/php.

How to use the DaemonManager

Load and initialize the libraries by loading their common.inc.php file:

require_once("/path/to/libLoggerPHP/controller/common.inc.php");
require_once("/path/to/libSDManagerPHP/controller/common.inc.php");

Extend DaemonManager from your own class with a constructor, and call the DaemonManager contructor with parent::__construct($daemonManager);.

The $daemonManager array keys are:

• string daemonUser: Daemon user owner
• string daemonGroup: Daemon group owner
• string filePid: PID file
• int processLimit: Limit the number of forked processes

For example:

<?php
require_once("/path/to/libLoggerPHP/controller/common.inc.php");
require_once("/path/to/libSDManagerPHP/controller/common.inc.php");

use libLoggerPHP\Log;
use libLoggerPHP\LogDestinationConsole;
use libSDManagerPHP\DaemonManager;

final class TestDaemon extends DaemonManager {

	public function __construct()
	{

		// DaemonManager options
		$daemonManager = array(
			'daemonUser'		=> "",
			'daemonGroup'		=> "",
			'filePid'		=> "/tmp/daemon.pid",
			'processLimit'		=> 10
		);

		// Call the DaemonManager constructor
		parent::__construct($daemonManager);

	}

	public function doSomeWork(): void
	{
		Log::debug("Do some work here and exit");
	}
}

// Define the logging method
Log::setDestination(new LogDestinationConsole(), LOG_DEBUG);

// Instantiate the TestDaemon
$daemon = new TestDaemon();

// Run
$daemon->doSomeWork();

How to use the SocketManager

Load and initialize the libraries by loading their common.inc.php file:

require_once("/path/to/libLoggerPHP/controller/common.inc.php");
require_once("/path/to/libSDManagerPHP/controller/common.inc.php");

Extend SocketManager from your own class with a constructor, and call the SocketManager contructor with parent::__construct($daemonManager, $socketManager);.

The $daemonManager array keys are:

• string daemonUser: Daemon user owner
• string daemonGroup: Daemon group owner
• string filePid: PID file
• int processLimit: Limit the number of forked processes

The $socketManager array keys are:

• string connection: Socket file or IPv4/IPv6 address/port ("unix|socket:///path/to/file.sock" or "inet:port@IP") or an empty string
• int timeout: Socket/Stream timeout in seconds
• array<string, bool|int|string> ssl: SSL/TLS context options (@see https://www.php.net/manual/en/context.ssl.php)
• bool ipc: Enable parent/child inter-process communication (IPC) over sockets

If the connection key is empty, then the SocketManager will not act as a server daemon (not listen for connections). This is useful when used for the IPC features only.

Create the function processChild(), which will be called for every connection. You can then use the available read/write functions:

• socketReadByHttp()
• socketWriteByHttp()
• socketReadByNul()
• socketWriteByNul()
• socketReadBySize()
• socketWriteBySize()

Finally, call the acceptConnections() method, to start the daemon in the foreground, for example: $yourClass->acceptConnections();. The acceptConnections() function will execute two functions, based on the connection type UNIX socket, Inet over SSL or plain Inet.

UNIX socket: -> prepareSocket() -> loopSocket()

INET SSL: -> prepareStream() -> loopStream()

INET: -> prepareInet() -> loopSocket()

For example:

<?php
require_once("/path/to/libLoggerPHP/controller/common.inc.php");
require_once("/path/to/libSDManagerPHP/controller/common.inc.php");

use libSDManagerPHP\SocketManager;

final class TestDaemon extends SocketManager {

	public function __construct()
	{

		// DaemonManager options
		$daemonManager = array(
			'daemonUser'		=> "",
			'daemonGroup'		=> "",
			'filePid'		=> "/tmp/daemon.pid",
			'processLimit'		=> 10
		);

		// SocketManager options
		$socketManager = array(
			'connection'		=> "inet:7777@127.0.0.1",
			'timeout'		=> 3,
			'ssl'			=> array(),
			'ipc'			=> false
		);

		// Call the SocketManager constructor
		parent::__construct($daemonManager, $socketManager);

	}

	public function processChild(): void
	{

		// Process incoming connection!
		echo "Incoming connection!\n";

	}
}

$daemon = new TestDaemon();
echo "Listening for incoming connections at 127.0.0.1 port 7777...\n";
$daemon->acceptConnections();

Design diagram

The following diagram shows a simplified view of the libSDManagerPHP implementation.

+----------------+         +-------------------+
|                |         |                   |
| common.inc.php | +---+-> | constants.inc.php |
|                |     |   |                   |
+----------------+     |   +-------------------+
                       |
Constants              |   Set system constants
Autoloader             |
                       |
                       |
                       |   +-------------------------------------------+
                       |   |                                           |
                       +-> | NoumeniaLibSDManagerPHPAutoloader.inc.php |
                           |                                           |
                           +-------------------------------------------+
                        
                           Define the autoloader function

                                     +-------------------------+
                                     |                         |
                                     | SocketInterface.inc.php |
                          implements |                         |
+-----------------------+ +--------> +-------------------------+
|                       |
| SocketManager.inc.php |
|                       | extends
+-----------------------+ <--------> +-----------------------+            +-------------------------+
                                     |                       | implements |                         |
__construct()                        | DaemonManager.inc.php | +--------> | DaemonInterface.inc.php |
acceptConnections()                  |                       |            |                         |
socketReadByHttp()                   +-----------------------+            +-------------------------+
socketWriteByHttp()
socketReadByNul()                    __construct()
socketWriteByNul()                   checkProcessLimit()
socketReadBySize()                   fork()
socketWriteBySize()                  signalHandler()
remoteConnect()
__destruct()

Related projects

• Aetolos - Virtual hosting at your... command line!
• guardian-milter - Multi-purpose security milter.
• bravos - Log file security parser.
• mmDbDaemon is a memory-resident MaxMind Database reader implementation in PHP.
• libMilterPHP is a Postfix/Sendmail Milter library implementation in PHP.
• libSDManagerPHP provides a portable daemon with a Sockets and Streams manager.
• libLoggerPHP is a logging library implementation in PHP.