19601180552

Committed 22 Nov 2025 09:03PM UTC coverage: 98.214% (+9.2%) from 88.971%

Build # 19601180552

Build Type

push

github

Committed by

diego-ninja

Commit Message

docs: facade documentation updated

Run Details

550 of 560 relevant lines covered (98.21%)

13.01 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

97.27

/src/DockerContainerInstance.php

<?php

// ABOUTME: Represents a running Docker container instance with execution capabilities.
// ABOUTME: Provides methods to execute commands, manage files, and inspect container state.

declare(strict_types=1);

namespace Ninja\Docker;

use JsonException;
use Ninja\Docker\ValueObjects\ContainerPath;
use Ninja\Docker\ValueObjects\HostPath;
use RuntimeException;
use Spatie\Macroable\Macroable;
use Symfony\Component\Process\Exception\ProcessFailedException;
use Symfony\Component\Process\Process;

class DockerContainerInstance
{
    use Macroable;

    public const string DEFAULT_PATH_AUTHORIZED_KEYS = '/root/.ssh/authorized_keys';

    public function __construct(
        private readonly DockerContainer $config,
        private readonly string $dockerIdentifier,
        private readonly string $name
    ) {}

    public static function fromExisting(string $name): self
    {
        return new self(
            config: DockerContainer::create(
                image: self::getImageFromExistingContainer($name),
                name: $name
            ),
            dockerIdentifier: self::getIdFromExistingContainer($name),
            name: $name
        );
    }

    public static function isRunning(string $name): bool
    {
        $process = new Process([
            'docker',
            'ps',
            '-q',
            '-f',
            "name={$name}",
        ]);

        $process->run();

        return !empty(trim($process->getOutput()));
    }

    public function __destruct()
    {
        if ($this->config->stopOnDestruct) {
            $this->stop();
        }
    }

    public function start(bool $async = false): Process
    {
        $fullCommand = $this->config->getStartCommand($this->getShortDockerIdentifier());
        $process     = new Process($fullCommand);

        $async ? $process->start() : $process->run();

        return $process;
    }

    public function stop(bool $async = false): Process
    {
        $fullCommand = $this->config->getStopCommand($this->getShortDockerIdentifier());
        $process     = new Process($fullCommand);

        $async ? $process->start() : $process->run();

        return $process;
    }

    public function getName(): string
    {
        return $this->name;
    }

    public function getConfig(): DockerContainer
    {
        return $this->config;
    }

    public function getDockerIdentifier(): string
    {
        return $this->dockerIdentifier;
    }

    public function getShortDockerIdentifier(): string
    {
        return substr($this->dockerIdentifier, 0, 12);
    }

    public function execute(string $command): string
    {
        $dockerCommand = array_merge(
            $this->config->getBaseCommand(),
            ['exec', '--interactive', $this->getShortDockerIdentifier(), $this->config->shell]
        );

        $process = new Process($dockerCommand);
        $process->setInput($command);
        $process->setTimeout(null);
        $process->run();

        if (!$process->isSuccessful()) {
            throw new RuntimeException(
                "Command execution failed: {$process->getErrorOutput()}"
            );
        }

        return $process->getOutput();
    }

    public function addPublicKey(
        HostPath|string $pathToPublicKey,
        ContainerPath|string $pathToAuthorizedKeys = self::DEFAULT_PATH_AUTHORIZED_KEYS
    ): self {
        $publicKeyPath = $pathToPublicKey instanceof HostPath
            ? $pathToPublicKey
            : HostPath::from($pathToPublicKey);

        $authorizedKeysPath = $pathToAuthorizedKeys instanceof ContainerPath
            ? $pathToAuthorizedKeys
            : ContainerPath::from($pathToAuthorizedKeys);

        $contents = file_get_contents((string)$publicKeyPath);
        if ($contents === false) {
            throw new RuntimeException(
                sprintf("Could not read contents of public key at %s", (string)$publicKeyPath)
            );
        }

        $publicKeyContents = trim($contents);
        $sshDir            = dirname((string)$authorizedKeysPath);

        $this->execute("mkdir -p {$sshDir}");
        $this->execute("chmod 700 {$sshDir}");
        $this->execute("echo '{$publicKeyContents}' >> {$authorizedKeysPath}");
        $this->execute("chmod 600 {$authorizedKeysPath}");
        $this->execute("chown root:root {$authorizedKeysPath}");

        return $this;
    }

