feat: add dedicated install-php playbook and command by loadinglucian · Pull Request #80 · loadinglucian/deployer-php

loadinglucian · 2025-11-11T10:19:46Z

Summary by CodeRabbit

New Features
- New CLI command to install PHP with selectable version and optional set-as-default; command replays chosen parameters.
- Server info now lists all detected PHP versions and highlights the default; per-version PHP-FPM metrics shown.
- PHP install flow now runs via its own playbook and configures PHP-FPM plus web server socket integration.
Chores
- Playbooks and helpers added PHP detection, apt retry/lock handling, and reporting back results to the CLI.
Chore (cleanup)
- Core server install playbook removed embedded PHP steps (moved to PHP install playbook).

coderabbitai · 2025-11-11T10:19:55Z

Walkthrough

Adds a standalone PHP install workflow (new CLI command and playbook), integrates multi-version PHP detection and per-version PHP-FPM metrics into server-info, removes PHP handling from the main server-install playbook, prepends playbook helpers to remote scripts, and registers the new command in the Symfony app.

Changes

Cohort / File(s)	Summary
Console commands `app/Console/Server/ServerInstallCommand.php`, `app/Console/Server/ServerInstallPhpCommand.php`, `app/SymfonyApp.php`	Added new `server:install:php` command (`ServerInstallPhpCommand`) with `--server`, `--php-version`, and `--php-default` options; `ServerInstallCommand` accepts PHP options and invokes `installPhp()` after server install; new command registered in `SymfonyApp`.
Server trait & flow `app/Traits/ServersTrait.php`	Added `installPhp(ServerDTO $server, array $info): array
Playbooks — new PHP installer `playbooks/server-install-php.sh`	New playbook that validates env vars, sets up distro-specific repos, installs PHP packages and FPM, configures sockets/status, optionally sets system default, updates Caddy, and emits YAML result (status, php_version, is_default, fpm_socket_path, tasks_completed).
Playbooks — server info `playbooks/server-info.sh`	Added `detect_php_versions()` and `detect_php_default()`; changed `get_php_fpm_metrics()` to accept a PHP version argument; emits per-version `php` blocks and per-version FPM metrics in output YAML; detection runs early in main.
Playbooks — demo site `playbooks/demo-site.sh`	Added `detect_php_default()` usage and replaced hardcoded PHP-FPM socket path with a dynamic path derived from detected PHP version; removed inlined permission helper usage.
Playbooks — server install `playbooks/server-install.sh`	Removed all PHP installation/configuration and PHP fields from YAML output; PHP setup delegated to `server-install-php.sh`; cleaned PHP-related tasks and monitoring endpoints.
Playbooks helpers & trait `playbooks/helpers.sh`, `app/Traits/PlaybooksTrait.php`	New `playbooks/helpers.sh` with `run_cmd()`, `detect_php_default()`, `wait_for_dpkg_lock()`, `apt_get_with_retry()`; `PlaybooksTrait` now prepends helpers into playbook scripts before remote execution.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as ServerInstallPhpCommand
    participant Trait as ServersTrait
    participant Playbook as server-install-php.sh
    participant Host as RemoteServer

    User->>CLI: run server:install:php --server --php-version [--php-default]
    CLI->>Trait: selectServer() / getServerInfo()
    Trait-->>CLI: ServerDTO + info
    CLI->>Trait: installPhp(server, info)
    note right of Trait `#DFF6E1`: prompt version choice / set-default
    Trait->>Playbook: exec playbook with env (DISTRO, PERMS, PHP_VERSION, SET_DEFAULT)
    rect rgb(220,240,255)
      Playbook->>Host: add repo / apt update
      Playbook->>Host: install php packages & fpm
      Playbook->>Host: configure php-fpm socket & status
      Playbook->>Host: set update-alternatives (if requested)
      Playbook->>Host: update caddy config & reload
      Playbook-->>Trait: YAML result (status, php_version, is_default, fpm_socket_path)
    end
    Trait-->>CLI: installation result
    CLI->>User: success/failure + command replay info

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Focus review on:
- playbooks/server-install-php.sh (distro repo logic, dpkg lock/retry, Caddy insertion).
- playbooks/server-info.sh (output YAML shape changes and per-version metrics).
- app/Traits/ServersTrait.php (new install flow, prompts, and return-value/exit-code semantics).
- End-to-end propagation of php_version and php_default through CLI → trait → playbook and command replay.

Possibly related PRs

bigpixelrocket/deployer-php#64 — Overlapping changes to traits and console helpers; likely touches the same install/display wiring.
bigpixelrocket/deployer-php#62 — Prior work on server-info playbook/command; overlaps per-version detection and metrics logic.
bigpixelrocket/deployer-php#77 — Related modifications to ServersTrait and PHP/PHP-FPM display and metrics aggregation.

Poem

🐰
I hopped into the playbook glade,
Where PHP versions stack and braid,
Defaults blossom, sockets sing,
Caddy hums and services spring,
A rabbit’s patch of code well-made. 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing a dedicated install-php playbook and corresponding command, which is the core theme across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/dedicated-install-php

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

playbooks/server-install.sh (1)
335-355: Remove stale PHP-FPM configuration logic.

This code block adds www-data to the deployer group and attempts to restart php8.4-fpm, but PHP installation has been moved to the separate server-install-php.sh playbook. At this point in execution, PHP may not be installed yet, causing this logic to either fail silently or reference non-existent services.

Apply this diff to remove the stale PHP-related configuration:
 	# Add www-data (PHP-FPM user) to deployer group so it can access files
-	if id -u www-data > /dev/null 2>&1; then
-		if ! id -nG www-data 2> /dev/null | grep -qw deployer; then
-			echo "✓ Adding www-data user to deployer group..."
-			if ! run_cmd usermod -aG deployer www-data; then
-				echo "Error: Failed to add www-data to deployer group" >&2
-				exit 1
-			fi
-
-			# Restart PHP-FPM so it picks up the new group membership
-			if systemctl is-active --quiet php8.4-fpm 2> /dev/null; then
-				echo "✓ Restarting PHP-FPM to apply group membership..."
-				if ! run_cmd systemctl restart php8.4-fpm; then
-					echo "Error: Failed to restart PHP-FPM" >&2
-					exit 1
-				fi
-			fi
-		fi
-	else
-		echo "Warning: PHP-FPM user 'www-data' not found, skipping group assignment"
-	fi
 }
Note: The www-data user group configuration should be handled in server-install-php.sh where PHP and PHP-FPM are actually installed.
playbooks/server-info.sh (1)
128-134: Extract duplicated helper functions to a shared module.

Multiple helper functions are duplicated across playbooks/server-info.sh, playbooks/demo-site.sh, playbooks/server-install.sh, and playbooks/server-install-php.sh:

run_cmd() - appears in all 4 playbooks with identical implementation

wait_for_dpkg_lock() - appears in server-install.sh and server-install-php.sh

apt_get_with_retry() - appears in server-install.sh and server-install-php.sh

detect_php_default() - appears in demo-site.sh and server-info.sh

Create a shared playbooks/helpers.sh file containing these common functions, then source it in each playbook:
#!/usr/bin/env bash
# playbooks/helpers.sh - Shared helper functions

# Permission Management
run_cmd() {
	if [[ $DEPLOYER_PERMS == 'root' ]]; then
		"$@"
	else
		sudo -n "$@"
	fi
}

# ... other shared functions
Then in each playbook:
# Source shared helpers
source "$(dirname "$0")/helpers.sh"
This eliminates duplication and ensures consistency across all playbooks.

Also applies to: 236-256

♻️ Duplicate comments (1)

playbooks/server-install-php.sh (1)

48-54: Consolidate duplicated helper functions.

The functions run_cmd(), wait_for_dpkg_lock(), and apt_get_with_retry() are duplicated across multiple playbooks. This has already been noted in the review of other files.

Refer to the comment on playbooks/server-info.sh for the recommended refactoring approach using a shared playbooks/helpers.sh file.

Also applies to: 63-93, 98-134

🧹 Nitpick comments (2)

app/Console/Server/ServerInstallPhpCommand.php (1)
74-82: Consider adding post-installation verification.

Unlike ServerInstallCommand which verifies the demo site via HTTP, this standalone PHP installation command doesn't verify that PHP-FPM is running and accessible. Consider adding a simple health check.

Example verification:
// After successful installation
$verification = $this->io->promptSpin(
    fn () => $this->verifyPhpFpm($server, $phpVersion),
    'Verifying PHP-FPM...'
);

if ($verification['status'] === 'success') {
    $this->yay($verification['message']);
}
Where verifyPhpFpm() could check the PHP-FPM status endpoint via Caddy proxy.
app/Traits/ServersTrait.php (1)
398-426: Extract hardcoded PHP versions to a class constant.

The list of PHP versions is hardcoded in the method body, making it harder to maintain and update when new PHP versions are released.

Apply this diff to extract to a constant:
+    /**
+     * Supported PHP versions for installation.
+     */
+    private const SUPPORTED_PHP_VERSIONS = ['5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5'];
+
     /**
      * Install PHP on a server.
      *
@@ -397,7 +400,6 @@
      */
     protected function installPhp(ServerDTO $server, array $info): array|int
     {
-        $phpVersions = ['5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5'];

         //
         // Extract installed PHP versions
@@ -419,7 +421,7 @@
         $phpVersion = (string) $this->io->getOptionOrPrompt(
             'php-version',
             fn () => $this->io->promptSelect(
                 label: 'PHP version:',
-                options: $phpVersions,
+                options: self::SUPPORTED_PHP_VERSIONS,
                 default: '8.4'
             )
         );

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2ba08b4 and f407e3d.

📒 Files selected for processing (8)

app/Console/Server/ServerInstallCommand.php (3 hunks)
app/Console/Server/ServerInstallPhpCommand.php (1 hunks)
app/SymfonyApp.php (2 hunks)
app/Traits/ServersTrait.php (2 hunks)
playbooks/demo-site.sh (2 hunks)
playbooks/server-info.sh (7 hunks)
playbooks/server-install-php.sh (1 hunks)
playbooks/server-install.sh (3 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.php

📄 CodeRabbit inference engine (.cursor/rules/00-main.mdc)

**/*.php: Eliminate single-use methods: inline if a method is called only once
Cache computed values: initialize expensive calculations in the constructor
Avoid method call overhead: prefer direct property access when appropriate

Files:

app/Traits/ServersTrait.php
app/Console/Server/ServerInstallPhpCommand.php
app/SymfonyApp.php
app/Console/Server/ServerInstallCommand.php

🧠 Learnings (8)