From ee1b9bafc76c1a29e5fa39ef6738ea715e7e55ed Mon Sep 17 00:00:00 2001 From: Thomas Schneider Date: Fri, 27 Mar 2026 14:50:23 +0100 Subject: [PATCH] =?UTF-8?q?PHPDoc=20Kommentare=20f=C3=BCr=20Deployment-=20?= =?UTF-8?q?und=20Docker-Dienste=20hinzugef=C3=BCgt:=20Verbesserte=20Dokume?= =?UTF-8?q?ntation=20und=20Code-Nachvollziehbarkeit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/Service/Docker/DockerCompose.php | 143 ++++++++++++++++++++++++++- src/Service/Git/GitDeployment.php | 46 ++++++++- 2 files changed, 186 insertions(+), 3 deletions(-) diff --git a/src/Service/Docker/DockerCompose.php b/src/Service/Docker/DockerCompose.php index a381966..4f4c64b 100644 --- a/src/Service/Docker/DockerCompose.php +++ b/src/Service/Docker/DockerCompose.php @@ -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 diff --git a/src/Service/Git/GitDeployment.php b/src/Service/Git/GitDeployment.php index 16c04d8..05b327d 100644 --- a/src/Service/Git/GitDeployment.php +++ b/src/Service/Git/GitDeployment.php @@ -1,6 +1,6 @@ * 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