    /**
     * @param string $fileOrDirectoryOnHost
     * @param string $pathInContainer
     * @return self
     * @throws ProcessFailedException
     */
    public function addFiles(string $fileOrDirectoryOnHost, string $pathInContainer): self
    {
        $fullCommand = $this->config->getCopyCommand($this->getShortDockerIdentifier(), $fileOrDirectoryOnHost, $pathInContainer);

        $process = new Process($fullCommand);

        $process->run();

        if (!$process->isSuccessful()) {
            throw new ProcessFailedException($process);
        }

        return $this;
    }

    /**
     * @return list<array<string, mixed>>
     * @throws JsonException
     */
    public function inspect(): array
    {
        $fullCommand = $this->config->getInspectCommand($this->getShortDockerIdentifier());

        $process = new Process($fullCommand);
        $process->run();

        $json = trim($process->getOutput());

        /** @var list<array<string, mixed>> $result */
        $result = json_decode($json, true, 512, JSON_THROW_ON_ERROR);

        return $result;
    }

    private static function getImageFromExistingContainer(string $name): string
    {
        $process = new Process([
            'docker',
            'ps',
            '--format={{.Image}}',
            '-f',
            "name={$name}",
        ]);

        $process->run();

        return trim($process->getOutput());
    }

    private static function getIdFromExistingContainer(string $name): string
    {
        $process = new Process([
            'docker',
            'ps',
            '-q',
            '-f',
            "name={$name}",
        ]);

        $process->run();

        return trim($process->getOutput());
    }

}

