{"id":26420112,"url":"https://github.com/ody-dev/server","last_synced_at":"2026-02-27T05:04:40.399Z","repository":{"id":281065135,"uuid":"944092476","full_name":"ody-dev/server","owner":"ody-dev","description":"Server component for ODY framework","archived":false,"fork":false,"pushed_at":"2025-04-06T18:26:44.000Z","size":95,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-31T20:50:25.122Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ody-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-06T19:17:08.000Z","updated_at":"2025-04-06T18:22:05.000Z","dependencies_parsed_at":"2025-03-23T12:24:41.197Z","dependency_job_id":"5484be77-2f53-4c66-ad62-3be0a13e083f","html_url":"https://github.com/ody-dev/server","commit_stats":null,"previous_names":["ody-dev/ody-server","ody-dev/server"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/ody-dev/server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ody-dev%2Fserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ody-dev%2Fserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ody-dev%2Fserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ody-dev%2Fserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ody-dev","download_url":"https://codeload.github.com/ody-dev/server/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ody-dev%2Fserver/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268618021,"owners_count":24279238,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-18T02:01:03.229Z","updated_at":"2026-02-27T05:04:35.369Z","avatar_url":"https://github.com/ody-dev.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Actions Status](https://github.com/ody-dev/ody-http-server/workflows/Build%20and%20test/badge.svg)](https://github.com/ody-dev/ody-http-server/actions)\n[![License](https://poser.pugx.org/ody/core/license)](https://packagist.org/packages/ody/core)\n\n# Ody Server\n\nOdy Server is a package for the Ody PHP framework that provides high-performance HTTP server capabilities powered by\nSwoole. It offers easy server management with command-line tools, hot-reloading support, and administrative features.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Basic Usage](#basic-usage)\n- [Configuration](#configuration)\n- [Server Management](#server-management)\n- [Server Events](#server-events)\n- [Admin Server](#admin-server)\n- [API Reference](#api-reference)\n\n## Introduction\n\nOdy Server simplifies the process of creating and managing Swoole-based servers. It provides:\n\n- Command-line tools for managing server processes\n- HTTP, WebSocket, and TCP server support\n- Hot reloading capabilities for development\n- Server state management\n- Administrative API interface for monitoring and management\n\n## Installation\n\n```bash\ncomposer require ody-dev/server\n```\n\n## Basic Usage\n\n### Starting a Server\n\nTo start a server, use the `server:start` command:\n\n```bash\nphp ody server:start\n```\n\nOptions:\n\n- `--daemonize` or `-d`: Run the server in the background\n- `--watch` or `-w`: Enable file watching for hot reloading\n\n### Stopping a Server\n\nTo stop a running server:\n\n```bash\nphp ody server:stop\n```\n\n### Reloading a Server\n\nTo reload workers without stopping the server:\n\n```bash\nphp ody server:reload\n```\n\n## Configuration\n\nServer configuration should be defined in your application's `config/server.php` file:\n\n```php\nreturn [\n    // Server host\n    'host' =\u003e env('SERVER_HOST', '127.0.0.1'),\n    \n    // Server port\n    'port' =\u003e env('SERVER_PORT', 9501),\n    \n    // Server mode (SWOOLE_BASE or SWOOLE_PROCESS)\n    'mode' =\u003e SWOOLE_PROCESS,\n    \n    // Socket type\n    'sock_type' =\u003e SWOOLE_SOCK_TCP,\n    \n    // SSL configuration\n    'ssl' =\u003e [\n        'ssl_cert_file' =\u003e env('SSL_CERT_FILE', null),\n        'ssl_key_file' =\u003e env('SSL_KEY_FILE', null),\n    ],\n    \n    // Additional Swoole server settings\n    'additional' =\u003e [\n        'worker_num' =\u003e env('SERVER_WORKER_NUM', 4),\n        'task_worker_num' =\u003e env('SERVER_TASK_WORKER_NUM', 2),\n        'reactor_num' =\u003e env('SERVER_REACTOR_NUM', 2),\n        'max_request' =\u003e 1000,\n        'buffer_output_size' =\u003e 2 * 1024 * 1024,\n        'admin_server' =\u003e '127.0.0.1:9506',\n    ],\n    \n    // Server event callbacks\n    'callbacks' =\u003e [\n        'start' =\u003e [\\Ody\\Server\\ServerCallbacks::class, 'onStart'],\n        'workerStart' =\u003e [\\Ody\\Server\\ServerCallbacks::class, 'onWorkerStart'],\n        'managerStart' =\u003e [\\Ody\\Server\\ServerCallbacks::class, 'onManagerStart'],\n        'managerStop' =\u003e [\\Ody\\Server\\ServerCallbacks::class, 'onManagerStop'],\n        'request' =\u003e [\\Ody\\Server\\ServerCallbacks::class, 'onRequest'],\n        'workerError' =\u003e [\\Ody\\Server\\ServerCallbacks::class, 'onWorkerError'],\n        // Add additional callbacks as needed\n    ],\n    \n    // File paths to watch for hot reloading (when --watch is enabled)\n    'watch_paths' =\u003e [\n        'app/',\n        'config/',\n        'routes/',\n    ],\n];\n```\n\n## Server Management\n\nThe `ServerManager` class provides an interface for creating and managing Swoole servers.\n\n```php\nuse Ody\\Server\\ServerManager;\nuse Ody\\Server\\ServerType;\nuse Ody\\Server\\State\\HttpServerState;\n\n// Initialize the server manager\n$serverManager = ServerManager::init(ServerType::HTTP_SERVER)\n    -\u003ecreateServer($config)\n    -\u003esetServerConfig($additionalConfig)\n    -\u003eregisterCallbacks($callbacks)\n    -\u003edaemonize($daemonize);\n\n// Get the server instance\n$server = $serverManager-\u003egetServerInstance();\n\n// Start the server\nServer::start($server);\n```\n\n## Server Events\n\nThe following server events can be registered in your configuration:\n\n| Event              | Description                                             |\n|--------------------|---------------------------------------------------------|\n| `ON_START`         | Triggered when the server starts                        |\n| `ON_WORKER_START`  | Triggered when a worker process starts                  |\n| `ON_WORKER_STOP`   | Triggered when a worker process stops                   |\n| `ON_WORKER_EXIT`   | Triggered when a worker process exits                   |\n| `ON_WORKER_ERROR`  | Triggered when a worker process encounters an error     |\n| `ON_PIPE_MESSAGE`  | Triggered when a message is sent through pipes          |\n| `ON_REQUEST`       | Triggered when an HTTP request is received              |\n| `ON_RECEIVE`       | Triggered when data is received                         |\n| `ON_CONNECT`       | Triggered when a client connects                        |\n| `ON_DISCONNECT`    | Triggered when a client disconnects                     |\n| `ON_OPEN`          | Triggered when a WebSocket connection is opened         |\n| `ON_MESSAGE`       | Triggered when a WebSocket message is received          |\n| `ON_CLOSE`         | Triggered when a connection is closed                   |\n| `ON_TASK`          | Triggered when a task is received                       |\n| `ON_FINISH`        | Triggered when a task is finished                       |\n| `ON_SHUTDOWN`      | Triggered when the server shuts down                    |\n| `ON_PACKET`        | Triggered when a UDP packet is received                 |\n| `ON_MANAGER_START` | Triggered when the manager process starts               |\n| `ON_MANAGER_STOP`  | Triggered when the manager process stops                |\n| `ON_BEFORE_START`  | Triggered before the server starts (not a Swoole event) |\n\n## Server State\n\nThe `HttpServerState` class manages the state of running server processes, allowing for tracking and management of\nprocesses.\n\n```php\n$serverState = HttpServerState::getInstance();\n\n// Check if the server is running\nif ($serverState-\u003ehttpServerIsRunning()) {\n    // Server is running\n}\n\n// Get process IDs\n$masterPid = $serverState-\u003egetMasterProcessId();\n$managerPid = $serverState-\u003egetManagerProcessId();\n$workerPids = $serverState-\u003egetWorkerProcessIds();\n\n// Kill processes\n$serverState-\u003ekillProcesses([\n    $masterPid,\n    $managerPid,\n    // ...worker PIDs\n]);\n\n// Reload processes\n$serverState-\u003ereloadProcesses([\n    $masterPid,\n    $managerPid,\n    // ...worker PIDs\n]);\n\n// Clear process IDs\n$serverState-\u003eclearProcessIds();\n```\n\n## Admin Server\n\n!! Use with caution, very experimental and likely to break !!\n\nThe `AdminServer` class provides an administrative interface for monitoring and managing Swoole servers. It exposes a\nRESTful API for interacting with the server processes.\n\nTo enable the Admin server, add the following to your server configuration:\n\n```php\n'additional' =\u003e [\n    // ...\n    'admin_server' =\u003e '127.0.0.1:9502',\n    // ...\n],\n```\n\nYou can access a web-based dashboard at `http://your-admin-server:port/dashboard`.\n\n### Authentication\n\nThe admin server supports authentication via the `admin_server` URI:\n\n```\nusername:password@host:port\n```\n\nWhen authenticated, an access token is generated as `sha1(username . password)` and must be provided in the\n`X-ADMIN-SERVER-ACCESS-TOKEN` HTTP header.\n\n### API Endpoints\n\nThe admin server exposes a RESTful API at the `/api` endpoint. The URL structure is:\n\n```\n/api/COMMAND/PROCESS\n```\n\nWhere:\n\n- `COMMAND` is one of the registered command names\n- `PROCESS` identifies the target process (e.g., \"master\", \"worker-0\", \"all\")\n\n#### Available Commands\n\n| Command                   | Description                    | HTTP Method |\n|---------------------------|--------------------------------|-------------|\n| `server_reload`           | Reload worker processes        | POST        |\n| `server_shutdown`         | Shut down the server           | POST        |\n| `server_stats`            | Get server statistics          | GET         |\n| `server_setting`          | Get server configuration       | GET         |\n| `coroutine_stats`         | Get coroutine statistics       | GET         |\n| `coroutine_list`          | Get active coroutines          | GET         |\n| `coroutine_bt`            | Get coroutine backtrace        | POST        |\n| `get_version_info`        | Get version information        | GET         |\n| `get_worker_info`         | Get worker process information | GET         |\n| `get_timer_list`          | Get active timers              | GET         |\n| `get_server_memory_usage` | Get memory usage               | GET         |\n| `get_server_cpu_usage`    | Get CPU usage                  | GET         |\n| `close_session`           | Close a client connection      | POST        |\n| `get_client_info`         | Get client information         | GET         |\n\n#### Example Requests\n\nRetrieve server statistics:\n\n```\nGET /api/server_stats/master\n```\n\nReload the server:\n\n```\nPOST /api/server_reload/master\n```\n\nGet coroutine list from all worker processes:\n\n```\nGET /api/coroutine_list/all_worker\n```\n\nClose a client connection:\n\n```\nPOST /api/close_session/worker-0\n{\n  \"session_id\": 1\n}\n```\n\n## API Reference\n\n### Server Types\n\nThe `ServerType` class provides constants for different server types:\n\n- `HTTP_SERVER`: Swoole HTTP server (`\\Swoole\\Http\\Server`)\n- `WS_SERVER`: Swoole WebSocket server (`\\Swoole\\WebSocket\\Server`)\n- `TCP_SERVER`: Swoole TCP server (`\\Swoole\\Server`)\n\n### Server Events\n\nThe `ServerEvent` class provides constants for all supported server events:\n\n- `ON_START`: Server start event\n- `ON_WORKER_START`: Worker process start event\n- `ON_WORKER_STOP`: Worker process stop event\n- `ON_WORKER_EXIT`: Worker process exit event\n- `ON_WORKER_ERROR`: Worker process error event\n- `ON_PIPE_MESSAGE`: Pipe message event\n- `ON_REQUEST`: HTTP request event\n- `ON_RECEIVE`: Data receive event\n- `ON_CONNECT`: Client connect event\n- `ON_DISCONNECT`: Client disconnect event\n- `ON_OPEN`: WebSocket open event\n- `ON_MESSAGE`: WebSocket message event\n- `ON_CLOSE`: Connection close event\n- `ON_TASK`: Task event\n- `ON_FINISH`: Task finish event\n- `ON_SHUTDOWN`: Server shutdown event\n- `ON_PACKET`: UDP packet event\n- `ON_MANAGER_START`: Manager start event\n- `ON_MANAGER_STOP`: Manager stop event\n- `ON_BEFORE_START`: Before server start event (not a Swoole event)\n\n### ServerManager Class\n\nMethods:\n\n- `init(string $serverType): static` - Initialize the server manager with a server type\n- `createServer(?array $config): static` - Create a new server instance with the given configuration\n- `setServerConfig(array $config): static` - Set additional server configuration\n- `getServerInstance(): HttpServer|WsServer` - Get the server instance\n- `registerCallbacks(array $callbacks): static` - Register event callbacks\n- `setWatcher(int $enableWatcher, array $paths, object $serverState): static` - Enable file watching for hot reloading\n- `daemonize(bool $daemonize): static` - Set the server to run in the background\n- `setLogger(LoggerInterface $logger): self` - Set the logger instance\n- `setConfig(Config $config): self` - Set the configuration instance\n- `start(): void` - Start the server\n\n### ServerState Class\n\nMethods:\n\n- `getInstance(): self` - Get the singleton instance\n- `getInformation(): array` - Get the state information\n- `setManagerProcessId(?int $id): void` - Set the manager process ID\n- `setMasterProcessId(?int $id): void` - Set the master process ID\n- `setWatcherProcessId(?int $id): void` - Set the watcher process ID\n- `setWorkerProcessIds(array $ids): void` - Set the worker process IDs\n- `getManagerProcessId(): int|null` - Get the manager process ID\n- `getMasterProcessId(): int|null` - Get the master process ID\n- `getWatcherProcessId(): int|null` - Get the watcher process ID\n- `getWorkerProcessIds(): array` - Get the worker process IDs\n- `clearProcessIds(): void` - Clear all process IDs\n- `reloadProcesses(array $processIds): void` - Reload the specified processes\n- `killProcesses(array $processIds): void` - Kill the specified processes\n\n### HttpServerState Class\n\nMethods:\n\n- `getInstance(): self` - Get the singleton instance\n- `httpServerIsRunning(): bool` - Check if the HTTP server is running\n\n### AdminServer Class\n\nMethods:\n\n- `init(Server $server): void` - Initialize the admin server\n- `getAccessToken(): string` - Get the access token\n- `start(Server $server): void` - Start the admin server\n\n### ServerCallbacks Class\n\nStatic methods:\n\n- `onStart(SwServer $server): void` - Handle server start event\n- `onRequest(SwRequest $request, SwResponse $response): void` - Handle HTTP request event\n- `onWorkerStart(SwServer $server, int $workerId): void` - Handle worker start event\n- `onManagerStart(SwServer $server)` - Handle manager start event\n- `onManagerStop(SwServer $server)` - Handle manager stop event\n- `onReceive(SwServer $server, int $fd, int $reactorId, string $data)` - Handle data receive event\n- `onWorkerError(SwServer $server, int $workerId, int $workerPid, int $exitCode, int $signal): void` - Handle worker\n  error event","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fody-dev%2Fserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fody-dev%2Fserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fody-dev%2Fserver/lists"}