Your own service
A service is a plain class with two methods. Here we write the simplest one step by step: a small server that serves the files of a folder.
What your own service is and why
What it is. A class of your project that implements the Service interface.
The problem. There may be no ready-made service for the program you need.
The solution. Describe the program once, in a class — and declare it in one line, in this project and the next ones.
Service
The interface has two methods:
| Method | What it answers |
|---|---|
component() |
how to run the program: the command, the name, the checks |
image() |
what it needs in the image: packages, folders. When everything is there already — nothing |
Step 1. The class
Take a program every image with PHP already has — the built-in server php -S. It serves
the files of the public/ folder on port 8080:
namespace Main\Services;
use Flytachi\Winter\Kernel\App\Component;
use Flytachi\Winter\Kernel\App\Service;
use Flytachi\Winter\Kernel\App\ServiceImage;
final class StaticFiles implements Service
{
public function component(): Component
{
return Component::command(['php', '-S', '0.0.0.0:8080', '-t', 'public'], 'static-files');
}
public function image(): ServiceImage
{
return new ServiceImage(); // PHP is already in the image
}
}Component::command()— an outside program: the program first, then its arguments; the second parameter is its name in the logs.image()is empty: there is nothing to install.
Step 2. Declare it
use Main\Services\StaticFiles;
protected static function components(Components $components): void
{
$components->service(new StaticFiles());
}Start the application — the log says:
Application up: http://0.0.0.0:8000 + [static-files]
static-files is up.
Http is up.The files are served: curl localhost:8080/hello.txt.
The service already works, but plainly: it starts together with HTTP, and if it crashes,
the whole application stops (a service is critical by default, and it has no restarts).
Let us fix that.
Step 3. Teach it to wait and to watch
So far the application takes the service as ready the moment it is started. Add a few parameters:
public function component(): Component
{
return Component::command(
['php', '-S', '0.0.0.0:8080', '-t', 'public'],
'static-files',
priority: Priority::High, // start before HTTP, stop after it
ready: 'tcp://127.0.0.1:8080', // ready once the port answers
alive: 'tcp://127.0.0.1:8080', // then keep checking it
retries: 3, // restart it if it crashes
);
}| Parameter | What it gives |
|---|---|
priority: Priority::High |
the service starts before HTTP and stops after it |
ready |
the rest wait until the port answers |
alive |
the port keeps being checked; a hung service is restarted |
retries |
how many times to restart it after a crash |
Now the log is this — the service comes up first, and comes back after a crash:
Application starting High: static-files
static-files is up.
Application starting Normal: Http
Http is up.
static-files crashed: killed by signal 15; restart 1 of 3 in 1s.
static-files is up.Every parameter is on the components page.
Step 4. Parameters through the constructor
The port and the folder are handy to pass from outside:
namespace Main\Services;
use Flytachi\Winter\Kernel\App\Component;
use Flytachi\Winter\Kernel\App\Priority;
use Flytachi\Winter\Kernel\App\Service;
use Flytachi\Winter\Kernel\App\ServiceImage;
final class StaticFiles implements Service
{
public function __construct(
private readonly int $port = 8080,
private readonly string $dir = 'public',
) {
}
public function component(): Component
{
$check = "tcp://127.0.0.1:{$this->port}";
return Component::command(
['php', '-S', "0.0.0.0:{$this->port}", '-t', $this->dir],
'static-files',
priority: Priority::High,
ready: $check,
alive: $check,
retries: 3,
);
}
public function image(): ServiceImage
{
return new ServiceImage();
}
}$components->service(new StaticFiles(port: 9000, dir: 'storage/files'));A few tips
new StaticFiles()with no arguments should work — make the defaults sensible.- Keep the check light: is the port open, does
pinganswer. Not a heavy query. - Services the rest stand on get
Priority::High. - Open it to the outside only when needed. A service for your own code is fine on
127.0.0.1.
Next
- What the image needs — when the program is not in the image and has to be installed.
- PostgreSQL — what a ready-made service from a package looks like.