Skip to content

Commit 5b74747

Browse files
luzrainluzrain
committed
Update documentation
1 parent 700035c commit 5b74747

File tree

11 files changed

+257
-192
lines changed

11 files changed

+257
-192
lines changed

‎docs/general/configuration.md‎

Lines changed: 114 additions & 53 deletions
Large diffs are not rendered by default.

‎docs/general/installation.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,38 @@ $ composer require phpstreamserver/core
1414
## PHPStreamServer plugins
1515
To extend the functionality of PHPStreamServer, you can install additional [plugins](/docs/plugins/).
1616
Each plugin is optional, so you can choose only those that are relevant to your application.
17+
18+
### Http Server Plugin
19+
An asynchronous HTTP server with HTTP/2, HTTPS, static file serving, and gzip compression.
20+
```bash
21+
$ composer require phpstreamserver/http-server
22+
```
23+
[Read more](/docs/plugins/http-server)
24+
25+
### Scheduler Plugin
26+
A cron-like scheduler for running tasks at specified intervals.
27+
```bash
28+
$ composer require phpstreamserver/scheduler
29+
```
30+
[Read more](/docs/plugins/scheduler)
31+
32+
### Logger Plugin
33+
A flexible logging system that supports multiple outputs, including files, stderr, syslog, and Graylog.
34+
```bash
35+
$ composer require phpstreamserver/logger
36+
```
37+
[Read more](/docs/plugins/logger)
38+
39+
### File Monitor Plugin
40+
Monitors directories for changes and automatically reloads workers whenever a file is modified.
41+
```bash
42+
$ composer require phpstreamserver/file-monitor
43+
```
44+
[Read more](/docs/plugins/file-monitor)
45+
46+
### Metrics Plugin
47+
Exposes prometheus metrics to monitor server performance and collect custom application metrics.
48+
```bash
49+
$ composer require phpstreamserver/metrics
50+
```
51+
[Read more](/docs/plugins/metrics)

‎docs/general/quick-start.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ $ composer require phpstreamserver/core phpstreamserver/http-server
1919
use Amp\Http\Server\HttpErrorException;
2020
use Amp\Http\Server\Request;
2121
use Amp\Http\Server\Response;
22-
use PHPStreamServer\Core\Plugin\Supervisor\WorkerProcess;
2322
use PHPStreamServer\Core\Server;
23+
use PHPStreamServer\Core\WorkerProcess;
2424
use PHPStreamServer\Plugin\HttpServer\HttpServerPlugin;
2525
use PHPStreamServer\Plugin\HttpServer\HttpServerProcess;
2626

‎docs/general/reload-strategies.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
title: Reload strategies
3+
---
4+
5+
# Reload strategies
6+
7+
Reload strategies in PHPStreamServer define the rules for when workers should be restarted.
8+
PHPStreamServer provides several built-in reload strategies of the box. Additionally, plugins can add new reload strategies, enhancing functionality.
9+
10+
### 🔄️ [TTLReloadStrategy](https://github.com/phpstreamserver/core/blob/main/src/ReloadStrategy/TTLReloadStrategy.php)
11+
12+
Reloads a worker after a specified time-to-live (TTL) interval.
13+
This ensures that workers are periodically restarted, which can help prevent issues caused by long-running processes.
14+
15+
| Option | Type | Default | Description |
16+
|--------|------|----------------|-----------------------------------|
17+
| `ttl` | int | *not set* | Time-to-live interval in seconds. |
18+
19+
### 🔄️ [MaxMemoryReloadStrategy](https://github.com/phpstreamserver/core/blob/main/src/ReloadStrategy/MaxMemoryReloadStrategy.php)
20+
21+
Reloads a worker when its memory consumption exceeds a specified threshold.
22+
This helps manage memory leaks and prevents excessive memory usage.
23+
24+
| Option | Type | Default | Description |
25+
|-------------|--------|----------------|----------------------------------------|
26+
| `maxMemory` | int | *not set* | Memory consumption threshold in bytes. |
27+
28+
### 🔄️ [ExceptionReloadStrategy](https://github.com/phpstreamserver/core/blob/main/src/ReloadStrategy/ExceptionReloadStrategy.php)
29+
30+
Reloads a worker when an exception is thrown, except for specified exceptions that are excluded from triggering a reload.
31+
This ensures workers don't remain in an unexpected state after encountering an error.
32+
33+
| Option | Type | Default | Description |
34+
|---------------------|----------------|----------------|---------------------------------------------------------------------------|
35+
| `allowedExceptions` | class-string[] | *not set* | Optional. A list of exception class names that will not trigger a reload. |
36+
37+
### 🔄️[🔌](/docs/plugins/http-server) [EachRequestReloadStrategy](https://github.com/phpstreamserver/http-server/blob/main/src/ReloadStrategy/EachRequestReloadStrategy.php)
38+
39+
This is the part of [Http Server Plugin](/docs/plugins/http-server)
40+
41+
This strategy reloads the worker after every HTTP request, making it primarily useful for debugging purposes.
42+
43+
This strategy does not have any specific configurable options.
44+
45+
### 🔄️[🔌](/docs/plugins/http-server) [MaxRequestsReloadStrategy](https://github.com/phpstreamserver/http-server/blob/main/src/ReloadStrategy/MaxRequestsReloadStrategy.php)
46+
47+
This is the part of [Http Server Plugin](/docs/plugins/http-server)
48+
49+
This strategy reloads the worker after handling a specified number of HTTP requests.
50+
51+
| Option | Type | Default | Description |
52+
|------------------------|------|----------------|---------------------------------------------------------------------------|
53+
| `maxRequests` | int | *not set* | The maximum number of requests a worker can handle before being reloaded. |
54+
| `dispersionPercentage` | int | 0 | Optional. Variability percantage to maxRequests. * |
55+
56+
\* Adds variability to the reload threshold to avoid restarting all workers simultaneously.
57+
For example, with maxRequests = 1000 and dispersionPercentage = 20, workers will be reloaded after handling between 800 and 1000 requests.

