Download the PHP package ody/server without Composer

Ody Server

Ody Server is a package for the Ody PHP framework that provides high-performance HTTP server capabilities powered by Swoole. It offers easy server management with command-line tools, hot-reloading support, and administrative features.

Table of Contents

• Introduction
• Installation
• Basic Usage
• Configuration
• Server Management
• Server Events
• Admin Server
• API Reference

Introduction

Ody Server simplifies the process of creating and managing Swoole-based servers. It provides:

• Command-line tools for managing server processes
• HTTP, WebSocket, and TCP server support
• Hot reloading capabilities for development
• Server state management
• Administrative API interface for monitoring and management

Installation

Basic Usage

Starting a Server

To start a server, use the server:start command:

Options:

• --daemonize or -d: Run the server in the background
• --watch or -w: Enable file watching for hot reloading

Stopping a Server

To stop a running server:

Reloading a Server

To reload workers without stopping the server:

Configuration

Server configuration should be defined in your application's config/server.php file:

Server Management

The ServerManager class provides an interface for creating and managing Swoole servers.

Server Events

The following server events can be registered in your configuration:

Server State

The HttpServerState class manages the state of running server processes, allowing for tracking and management of processes.

Admin Server

!! Use with caution, very experimental and likely to break !!

The AdminServer class provides an administrative interface for monitoring and managing Swoole servers. It exposes a RESTful API for interacting with the server processes.

To enable the Admin server, add the following to your server configuration:

You can access a web-based dashboard at http://your-admin-server:port/dashboard.

Authentication

The admin server supports authentication via the admin_server URI:

When authenticated, an access token is generated as sha1(username . password) and must be provided in the X-ADMIN-SERVER-ACCESS-TOKEN HTTP header.

API Endpoints

The admin server exposes a RESTful API at the /api endpoint. The URL structure is:

Where:

• COMMAND is one of the registered command names
• PROCESS identifies the target process (e.g., "master", "worker-0", "all")

Available Commands

Example Requests

Retrieve server statistics:

Reload the server:

Get coroutine list from all worker processes:

Close a client connection:

API Reference

Server Types

The ServerType class provides constants for different server types:

• HTTP_SERVER: Swoole HTTP server (\Swoole\Http\Server)
• WS_SERVER: Swoole WebSocket server (\Swoole\WebSocket\Server)
• TCP_SERVER: Swoole TCP server (\Swoole\Server)

Server Events

The ServerEvent class provides constants for all supported server events:

• ON_START: Server start event
• ON_WORKER_START: Worker process start event
• ON_WORKER_STOP: Worker process stop event
• ON_WORKER_EXIT: Worker process exit event
• ON_WORKER_ERROR: Worker process error event
• ON_PIPE_MESSAGE: Pipe message event
• ON_REQUEST: HTTP request event
• ON_RECEIVE: Data receive event
• ON_CONNECT: Client connect event
• ON_DISCONNECT: Client disconnect event
• ON_OPEN: WebSocket open event
• ON_MESSAGE: WebSocket message event
• ON_CLOSE: Connection close event
• ON_TASK: Task event
• ON_FINISH: Task finish event
• ON_SHUTDOWN: Server shutdown event
• ON_PACKET: UDP packet event
• ON_MANAGER_START: Manager start event
• ON_MANAGER_STOP: Manager stop event
• ON_BEFORE_START: Before server start event (not a Swoole event)

ServerManager Class

Methods:

• init(string $serverType): static - Initialize the server manager with a server type
• createServer(?array $config): static - Create a new server instance with the given configuration
• setServerConfig(array $config): static - Set additional server configuration
• getServerInstance(): HttpServer|WsServer - Get the server instance
• registerCallbacks(array $callbacks): static - Register event callbacks
• setWatcher(int $enableWatcher, array $paths, object $serverState): static - Enable file watching for hot reloading
• daemonize(bool $daemonize): static - Set the server to run in the background
• setLogger(LoggerInterface $logger): self - Set the logger instance
• setConfig(Config $config): self - Set the configuration instance
• start(): void - Start the server

ServerState Class

Methods:

• getInstance(): self - Get the singleton instance
• getInformation(): array - Get the state information
• setManagerProcessId(?int $id): void - Set the manager process ID
• setMasterProcessId(?int $id): void - Set the master process ID
• setWatcherProcessId(?int $id): void - Set the watcher process ID
• setWorkerProcessIds(array $ids): void - Set the worker process IDs
• getManagerProcessId(): int|null - Get the manager process ID
• getMasterProcessId(): int|null - Get the master process ID
• getWatcherProcessId(): int|null - Get the watcher process ID
• getWorkerProcessIds(): array - Get the worker process IDs
• clearProcessIds(): void - Clear all process IDs
• reloadProcesses(array $processIds): void - Reload the specified processes
• killProcesses(array $processIds): void - Kill the specified processes

HttpServerState Class

Methods:

• getInstance(): self - Get the singleton instance
• httpServerIsRunning(): bool - Check if the HTTP server is running

AdminServer Class

Methods:

• init(Server $server): void - Initialize the admin server
• getAccessToken(): string - Get the access token
• start(Server $server): void - Start the admin server

ServerCallbacks Class

Static methods:

• onStart(SwServer $server): void - Handle server start event
• onRequest(SwRequest $request, SwResponse $response): void - Handle HTTP request event
• onWorkerStart(SwServer $server, int $workerId): void - Handle worker start event
• onManagerStart(SwServer $server) - Handle manager start event
• onManagerStop(SwServer $server) - Handle manager stop event
• onReceive(SwServer $server, int $fd, int $reactorId, string $data) - Handle data receive event
• onWorkerError(SwServer $server, int $workerId, int $workerPid, int $exitCode, int $signal): void - Handle worker error event