Snck3rs/Orchestar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

PHPDoc Kommentare für Deployment- und Docker-Dienste hinzugefügt: Verbesserte Dokumentation und Code-Nachvollziehbarkeit

Browse Source
This commit is contained in:
Thomas Schneider
2026-03-27 14:50:23 +01:00
parent 39042b0236
commit ee1b9bafc7
2 changed files with 186 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
src/Service/Docker/DockerCompose.php
View File

@@ -11,7 +11,6 @@ namespace App\Service\Docker;
use App\Service\Process\CleanProcess;
use Dotenv\Dotenv;
use Exception;
use Spatie\Docker\Exceptions\CouldNotStartDockerContainer;
use Symfony\Component\Filesystem\Filesystem;
use Symfony\Component\Process\Process;
@@ -36,8 +35,9 @@ class DockerCompose
protected array $inlineEnvFiles = [];
/**
* @throws CouldNotStartDockerContainer
* @todo Fehlerüberprüfung /-ausgabe optimieren
*/
public function up(array $optionalArgs = []): void
{
@@ -58,6 +58,17 @@ class DockerCompose
}
/**
* Generates a process instance for the given command.
*
* @param string $cmd The command to execute.
* @param array $optionalArgs Optional arguments to be appended to the command.
*
* @return Process The configured process instance.
*
* @todo Improve error handling and validation of environment variables.
* @todo Evaluate potential performance issues with environment loading and inline parsing.
*/
protected function process(string $cmd, array $optionalArgs = []): Process
{
$env = [...$this->loadDotEnv(), ...$this->parseInlineEnvFiles()];
@@ -76,6 +87,14 @@ class DockerCompose
}
/**
* Constructs and returns the base command array for the Docker Compose operations.
*
* @return array The assembled base command array, including the base compose command
* and additional Docker options.
*
* @todo Evaluate potential optimizations in command composition and handling.
*/
protected function getBaseCommand(): array
{
return [
@@ -85,6 +104,11 @@ class DockerCompose
}
/**
* @todo Review the logic for constructing extra Docker options, ensuring all possible options are correctly appended.
* @todo Validate and sanitize the inputs for docker host, name, compose files, and environment files if necessary.
* @todo Consider handling potential edge cases where input values might contain unexpected characters or formats.
*/
protected function getExtraDockerOptions(): array
{
$extraDockerOptions = [];
@@ -119,6 +143,15 @@ class DockerCompose
}
/**
* Retrieves additional options for the current process.
*
* If the application is running in daemon mode and the '-d' option
* is not already set, it will be appended to the resulting options array.
*
* @param array $optionalArgs Optional arguments to customize the options.
* @return array Merged array of optional arguments and inferred additional options.
*/
protected function getExtraOptions(array $optionalArgs = []): array
{
$extraOptions = [...$optionalArgs];
@@ -132,6 +165,15 @@ class DockerCompose
}
/**
* Sets the name property of the object.
*
* This method assigns the provided name to the object's internal property
* and returns the current instance for method chaining.
*
* @param string $name The name to set.
* @return self The current instance of the object.
*/
public function setName(string $name): self
{
$this->name = $name;
@@ -139,6 +181,16 @@ class DockerCompose
}
/**
* Sets the working directory.
*
* This method assigns the provided directory path to the internal
* working directory property and returns the current instance for
* method chaining.
*
* @param string $workingDir The path to set as the working directory.
* @return self The current instance for fluent interface usage.
*/
public function setWorkingDir(string $workingDir): self
{
$this->workingDir = $workingDir;
@@ -146,6 +198,15 @@ class DockerCompose
}
/**
* Sets the timeout value for the start command.
*
* This method assigns a specified timeout value to the start command
* and returns the current instance for method chaining.
*
* @param float $startCommandTimeout The timeout duration in seconds.
* @return self The current instance with the updated timeout value.
*/
public function setStartCommandTimeout(float $startCommandTimeout): self
{
$this->startCommandTimeout = $startCommandTimeout;
@@ -153,6 +214,16 @@ class DockerCompose
}
/**
* Sets the Docker host configuration.
*
* This method assigns the provided Docker host value to the corresponding property
* and returns the current instance for method chaining.
*
* @param string $dockerHost The Docker host address to be set.
*
* @return self The current instance of the class.
*/
public function setDockerHost(string $dockerHost): self
{
$this->dockerHost = $dockerHost;
@@ -160,6 +231,16 @@ class DockerCompose
}
/**
* Sets the daemonize mode for the application.
*
* This method allows enabling or disabling the daemon mode
* by setting a boolean value. The current instance of the class
* is returned to allow method chaining.
*
* @param bool $daemonize Indicates whether to enable or disable daemon mode.
* @return self The current instance of the class.
*/
public function daemonize(bool $daemonize): self
{
$this->daemonize = $daemonize;
@@ -167,6 +248,16 @@ class DockerCompose
}
/**
* Sets and merges Docker Compose files.
*
* This method updates the list of Docker Compose files by merging the
* provided array of files into the existing list. The operation ensures
* that the provided files are appended to the current set of files.
*
* @param array $composeFiles The array of Docker Compose file paths to add.
* @return self Returns the current instance for method chaining.
*/
public function setComposeFiles(array $composeFiles): self
{
$this->composeFiles = [...$this->composeFiles, ...$composeFiles];
@@ -174,6 +265,16 @@ class DockerCompose
}
/**
* Sets the environment files and merges them with the existing ones.
*
* This method appends the provided array of environment file paths to the
* existing list of files stored in the class. The updated list of files
* is then returned for further operations.
*
* @param array $envFiles An array of environment file paths to be added.
* @return self The current instance for method chaining.
*/
public function setEnvFiles(array $envFiles): self
{
$this->envFiles = [...$this->envFiles, ...$envFiles];
@@ -181,6 +282,16 @@ class DockerCompose
}
/**
* Sets the inline environment files and appends them to the existing list.
*
* This method updates the internal list of inline environment files by
* appending the provided array of file paths to the current list. It allows
* for dynamically adding environment file paths to be processed.
*
* @param array $envFiles An array of environment file paths to be added.
* @return self The current instance for method chaining.
*/
public function setInlineEnvFiles(array $envFiles): self
{
$this->inlineEnvFiles = [...$this->inlineEnvFiles, ...$envFiles];
@@ -188,12 +299,31 @@ class DockerCompose
}
/**
* Retrieves the list of inline environment files.
*
* This method returns an array containing the names of the environment
* files that are processed inline. These files typically contain environment
* variables that can be used by the application.
*
* @return array The list of inline environment file names.
*/
public function getInlineEnvFiles(): array
{
return $this->inlineEnvFiles;
}
/**
* Parses the inline environment files and merges their contents.
*
* This method iterates through a list of inline environment files,
* reads their content, and parses them into an associative array.
* Any files that cannot be read or parsed will be skipped. The resulting
* data from all parsed files is combined into a single array and returned.
*
* @return array The merged environment variables from the parsed files.
*/
protected function parseInlineEnvFiles(): array
{
$env = [];
@@ -218,6 +348,15 @@ class DockerCompose
}
/**
* Loads environment variables from the application's working directory.
*
* This method uses the Dotenv library to parse and retrieve environment
* variables defined in the designated working directory. If an error occurs
* during the loading process, an empty array is returned.
*
* @return array The environment variables loaded from the working directory.
*/
protected function loadDotEnv(): array
{
try

46
src/Service/Git/GitDeployment.php
View File

@@ -1,6 +1,6 @@
<?php
/*
* GitDeployment.php 2026-03-25 thomas
* GitDeployment.php 2026-03-27 thomas
*
* Copyright (c) 2026 Thomas Schneider <thomas@inter-mundos.de>
* Alle Rechte vorbehalten.
@@ -39,6 +39,20 @@ class GitDeployment extends DeploymentService
}
/**
* Handles the deployment process for the specified project by fetching the required
* resources and deploying the appropriate version.
*
* This method first fetches the necessary project resources. Then, it delegates
* the deployment process to the deployment method, optionally using the provided
* version and step parameters.
*
* @param Project $project The project to handle.
* @param string $version An optional specific version to deploy. Defaults to an empty string.
* @param string $step An optional step parameter used during the handling process. Defaults to an empty string.
*
* @return void
*/
public function handle(Project $project, string $version = '', string $step = ''): void
{
$this->fetch($project);
@@ -46,6 +60,23 @@ class GitDeployment extends DeploymentService
}
/**
* Fetches the latest updates for the specified project's repository.
* Depending on the state of the repository directory, either a fetch or
* a full clone operation is performed. Supports authenticated access to
* repositories when a URL with HTTP is provided.
*
* If the repository is already cloned, this method performs a fetch operation
* to synchronize the local repository. Otherwise, it clones the repository in
* mirror mode to the designated directory.
*
* During the process, the deployment step is updated to reflect the current
* stage of the fetch operation for the given project.
*
* @param Project $project The project whose repository updates are to be fetched.
*
* @return void
*/
public function fetch(Project $project): void
{
$this->projectConfigDirService->setDeploymentStep($project->projectDir, 'fetch');
@@ -81,6 +112,19 @@ class GitDeployment extends DeploymentService
}
/**
* Deploys the specified project by preparing a clean working directory,
* cloning the git repository, and checking out the appropriate version.
*
* If the version is set to "default", it translates to the current state of
* the default branch in the repository. If set to "latest" or if no version
* is provided, the latest release of the repository is checked out.
*
* @param Project $project The project to be deployed.
* @param string $version The version to be deployed, which could be explicit, "default", or "latest".
*
* @return void
*/
public function deploy(Project $project, string $version): void
{
# remove work tree