1	<?php
2
3	// ABOUTME: Represents a running Docker container instance with execution capabilities.
4	// ABOUTME: Provides methods to execute commands, manage files, and inspect container state.
5
6	declare(strict_types=1);
7
8	namespace Ninja\Docker;
9
10	use JsonException;
11	use Ninja\Docker\ValueObjects\ContainerPath;
12	use Ninja\Docker\ValueObjects\HostPath;
13	use RuntimeException;
14	use Spatie\Macroable\Macroable;
15	use Symfony\Component\Process\Exception\ProcessFailedException;
16	use Symfony\Component\Process\Process;
17
18	class DockerContainerInstance
19	{
20	use Macroable;
21
22	public const string DEFAULT_PATH_AUTHORIZED_KEYS = '/root/.ssh/authorized_keys';
23
24	public function __construct(	27✔
25	private readonly DockerContainer $config,
26	private readonly string $dockerIdentifier,
27	private readonly string $name
28	) {}	27✔
29
30	public static function fromExisting(string $name): self	1✔
31	{
32	return new self(	1✔
33	config: DockerContainer::create(	1✔
34	image: self::getImageFromExistingContainer($name),	1✔
35	name: $name	1✔
36	),	1✔
37	dockerIdentifier: self::getIdFromExistingContainer($name),	1✔
38	name: $name	1✔
39	);	1✔
40	}
41
42	public static function isRunning(string $name): bool	5✔
43	{
44	$process = new Process([	5✔
45	'docker',	5✔
46	'ps',	5✔
47	'-q',	5✔
48	'-f',	5✔
49	"name={$name}",	5✔
50	]);	5✔
51
52	$process->run();	5✔
53
54	return !empty(trim($process->getOutput()));	5✔
55	}
56
57	public function __destruct()	20✔
58	{
59	if ($this->config->stopOnDestruct) {	20✔
60	$this->stop();	5✔
61	}
62	}
63
64	public function start(bool $async = false): Process	2✔
65	{
66	$fullCommand = $this->config->getStartCommand($this->getShortDockerIdentifier());	2✔
67	$process = new Process($fullCommand);	2✔
68
69	$async ? $process->start() : $process->run();	2✔
70
71	return $process;	2✔
72	}
73
74	public function stop(bool $async = false): Process	13✔
75	{
76	$fullCommand = $this->config->getStopCommand($this->getShortDockerIdentifier());	13✔
77	$process = new Process($fullCommand);	13✔
78
79	$async ? $process->start() : $process->run();	13✔
80
81	return $process;	13✔
82	}
83
84	public function getName(): string	5✔
85	{
86	return $this->name;	5✔
87	}
88
89	public function getConfig(): DockerContainer	1✔
90	{
91	return $this->config;	1✔
92	}
93
94	public function getDockerIdentifier(): string	4✔
95	{
96	return $this->dockerIdentifier;	4✔
97	}
98
99	public function getShortDockerIdentifier(): string	20✔
100	{
101	return substr($this->dockerIdentifier, 0, 12);	20✔
102	}
103
104	public function execute(string $command): string	8✔
105	{
106	$dockerCommand = array_merge(	8✔
107	$this->config->getBaseCommand(),	8✔
108	['exec', '--interactive', $this->getShortDockerIdentifier(), $this->config->shell]	8✔
109	);	8✔
110
111	$process = new Process($dockerCommand);	8✔
112	$process->setInput($command);	8✔
113	$process->setTimeout(null);	8✔
114	$process->run();	8✔
115
116	if (!$process->isSuccessful()) {	8✔
117	throw new RuntimeException(	1✔
118	"Command execution failed: {$process->getErrorOutput()}"	1✔
119	);	1✔
120	}
121
122	return $process->getOutput();	7✔
123	}
124
125	public function addPublicKey(	5✔
126	HostPath\|string $pathToPublicKey,
127	ContainerPath\|string $pathToAuthorizedKeys = self::DEFAULT_PATH_AUTHORIZED_KEYS
128	): self {
129	$publicKeyPath = $pathToPublicKey instanceof HostPath	5✔
130	? $pathToPublicKey	1✔
131	: HostPath::from($pathToPublicKey);	4✔
132
133	$authorizedKeysPath = $pathToAuthorizedKeys instanceof ContainerPath	4✔
134	? $pathToAuthorizedKeys	1✔
135	: ContainerPath::from($pathToAuthorizedKeys);	3✔
136
137	$contents = file_get_contents((string)$publicKeyPath);	4✔
138	if ($contents === false) {	4✔
139	throw new RuntimeException(	×
140	sprintf("Could not read contents of public key at %s", (string)$publicKeyPath)	×
141	);	×
142	}
143
144	$publicKeyContents = trim($contents);	4✔
145	$sshDir = dirname((string)$authorizedKeysPath);	4✔
146
147	$this->execute("mkdir -p {$sshDir}");	4✔
148	$this->execute("chmod 700 {$sshDir}");	4✔
149	$this->execute("echo '{$publicKeyContents}' >> {$authorizedKeysPath}");	4✔
150	$this->execute("chmod 600 {$authorizedKeysPath}");	4✔
151	$this->execute("chown root:root {$authorizedKeysPath}");	4✔
152
153	return $this;	4✔
154	}
155
156	/**
157	* @param string $fileOrDirectoryOnHost
158	* @param string $pathInContainer
159	* @return self
160	* @throws ProcessFailedException
161	*/
162	public function addFiles(string $fileOrDirectoryOnHost, string $pathInContainer): self	2✔
163	{
164	$fullCommand = $this->config->getCopyCommand($this->getShortDockerIdentifier(), $fileOrDirectoryOnHost, $pathInContainer);	2✔
165
166	$process = new Process($fullCommand);	2✔
167
168	$process->run();	2✔
169
170	if (!$process->isSuccessful()) {	2✔
171	throw new ProcessFailedException($process);	1✔
172	}
173
174	return $this;	1✔
175	}
176
177	/**
178	* @return list<array<string, mixed>>
179	* @throws JsonException
180	*/
181	public function inspect(): array	1✔
182	{
183	$fullCommand = $this->config->getInspectCommand($this->getShortDockerIdentifier());	1✔
184
185	$process = new Process($fullCommand);	1✔
186	$process->run();	1✔
187
188	$json = trim($process->getOutput());	1✔
189
190	/** @var list<array<string, mixed>> $result */
191	$result = json_decode($json, true, 512, JSON_THROW_ON_ERROR);	1✔
192
193	return $result;	1✔
194	}
195
196	private static function getImageFromExistingContainer(string $name): string	1✔
197	{
198	$process = new Process([	1✔
199	'docker',	1✔
200	'ps',	1✔
201	'--format={{.Image}}',	1✔
202	'-f',	1✔
203	"name={$name}",	1✔
204	]);	1✔
205
206	$process->run();	1✔
207
208	return trim($process->getOutput());	1✔
209	}
210
211	private static function getIdFromExistingContainer(string $name): string	1✔
212	{
213	$process = new Process([	1✔
214	'docker',	1✔
215	'ps',	1✔
216	'-q',	1✔
217	'-f',	1✔
218	"name={$name}",	1✔
219	]);	1✔
220
221	$process->run();	1✔
222
223	return trim($process->getOutput());	1✔
224	}
225
226	}

diego-ninja / docker / 19601180552

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous