functions.php

<?php

namespace Deployer;

use Deployer\Exception\RunException;
use MoveElevator\DeployerTools\Utility\FeatureUtility;
use Symfony\Component\Console\Output\OutputInterface;

/**
 * @param $message
 * @return void
 */
function debug($message): void
{
    if (isVerbose() && !empty($message)) {
        writeln("<fg=yellow;options=bold>debug</> " . parse($message));
    }
}

/**
 * @return bool
 */
function isVerbose(): bool
{
    return in_array(output()->getVerbosity(), [OutputInterface::VERBOSITY_VERBOSE, OutputInterface::VERBOSITY_VERY_VERBOSE, OutputInterface::VERBOSITY_DEBUG], true);
}

/**
 * @return void
 */
function checkVerbosity(): void
{
    if (!empty(getenv('DEPLOYER_CONFIG_VERBOSE'))) {
        output()->setVerbosity(OutputInterface::VERBOSITY_VERBOSE);
    }
}

/**
 * Whether a feature instance was addressed via --feature.
 *
 * A blank --feature= counts as absent: it would otherwise resolve to the base
 * instance path and let the feature scaffolding write into the reference stage.
 * Only null and blank strings qualify — empty() would also swallow the perfectly
 * valid feature name "0". The option itself only exists once the feature recipe
 * is loaded, hence hasOption().
 *
 * @return bool
 */
function featureRequested(): bool
{
    if (!input()->hasOption('feature')) {
        return false;
    }
    $feature = input()->getOption('feature');

    return null !== $feature && '' !== trim((string)$feature);
}

/**
 * Normalize a feature identifier into the flat instance name used for the deploy
 * directory, the public url segment, the url shortener symlink and the database name.
 *
 * Branch names may carry path separators ("feature/ABC-12"), which would otherwise
 * nest the instance directory and break listing, cleanup and deletion. Identifiers
 * that already consist of allowed characters only are returned unchanged.
 *
 * @param ?string $feature
 * @return string
 */
function getFeatureName(?string $feature = null): string
{
    if (null === $feature || '' === trim($feature)) {
        $feature = featureRequested() ? (string)input()->getOption('feature') : '';
    }

    return FeatureUtility::normalize($feature);
}

/**
 * Extend the deployer configuration with available environment variables (starting with "DEPLOYER_CONFIG_"):
 *
 * ENVIRONMENT_VARIABLE => deployer_configuration
 * e.g.
 * DEPLOYER_CONFIG_DATABASE_PASSWORD => database_password
 *
 * @return void
 * @throws \Deployer\Exception\Exception
 */
function prepareDeployerConfiguration(): void {
    $environmentVariables = getenv();

    debug('Extending deployer configuration with environment variables');
    foreach ($environmentVariables as $key => $value) {
        if (str_starts_with($key, 'DEPLOYER_CONFIG_')) {
            $configName = strtolower(str_replace('DEPLOYER_CONFIG_', '', $key));

            if (has($configName)) {
                debug("Attention: overwriting existing deployer configuration '$configName' with environment variable '$key' ");
            }
            set($configName, $value);
        }
    }
}

/**
 * Check if a subcommand is available, e.g. "php bin/console", "ckeditor:install"
 *
 * @param string $command
 * @param string $subcommand
 * @return bool
 * @throws \Deployer\Exception\Exception
 * @throws \Deployer\Exception\RunException
 * @throws \Deployer\Exception\TimeoutException
 */
function commandSupportSubcommand(string $command, string $subcommand): bool
{
    $check = run("( $command list 2>&1 || $command --list) | grep -- $subcommand || true");
    if (empty($check)) {
        return false;
    }
    return str_contains($check, $subcommand);
}

/**
 * Check if command exists locally
 *
 * @throws RunException
 */
function commandExistLocally(string $command): bool
{
    return testLocally("hash $command 2>/dev/null");
}

/**
 * Checks whether a local path is executable. Unlike commandExistLocally()/hash (built
 * for PATH lookups), this reliably resolves a relative path containing a slash, e.g.
 * vendor/bin/sync-tool.
 */
function isExecutableLocally(string $path): bool
{
    return testLocally('[ -x ' . escapeshellarg($path) . ' ]');
}

/**
 * Resolves the sync tool binary to use: prefers the Composer-installed php-sync-tool
 * (https://github.com/konradmichalik/php-sync-tool) when present locally, falling back
 * to the legacy PATH-installed Python tool (db-sync-tool/file-sync-tool) otherwise.
 *
 * Lets each downstream project migrate independently by running
 * `composer require --dev konradmichalik/php-sync-tool` - no deploy.php opt-in needed.
 */
function resolveSyncTool(string $legacyBinary, string $phpBinary = 'vendor/bin/sync-tool'): string
{
    return isExecutableLocally($phpBinary) ? $phpBinary : $legacyBinary;
}

/**
 * Whether a resolved sync tool binary is php-sync-tool rather than the legacy tool.
 * Compared against the known php-sync-tool path, not path-shape - a downstream
 * project's legacy binary can itself be configured as an absolute or relative path,
 * which would otherwise be misclassified.
 */
function usingPhpSyncTool(string $resolvedBinary, string $phpBinary = 'vendor/bin/sync-tool'): bool
{
    return $resolvedBinary === $phpBinary;
}

/**
 * Checks whether a resolved sync tool binary is actually available locally: a path
 * (containing a slash) via isExecutableLocally(), a bare PATH command via
 * commandExistLocally().
 */
function syncToolAvailableLocally(string $binary): bool
{
    return str_contains($binary, '/')
        ? isExecutableLocally($binary)
        : commandExistLocally($binary);
}

