feat: add standalone PHAR distribution (#157)

* refactor: extract translation-validation command behavior into a shared trait

* feat: add standalone PHAR distribution

* refactor: simplify standalone command wiring and dedupe test setup

* fix: disable credential persistence on PHAR workflow checkout

Author: konradmichalik

.gitattributes

@@ -9,6 +9,7 @@
 /.gitattributes           export-ignore
 /.gitignore               export-ignore
 /.php-cs-fixer.php        export-ignore
+/box.json                 export-ignore
 /codecov.yml              export-ignore
 /composer.lock            export-ignore
 /Dockerfile               export-ignore

.github/workflows/phar.yml

@@ -0,0 +1,62 @@
+name: PHAR
+on:
+  push:
+    tags:
+      - '*'
+  pull_request:
+    branches:
+      - '**'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  phar:
+    runs-on: ubuntu-latest
+    name: Build PHAR
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.4'
+          extensions: libxml, mbstring, simplexml, dom, intl
+          tools: composer, box
+
+      - name: Install Composer dependencies (production only)
+        run: composer install --no-dev --no-interaction --no-progress
+
+      - name: Compile PHAR
+        run: box compile --no-interaction
+
+      - name: Smoke test (valid files -> exit 0)
+        run: php composer-translation-validator.phar tests/src/Fixtures/translations/xliff/success
+
+      - name: Smoke test (invalid files -> exit 1)
+        run: |
+          set +e
+          php composer-translation-validator.phar tests/src/Fixtures/translations/xliff/fail
+          code=$?
+          set -e
+          if [ "$code" -ne 1 ]; then
+            echo "Expected exit code 1 for invalid fixtures, got $code" >&2
+            exit 1
+          fi
+
+      - name: Generate checksum
+        if: startsWith(github.ref, 'refs/tags/')
+        run: sha256sum composer-translation-validator.phar > composer-translation-validator.phar.sha256
+
+      - name: Attach PHAR to release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            composer-translation-validator.phar
+            composer-translation-validator.phar.sha256

.gitignore

@@ -10,6 +10,9 @@
 /tests/composer.lock
 /tests/vendor
 
+# PHAR build artifacts
+/*.phar
+
 # Node.js / VitePress
 node_modules/
 docs/.vitepress/cache/

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- feat: provide a standalone PHAR distribution for CI and non-Composer projects
+
 ## [1.5.0] - 2026-06-29
 
 - feat: add target-language consistency check for XLIFF files (filename locale vs. declared target-language)

README.md

@@ -32,6 +32,8 @@ Supports XLIFF, YAML, JSON and PHP translation files.
 composer require --dev move-elevator/composer-translation-validator
 ```
 
+Alternatively, a dependency-free [standalone PHAR](https://move-elevator.github.io/composer-translation-validator/getting-started/installation#standalone-phar) is available for CI or non-Composer projects.
+
 ## 📊 Usage
 
 Validate your translation files by running the command:

bin/composer-translation-validator

@@ -0,0 +1,50 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the "composer-translation-validator" Composer plugin.
+ *
+ * (c) 2025-2026 Konrad Michalik <km@move-elevator.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use MoveElevator\ComposerTranslationValidator\Command\StandaloneValidateTranslationCommand;
+use Symfony\Component\Console\Application;
+
+(static function (): void {
+    $autoloads = [
+        __DIR__.'/../vendor/autoload.php',   // running from source / inside the PHAR
+        __DIR__.'/../../../autoload.php',     // installed as a dependency
+    ];
+
+    foreach ($autoloads as $autoload) {
+        if (is_file($autoload)) {
+            require $autoload;
+
+            return;
+        }
+    }
+
+    fwrite(\STDERR, 'Composer autoloader not found. Run "composer install".'.\PHP_EOL);
+    exit(1);
+})();
+
+// Replaced with the git tag by Box at compile time; stays literal when run from
+// source. The '@' check must not reference the placeholder string itself,
+// otherwise Box would replace it here too.
+$version = '@git_version@';
+if (str_contains($version, '@')) {
+    $version = 'dev';
+}
+
+$application = new Application('composer-translation-validator', $version);
+// The PHAR bundles the Symfony version pinned in composer.lock (>= 8), where
+// Application::addCommand() replaced the removed add().
+$application->addCommand(new StandaloneValidateTranslationCommand());
+$application->setDefaultCommand('validate-translations', true);
+
+exit($application->run());

box.json

@@ -0,0 +1,13 @@
+{
+	"$schema": "https://raw.githubusercontent.com/box-project/box/main/res/schema.json",
+	"main": "bin/composer-translation-validator",
+	"output": "composer-translation-validator.phar",
+	"compression": "GZ",
+	"git": "git_version",
+	"check-requirements": true,
+	"exclude-dev-files": true,
+	"blacklist": [
+		"src/Plugin.php",
+		"src/Capability/ValidateTranslationCommandProvider.php"
+	]
+}

docs/getting-started/installation.md

@@ -15,6 +15,34 @@ composer require --dev move-elevator/composer-translation-validator
 
 The plugin will be automatically registered with Composer and the `validate-translations` command becomes available.
 
+This is the recommended way to use the tool inside a Composer/PHP project.
+
+## Standalone PHAR
+
+For CI pipelines or non-Composer projects, a standalone PHAR is available. It runs as its own process with all dependencies bundled, so it never conflicts with your project's dependencies.
+
+Download the latest PHAR (and its checksum) from the [GitHub releases page](https://github.com/move-elevator/composer-translation-validator/releases):
+
+```bash
+curl -L -o composer-translation-validator.phar \
+  https://github.com/move-elevator/composer-translation-validator/releases/latest/download/composer-translation-validator.phar
+curl -L -o composer-translation-validator.phar.sha256 \
+  https://github.com/move-elevator/composer-translation-validator/releases/latest/download/composer-translation-validator.phar.sha256
+
+# Verify the download
+sha256sum -c composer-translation-validator.phar.sha256
+
+chmod +x composer-translation-validator.phar
+```
+
+Run it directly against your translation folders:
+
+```bash
+./composer-translation-validator.phar ./translations --recursive
+```
+
+The PHAR accepts the same arguments and options as the `validate-translations` command.
+
 ## Verify Installation
 
 Check that the command is available:

src/Command/StandaloneValidateTranslationCommand.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the "composer-translation-validator" Composer plugin.
+ *
+ * (c) 2025-2026 Konrad Michalik <km@move-elevator.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace MoveElevator\ComposerTranslationValidator\Command;
+
+use Symfony\Component\Console\Command\Command;
+
+/**
+ * StandaloneValidateTranslationCommand.
+ *
+ * @author Konrad Michalik <km@move-elevator.de>
+ * @license GPL-3.0-or-later
+ */
+class StandaloneValidateTranslationCommand extends Command
+{
+    use TranslationValidationBehavior;
+}