‎docs/plugins/file-monitor.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ $ composer require phpstreamserver/file-monitor
1616
## Example of usage
1717

1818
```php title="server.php"
19-
use PHPStreamServer\Core\Plugin\Supervisor\WorkerProcess;
2019
use PHPStreamServer\Core\Server;
20+
use PHPStreamServer\Core\WorkerProcess;
2121
use PHPStreamServer\Plugin\FileMonitor\FileMonitorPlugin;
2222
use PHPStreamServer\Plugin\FileMonitor\WatchDir;
2323

@@ -43,13 +43,9 @@ exit($server->run());
4343

4444
## Configuration
4545

46-
### 🔌 FileMonitorPlugin
46+
### 🔵 [WatchDir](https://github.com/phpstreamserver/file-monitor/blob/main/src/WatchDir.php)
4747

48-
| Option | Type | Default | Description |
49-
|---------|--------------------------|-----------------|------------------------------------------------------------------------|
50-
| `watch` | ...[WatchDir](#watchdir) | *not set* | List of WatchDir objects that define the files to monitor for changes. |
51-
52-
### 🔵 WatchDir
48+
WatchDir specifies the directory and file patterns to monitor.
5349

5450
| Option | Type | Default | Description |
5551
|---------------------|----------|----------------|-----------------------------------------------------------------------------|

‎docs/plugins/http-server.md‎

Lines changed: 0 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -52,59 +52,3 @@ $server->addWorker(
5252

5353
exit($server->run());
5454
```
55-
56-
## Configuration
57-
58-
### 🔌 HttpServerPlugin
59-
60-
| Option | Type | Default | Description |
61-
|-------------------------|--------|---------|------------------------------------------------------------------------------------|
62-
| `http2Enable` | bool | true | Optional. Enables support for HTTP/2 protocol. |
63-
| `httpConnectionTimeout` | int | 60 | Optional. Timeout duration for idle HTTP connections. |
64-
| `httpHeaderSizeLimit` | int | 32768 | Optional. Maximum allowed size for HTTP headers. |
65-
| `httpBodySizeLimit` | int | 131072 | Optional. Maximum allowed size for the HTTP request body. |
66-
| `gzipMinLength` | int | 860 | Optional. Minimum response size required to enable gzip compression. |
67-
| `gzipTypesRegex` | string | * | Optional. Regular expression to match content types eligible for gzip compression. |
68-
69-
\* `#^(?:text/.*+|[^/]*+/xml|[^+]*\+xml|application/(?:json|(?:x-)?javascript))$#i`
70-
71-
### ⚙️ HttpServerProcess
72-
73-
This worker type is designed to handle incoming HTTP requests asynchronously.
74-
75-
| Option | Type | Default | Description |
76-
|------------------------|--------------------------|----------------|--------------------------------------------------------------------------|
77-
| `listen` | string\|Listen\|Listen[] | *not set* | The address at which the server is listening. |
78-
| `name` | string | "HTTP Server" | Optional. The name associated with the worker process. |
79-
| `count` | int | 1 | Optional. The number of processes to start. |
80-
| `reloadable` | bool | true | Optional. Whether the worker can be reloaded with the reload command. |
81-
| `user` | string | *not set* | Optional. Unix user of process. Current user by default. |
82-
| `group` | string | *not set* | Optional. Unix group of process. Current group by default. |
83-
| `onStart` | Closure | *not set* | Optional. A callback function executed when the worker starts. |
84-
| `onRequest` | Closure | *not set* | Optional. A callback function executed when an HTTP request is received. |
85-
| `onStop` | Closure | *not set* | Optional. A callback function executed when the worker stops. |
86-
| `onReload` | Closure | *not set* | Optional. A callback function executed when the worker reloads. |
87-
| `middleware` | Middleware[] | *not set* | Optional. A list of middlewares for processing HTTP requests. |
88-
| `reloadStrategies` | ReloadStrategy[] | *not set* | Optional. The strategies used to reload the worker. |
89-
| `serverDir` | string | *not set* | Optional. The directory to serve static files from. |
90-
| `accessLog` | bool | true | Optional. Whether to log incoming HTTP requests. |
91-
| `gzip` | bool | false | Optional. Enables gzip compression. |
92-
| `connectionLimit` | int | *not set* | Optional. The maximum number of connections per worker. |
93-
| `connectionLimitPerIp` | int | *not set* | Optional. The maximum number of connections allowed per IP. |
94-
| `concurrencyLimit` | int | *not set* | Optional. The maximum number of concurrent HTTP requests per worker. |
95-
96-
### 🔄️ EachRequestReloadStrategy
97-
98-
This strategy reloads the worker after every HTTP request, making it primarily useful for debugging purposes.
99-
100-
### 🔄️ MaxRequestsReloadStrategy
101-
102-
This strategy reloads the worker after handling a specified number of HTTP requests.
103-
104-
| Option | Type | Default | Description |
105-
|------------------------|------|----------------|---------------------------------------------------------------------------|
106-
| `maxRequests` | int | *not set* | The maximum number of requests a worker can handle before being reloaded. |
107-
| `dispersionPercentage` | int | 0 | Optional. Variability percantage to maxRequests. * |
108-
109-
\* Adds variability to the reload threshold to avoid restarting all workers simultaneously.
110-
For example, with maxRequests = 1000 and dispersionPercentage = 20, workers will be reloaded after handling between 800 and 1000 requests.

0 commit comments

Comments
 (0)