add new example showing how to gracefully stop Swoole servers in Docker

README.md

@@ -156,6 +156,7 @@ Here is a list of the examples under folder "_examples/_":
     * **21-supervisord-tasks**: to show how to run Supervisord program(s) when launching a one-off command with Docker. Please check the [README](https://github.com/swoole/docker-swoole/tree/master/examples/21-supervisord-tasks) file included to see how to run the example.
     * **22-supervisord-enable-program**: to show how to enable program(s) in Supervisord program.
     * **23-supervisord-disable-program**: to show how to disable Supervisord program(s).
+    * **[24-supervisord-gracefully-shutdown](examples/24-supervisord-gracefully-shutdown)**: how to gracefully stop Swoole servers (managed by `supervisord`) in Docker containers.
 * Debugging:
     * **30-debug-with-gdb**: Please check the [README](https://github.com/swoole/docker-swoole/tree/master/examples/30-debug-with-gdb) file included to see how to debug your PHP code with _gdb_.
     * **31-debug-with-valgrind**: Please check the [README](https://github.com/swoole/docker-swoole/tree/master/examples/31-debug-with-valgrind) file included to see how to debug your PHP code with _Valgrind_.

examples/24-supervisord-gracefully-shutdown/Dockerfile

@@ -0,0 +1,3 @@
+FROM phpswoole/swoole
+
+COPY ./rootfilesystem/ /

examples/24-supervisord-gracefully-shutdown/README.md

@@ -0,0 +1,42 @@
+# Gracefully Stop Swoole Servers In Docker Containers
+
+In this example, we will demonstrate how to gracefully stop Swoole servers in a Docker container. Note that we use
+`supervisord` to manage these Swoole servers in Docker containers.
+
+## How To Gracefully Stop Supervisord Programs In Docker Container
+
+### 1. Use command `exec` to run `supervisord` in the foreground.
+
+As we can see in the [entrypoint.sh] script, command `exec` is used to forward signals to `supervisord` processes:
+
+```bash
+exec /usr/bin/supervisord -c /etc/supervisor/supervisord.conf -n # Run supervisord in the foreground.
+```
+
+### 2. Set option `stopasgroup` to `true` in the `supervisord` configuration file(s).
+
+Also, please make sure that the `stopsignal` option is commented out or set to `TERM` (the default value), as we can see
+in the Supervisord configuration file [swoole.conf]:
+
+```ini
+stopasgroup=true
+; stopsignal=QUIT ; DON'T set this; it prevents graceful shutdown of Supervisord programs.
+```
+
+## Docker Commands To Play With This Example
+
+```bash
+docker compose up # Start the Docker container and monitor the logs.
+
+# You will need a separate terminal to run the following commands.
+
+docker compose exec -ti app supervisorctl status # Check the status of Supervisord programs.
+docker compose exec -ti app curl -i http://127.0.0.1:9501 # Check the status of the Swoole HTTP server.
+
+docker compose exec -ti app supervisorctl signal SIGTERM swoole # Send SIGTERM signal to the Swoole HTTP server.
+docker compose kill --signal=SIGTERM # Send SIGTERM signal to the Docker container.
+docker compose stop # Stop the Docker container.
+```
+
+[entrypoint.sh]: https://github.com/swoole/docker-swoole/blob/master/rootfilesystem/entrypoint.sh
+[swoole.conf]: https://github.com/swoole/docker-swoole/blob/master/rootfilesystem/etc/supervisor/service.d/swoole.conf

examples/24-supervisord-gracefully-shutdown/docker-compose.yml

@@ -0,0 +1,5 @@
+version: '3'
+
+services:
+  app:
+    build: .

examples/24-supervisord-gracefully-shutdown/rootfilesystem/var/www/server.php

@@ -0,0 +1,26 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+use Swoole\Http\Request;
+use Swoole\Http\Response;
+use Swoole\Http\Server;
+
+$http = new Server('0.0.0.0', 9501);
+
+$http->on('request', function (Request $request, Response $response): void {
+    $response->end('OK' . PHP_EOL);
+});
+$http->on('workerStop', function (Server $http, int $workerId): void {
+    // When the Docker container is stopped (e.g., by the `docker compose stop` command), event "onWorkerStop" is
+    // triggered in each worker process, allowing graceful shutdown of Swoole workers.
+    echo "Event \"onWorkerStop\" is triggered in worker #{$workerId}.", PHP_EOL;
+});
+$http->on('shutdown', function (Server $http): void {
+    // When the Docker container is stopped (e.g., by the `docker compose stop` command), event "onShutdown" is
+    // triggered, allowing graceful shutdown of Swoole server.
+    echo 'Event "onShutdown" is triggered.', PHP_EOL;
+});
+
+$http->start();