moko-platform/lib/Enterprise/PackageBuilder.php

<?php
/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 *
 * This file is part of a Moko Consulting project.
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * FILE INFORMATION
 * DEFGROUP: MokoStandards.Enterprise
 * INGROUP: MokoStandards.Lib
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
 * PATH: /lib/Enterprise/PackageBuilder.php
 * BRIEF: Builds release packages for generic, Dolibarr module, and Joomla component projects
 */

declare(strict_types=1);

namespace MokoEnterprise;

use RecursiveDirectoryIterator;
use RecursiveIteratorIterator;
use SplFileInfo;
use ZipArchive;

/**
 * Static factory that creates distributable ZIP release packages.
 *
 * Supports three project types: generic (src/admin/site layout), Dolibarr module
 * (src/ layout), and Joomla component (site/admin/media/language layout).
 * All methods return the path to the created archive (or would-create path in dry-run).
 */
class PackageBuilder
{
	// ── Public API ────────────────────────────────────────────────────────────

	/**
	 * Build a generic release package.
	 *
	 * Copies src/, admin/, site/, top-level *.xml files, LICENSE* files, and
	 * CHANGELOG.md into a build staging directory, then archives them as
	 * dist/<packageName>-<version>.zip.
	 *
	 * @param string $repoRoot    Absolute path to the repository root.
	 * @param string $packageName Base name for the archive.
	 * @param string $version     Version string (e.g. "1.2.0").
	 * @param bool   $dryRun      When true, preview without writing.
	 * @return string  Path to the created archive (or would-create path in dry-run).
	 * @throws \RuntimeException  When the zip archive cannot be opened.
	 */
	public static function buildGeneric(
		string $repoRoot,
		string $packageName,
		string $version,
		bool $dryRun = false
	): string {
		$buildDir   = $repoRoot . '/build';
		$packageDir = $buildDir . '/' . $packageName;
		$distDir    = $repoRoot . '/dist';
		$archivePath = $distDir . '/' . $packageName . '-' . $version . '.zip';

		if ($dryRun) {
			return $archivePath;
		}

		self::cleanDir($buildDir);
		self::cleanDir($distDir);
		mkdir($packageDir, 0755, true);
		mkdir($distDir, 0755, true);

		foreach (['src', 'admin', 'site'] as $dir) {
			if (is_dir($repoRoot . '/' . $dir)) {
				self::copyDirectory($repoRoot . '/' . $dir, $packageDir . '/' . $dir);
			}
		}

		foreach (glob($repoRoot . '/*.xml') ?: [] as $xml) {
			copy($xml, $packageDir . '/' . basename($xml));
		}

		foreach (glob($repoRoot . '/LICENSE*') ?: [] as $lic) {
			copy($lic, $packageDir . '/' . basename($lic));
		}

		if (is_file($repoRoot . '/CHANGELOG.md')) {
			copy($repoRoot . '/CHANGELOG.md', $packageDir . '/CHANGELOG.md');
		}

		self::zip($packageDir, $archivePath, $packageName);

		return $archivePath;
	}

	/**
	 * Build a Dolibarr module release package.
	 *
	 * Copies everything under src/ into a build staging directory and archives
	 * it as dist/<MODULE_NAME>_<VERSION>.zip.
	 *
	 * @param string $repoRoot   Absolute path to the repository root.
	 * @param string $moduleName Module name (used in archive filename).
	 * @param string $version    Version string.
	 * @param bool   $dryRun     When true, preview without writing.
	 * @return string  Path to the created archive (or would-create path in dry-run).
	 * @throws \RuntimeException  When src/ is absent or archive creation fails.
	 */
	public static function buildDolibarr(
		string $repoRoot,
		string $moduleName,
		string $version,
		bool $dryRun = false
	): string {
		$srcDir      = $repoRoot . '/src';
		$buildDir    = $repoRoot . '/build';
		$distDir     = $repoRoot . '/dist';
		$archivePath = $distDir . '/' . $moduleName . '_' . $version . '.zip';

		if (!is_dir($srcDir)) {
			throw new \RuntimeException("src/ directory not found at {$srcDir}");
		}

		if ($dryRun) {
			return $archivePath;
		}

		self::cleanDir($buildDir);
		self::cleanDir($distDir);
		mkdir($buildDir, 0755, true);
		mkdir($distDir, 0755, true);

		self::copyDirectory($srcDir, $buildDir);
		self::zip($buildDir, $archivePath, '');

		return $archivePath;
	}

