Services

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.

Contract ServiceMethods component() · image()Declaration $components->service()

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:

main/Services/StaticFiles.php
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

bootstrap.php
use Main\Services\StaticFiles;

protected static function components(Components $components): void
{
  $components->service(new StaticFiles());
}

Start the application — the log says:

text
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:

main/Services/StaticFiles.php
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:

text
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:

main/Services/StaticFiles.php
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();
  }
}
bootstrap.php
$components->service(new StaticFiles(port: 9000, dir: 'storage/files'));

A few tips

  1. new StaticFiles() with no arguments should work — make the defaults sensible.
  2. Keep the check light: is the port open, does ping answer. Not a heavy query.
  3. Services the rest stand on get Priority::High.
  4. 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.