innmind/server-control

Allows to control the server from php

6.1.0 2025-08-06 13:51 UTC

Requires

• php: ~8.2
• innmind/filesystem: ~8.0
• innmind/immutable: ~5.12
• innmind/io: ~3.1
• innmind/time-continuum: ^4.1.1
• innmind/time-warp: ~4.0
• innmind/url: ~4.0
• psr/log: ~3.0

Requires (Dev)

• innmind/black-box: ~6.5
• innmind/coding-standard: ~2.0
• innmind/static-analysis: ^1.2.1

MIT

• Baptiste Langlade

README

Give access to giving instructions to the server.

Important

To correctly use this library you must validate your code with vimeo/psalm

Installation

composer require innmind/server-control

Usage

use Innmind\Server\Control\{
    ServerFactory,
    Server\Command,
    Server\Process\Output\Chunk,
    Server\Process\Output\Type,
    Server\Process\Pid,
    Server\Signal,
    Server\Volumes\Name,
};
use Innmind\TimeContinuum\Clock;
use Innmind\TimeWarp\Halt\Usleep;
use Innmind\IO\IO;
use Innmind\Url\Path;
use Innmind\Immutable\Str;

$server = ServerFactory::build(
    Clock::live(),
    IO::fromAmbientAuthority(),
    Usleep::new(),
);
$server
    ->processes()
    ->execute(
        Command::foreground('bin/console')
            ->withArgument('debug:router')
    )
    ->unwrap()
    ->output()
    ->foreach(static function(Chunk $chunk): void {
        $type = match ($chunk->type()) {
            Type::error => 'ERR : ',
            Type::output => 'OUT : ',
        };

        echo $type.$chunk->data()->toString();
    });
$server
    ->processes()
    ->kill(
        new Pid(42),
        Signal::kill,
    )
    ->unwrap();
$server
    ->volumes()
    ->mount(new Name('/dev/disk2s1'), Path::of('/somewhere')) // the path is only interpreted for linux
    ->unwrap();
$server
    ->volumes()
    ->unmount(new Name('/dev/disk2s1'))
    ->unwrap();
$server->reboot()->unwrap();
$server->shutdown()->unwrap();

Scripts

Sometimes you may want to run a set of commands on your server. You can easily do so like this:

use Innmind\Server\Control\Server\{
    Script,
    Command,
};

$script = Script::of(
    Command::foreground('apt-get install php-fpm -y'),
    Command::foreground('service nginx start'),
);
$script($server);

If any command fails, it will stop the script and raise an exception.

Remote server control

use Innmind\Server\Control\Servers\Remote;
use Innmind\Url\Authority\{
    Host,
    Port,
    UserInformation\User,
};

$server = Remote::of(
    $server,
    User::of('john'),
    Host::of('example.com'),
    Port::of(42),
);
$server
    ->processes()
    ->execute(Command::foreground('ls'))
    ->unwrap();

This will run ssh -p 42 [e-mail] ls.

Important

Specifying environment variables or an input stream will not be taken into account on the remote server.

Logging

use Innmind\Server\Control\Servers\Logger;
use Psr\Log\LoggerInterface;

$server = Logger::psr($server, /** an instance of LoggerInterface */);

Mocking

In order to simplify testing code this library exposes a Mock server that can be configured like this:

use Innmind\Server\Control\{
    Servers\Mock,
    Servers\Mock\ProcessBuilder,
    Server\Command,
    Server\Process\Output\Chunk,
    Server\Process\Output\Type,
};
use Innmind\Immutable\{
    Sequence,
    Str,
};
use Innmind\BlackBox\Runner\Assert;

$assert = /* an instance of Assert */;
$server = Mock::new($assert)
    ->willReboot()
    ->willFailToReboot()
    ->willShutdown()
    ->willFailToShutdown()
    ->willMountVolume('volumeName', '/mount/endpoint')
    ->willFailToMountVolume('volumeName', '/mount/endpoint')
    ->willUnmountVolume('volumeName')
    ->willFailToUnmountVolume('volumeName')
    ->willExecute(
        static fn(Command $command) => $assert->same(
            "echo 'foo'",
            $command->toString(),
        ),
        static fn(Command $command, ProcessBuilder $build) => $build->success(
            Sequence::of(Chunk::of(
                Str::of('foo'),
                Type::output,
            )),
        ),
    )
    ->willExecute(
        static fn(Command $command) => $assert->same(
            "echo 'foobar'",
            $command->toString(),
        ),
        static fn(Command $command, ProcessBuilder $build) => $build->success([
            ['foobar', 'output'],
        ]),
    );

Important

The order in which you call the will* methods is the order in which the code you test needs to make these actions.