	/**
	 * Build a Joomla component release package.
	 *
	 * Copies site/, admin/, optional media/ and language/ directories, and the
	 * component XML manifest into a build staging directory, then archives as
	 * dist/<componentName>_<version>.zip.
	 *
	 * @param string $repoRoot       Absolute path to the repository root.
	 * @param string $componentName  Component name, e.g. "com_example".
	 * @param string $version        Version string.
	 * @param bool   $dryRun         When true, preview without writing.
	 * @return string  Path to the created archive (or would-create path in dry-run).
	 * @throws \RuntimeException  When required directories are absent or archiving fails.
	 */
	public static function buildJoomla(
		string $repoRoot,
		string $componentName,
		string $version,
		bool $dryRun = false
	): string {
		$buildDir    = $repoRoot . '/build';
		$distDir     = $repoRoot . '/dist';
		$archivePath = $distDir . '/' . $componentName . '_' . $version . '.zip';

		if ($dryRun) {
			return $archivePath;
		}

		self::cleanDir($buildDir);
		self::cleanDir($distDir);
		mkdir($buildDir, 0755, true);
		mkdir($distDir, 0755, true);

		foreach (['site', 'admin'] as $required) {
			$src = $repoRoot . '/' . $required;
			if (!is_dir($src)) {
				throw new \RuntimeException("Required directory '{$required}/' not found at {$src}");
			}
			self::copyDirectory($src, $buildDir . '/' . $required);
		}

		foreach (['media', 'language'] as $optional) {
			$src = $repoRoot . '/' . $optional;
			if (is_dir($src)) {
				self::copyDirectory($src, $buildDir . '/' . $optional);
			}
		}

		$manifest = $repoRoot . '/' . $componentName . '.xml';
		if (is_file($manifest)) {
			copy($manifest, $buildDir . '/' . $componentName . '.xml');
		}

		self::zip($buildDir, $archivePath, '');

		return $archivePath;
	}

	// ── Private helpers ───────────────────────────────────────────────────────

	/**
	 * Remove a directory if it exists, then recreate it.
	 *
	 * @param string $dir  Directory path to clean.
	 */
	private static function cleanDir(string $dir): void
	{
		if (is_dir($dir)) {
			self::deleteDirectory($dir);
		}
	}

	/**
	 * Recursively copy a source directory to a destination.
	 *
	 * @param string $src  Source directory path.
	 * @param string $dst  Destination directory path.
	 */
	private static function copyDirectory(string $src, string $dst): void
	{
		if (!is_dir($dst)) {
			mkdir($dst, 0755, true);
		}

		$iter = new RecursiveIteratorIterator(
			new RecursiveDirectoryIterator($src, RecursiveDirectoryIterator::SKIP_DOTS),
			RecursiveIteratorIterator::SELF_FIRST
		);

		foreach ($iter as $item) {
			/** @var SplFileInfo $item */
			$target = $dst . '/' . $iter->getSubPathname();
			if ($item->isDir()) {
				if (!is_dir($target)) {
					mkdir($target, 0755, true);
				}
			} else {
				copy($item->getPathname(), $target);
			}
		}
	}

	/**
	 * Create a ZIP archive from a source directory tree.
	 *
	 * @param string $sourceDir  Directory to archive.
	 * @param string $archivePath  Destination archive path.
	 * @param string $prefix     Path prefix inside the archive (empty string for no prefix).
	 * @throws \RuntimeException  When the archive cannot be opened for writing.
	 */
	private static function zip(string $sourceDir, string $archivePath, string $prefix): void
	{
		$zip = new ZipArchive();
		if ($zip->open($archivePath, ZipArchive::CREATE | ZipArchive::OVERWRITE) !== true) {
			throw new \RuntimeException("Cannot create archive: {$archivePath}");
		}

		$iter = new RecursiveIteratorIterator(
			new RecursiveDirectoryIterator($sourceDir, RecursiveDirectoryIterator::SKIP_DOTS),
			RecursiveIteratorIterator::SELF_FIRST
		);

		foreach ($iter as $item) {
			/** @var SplFileInfo $item */
			$rel  = $iter->getSubPathname();
			$name = $prefix !== '' ? $prefix . '/' . $rel : $rel;
			if ($item->isFile()) {
				$zip->addFile($item->getPathname(), $name);
			} elseif ($item->isDir()) {
				$zip->addEmptyDir($name);
			}
		}

		$zip->close();
	}

	/**
	 * Recursively delete a directory and all its contents.
	 *
	 * @param string $dir  Directory path.
	 */
	private static function deleteDirectory(string $dir): void
	{
		if (!is_dir($dir)) {
			return;
		}

		$items = array_diff((array) scandir($dir), ['.', '..']);
		foreach ($items as $item) {
			$path = $dir . '/' . $item;
			is_dir($path) ? self::deleteDirectory($path) : unlink($path);
		}

		rmdir($dir);
	}
}