/**
 * Resolves the sync tool binary and verifies it is actually available locally, or
 * throws. Used by the dev:* tasks, which have no "disabled" concept and must hard-fail
 * rather than silently skip when the tool is missing.
 *
 * @throws \RuntimeException if db_sync_tool was disabled or is not available locally
 */
function requireSyncTool(string $action): string
{
    $dbSyncTool = get('db_sync_tool');

    if (false === $dbSyncTool) {
        throw new \RuntimeException("db_sync_tool was disabled, cannot $action.");
    }

    if (!syncToolAvailableLocally($dbSyncTool)) {
        throw new \RuntimeException("Sync tool \"$dbSyncTool\" not available locally.");
    }

    return $dbSyncTool;
}

/**
 * Runs a remote command with the possibility to overwrite the default command options
 */
function runExtended(string $command, ?array $options = [], ?int $timeout = null, ?int $idle_timeout = null, ?string $secret = null, ?array $env = null, ?bool $real_time_output = null, ?bool $no_throw = null): string
{
    return run(
        $command,
        $options,
            $timeout ?? (int)get('run_timeout'),
            $idle_timeout ?? (int)get('run_idle_timeout'),
            $secret ?? (string)get('run_secret'),
            $env ?? (array)get('run_env'),
            $real_time_output ?? (bool)get('run_real_time_output'),
            $no_throw ?? (bool)get('run_no_throw')
    );
}

function getRecentDatabaseCacheDumpPath(): string
{
    return get('dev_tr_db_dump_dir') . '/' . getRecentDatabaseCacheDumpFilename() . '.sql';
}

function getRecentDatabaseCacheDumpFilename(): string
{
    return date('Y-m-d');
}

function recentDatabaseCacheDumpExists(): bool
{
    return test('[ -f ' . getRecentDatabaseCacheDumpPath() . ' ]');
}

function cleanUpDatabaseCacheDumps(int $days = 7): void
{
    $dbDumpDir = get('dev_tr_db_dump_dir');
    run("mkdir -p $dbDumpDir");

    // cleanup beforehand: delete all dump files with the above naming scheme older than 7 days
    run("find $dbDumpDir -name '*.sql' -mtime +$days -delete");
}

/**
 * Applies standardized file and directory permissions for a deployment.
 *
 * Handles:
 * - var/cache creation and writable permissions
 * - SGID-aware directory permissions for group inheritance
 * - Restrictive file permissions
 * - Shared directory baseline and writable permissions
 *
 * Config keys (with defaults):
 * - writable_chmod_mode_files: '644'
 * - writable_chmod_mode_dirs: '2755'
 * - writable_chmod_mode_writable_dirs: '2775'
 */
function applyDeployPermissions(): void
{
    $modeFiles = has('writable_chmod_mode_files') ? get('writable_chmod_mode_files') : '644';
    $modeDirs = has('writable_chmod_mode_dirs') ? get('writable_chmod_mode_dirs') : '2755';
    $modeWritableDirs = has('writable_chmod_mode_writable_dirs') ? get('writable_chmod_mode_writable_dirs') : '2775';

    // Ensure var/cache exists before any cache operation
    runExtended("cd {{ release_path }} && mkdir -p var/cache");

    // Set SGID + writable permissions on var directories
    runExtended("cd {{ release_path }} && chmod $modeWritableDirs var var/cache");

    // Set proper directory permissions with SGID for group inheritance, skip var
    runExtended("cd {{ release_path }} && find . -path \"./var\" -prune -o -type d -exec chmod $modeDirs {} +");

    // Set restrictive file permissions
    runExtended("cd {{ release_path }} && find . -type f -exec chmod $modeFiles {} +");

    // var/cache directories need recursive SGID+writable permissions; files need group-writable
    runExtended("cd {{ release_path }} && find var/cache -type d -exec chmod $modeWritableDirs {} +");
    runExtended("cd {{ release_path }} && find var/cache -type f -exec chmod 664 {} +");

    // Restore writable permissions on release-path-only writable dirs (not shared, not var)
    $sharedDirs = has('shared_dirs') ? get('shared_dirs') : [];
    foreach (has('writable_dirs') ? get('writable_dirs') : [] as $dir) {
        if (str_starts_with($dir, 'var') || in_array($dir, $sharedDirs)) {
            continue;
        }
        if (test("[ -d {{ release_path }}/$dir ]")) {
            runExtended("find {{ release_path }}/$dir -type d -exec chmod $modeWritableDirs {} +");
            runExtended("find {{ release_path }}/$dir -type f -exec chmod 664 {} +");
        }
    }

    // Fix shared directory permissions (baseline)
    runExtended("cd {{ deploy_path }}/shared && find . -type d -exec chmod $modeDirs {} +");
    runExtended("cd {{ deploy_path }}/shared && find . -type f -exec chmod $modeFiles {} +");

    // Shared writable directories need broader permissions (recursive for subdirectories)
    foreach (get('shared_dirs') as $dir) {
        if (test("[ -d {{ deploy_path }}/shared/$dir ]")) {
            runExtended("find {{ deploy_path }}/shared/$dir -type d -exec chmod $modeWritableDirs {} +");
        }
    }

    // Tighten permissions on shared sensitive files (.env, credentials)
    foreach (has('shared_files') ? get('shared_files') : [] as $file) {
        if (test("[ -f {{ deploy_path }}/shared/$file ]")) {
            runExtended("chmod 640 {{ deploy_path }}/shared/$file");
        }
    }
}