Budowa narzędzia CLI w PHP

PHP kojarzy się głównie z aplikacjami webowymi, ale bardzo dobrze sprawdza się też w narzędziach uruchamianych z terminala. CLI tool w PHP jest prosty do napisania, łatwy do wdrożenia i wygodny tam, gdzie potrzebujesz automatyzacji, przetwarzania plików, integracji z API albo szybkiego narzędzia dla zespołu. W praktyce taki program może robić wszystko: od porządkowania logów, przez generowanie raportów, po uruchamianie zadań administracyjnych. Jeśli dobrze go zaprojektujesz, stanie się małym, ale bardzo użytecznym elementem workflow.

Dlaczego PHP do CLI

Minimalna struktura projektu

my-tool/
├── bin/
│   └── my-tool
├── src/
│   ├── Command/
│   ├── Service/
│   └── Infrastructure/
├── vendor/
├── composer.json
└── .env

Punkt wejścia

#!/usr/bin/env php
<?php

require __DIR__ . '/../vendor/autoload.php';

echo "Hello from CLI tool" . PHP_EOL;

chmod +x bin/my-tool
./bin/my-tool

Argumenty i opcje

#!/usr/bin/env php
<?php

require __DIR__ . '/../vendor/autoload.php';

$args = $argv;
array_shift($args);

$command = $args[0] ?? null;

if ($command === null) {
    fwrite(STDERR, "Brak komendy.\n");
    exit(1);
}

echo "Uruchomiono komendę: {$command}" . PHP_EOL;

$options = getopt('', ['file:', 'dry-run']);

$file = $options['file'] ?? null;
$dryRun = array_key_exists('dry-run', $options);

if ($file === null) {
    fwrite(STDERR, "Musisz podać --file.\n");
    exit(1);
}

Komendy jako osobne klasy

namespace App\Command;

final class ImportCommand
{
    public function run(string $file, bool $dryRun = false): int
    {
        if (!file_exists($file)) {
            fwrite(STDERR, "Plik nie istnieje.\n");
            return 1;
        }

        if ($dryRun) {
            echo "Tryb testowy: import z {$file}\n";
            return 0;
        }

        echo "Importuję dane z {$file}\n";
        return 0;
    }
}

Warstwa usług

namespace App\Service;

final class ReportGenerator
{
    public function generate(array $rows): string
    {
        $lines = ["id,name,email"];

        foreach ($rows as $row) {
            $lines[] = implode(',', [
                $row['id'],
                $row['name'],
                $row['email'],
            ]);
        }

        return implode(PHP_EOL, $lines) . PHP_EOL;
    }
}

Odczyt i zapis plików

$input = fopen($file, 'r');

if ($input === false) {
    fwrite(STDERR, "Nie można otworzyć pliku.\n");
    exit(1);
}

while (($line = fgets($input)) !== false) {
    echo trim($line) . PHP_EOL;
}

fclose($input);

$output = fopen('output.txt', 'w');

if ($output === false) {
    fwrite(STDERR, "Nie można utworzyć pliku wyjściowego.\n");
    exit(1);
}

fwrite($output, "Gotowe\n");
fclose($output);

Logowanie i błędy

• STDOUT dla zwykłych informacji.
• STDERR dla błędów.
• kody wyjścia do sygnalizowania sukcesu lub porażki.

fwrite(STDOUT, "Start procesu...\n");
fwrite(STDERR, "Wystąpił błąd.\n");

exit(0);

Integracja z Composerem

{
  "name": "acme/my-tool",
  "require": {
    "php": "^8.2"
  },
  "autoload": {
    "psr-4": {
      "App\\": "src/"
    }
  },
  "bin": [
    "bin/my-tool"
  ]
}

composer dump-autoload

Przykład pełnego przepływu

namespace App\Command;

final class ImportCsvCommand
{
    public function run(string $file): int
    {
        if (!file_exists($file)) {
            fwrite(STDERR, "Plik nie istnieje.\n");
            return 1;
        }

        $handle = fopen($file, 'r');

        if ($handle === false) {
            fwrite(STDERR, "Nie można otworzyć pliku.\n");
            return 1;
        }

        $count = 0;

        while (($row = fgetcsv($handle)) !== false) {
            $count++;
        }

        fclose($handle);

        echo "Przetworzono {$count} rekordów.\n";
        return 0;
    }
}

#!/usr/bin/env php
<?php

require __DIR__ . '/../vendor/autoload.php';

use App\Command\ImportCsvCommand;

$file = $argv[1] ?? null;

if ($file === null) {
    fwrite(STDERR, "Użycie: my-tool <plik.csv>\n");
    exit(1);
}

$command = new ImportCsvCommand();
exit($command->run($file));