PHP โปรเจกต์: เครื่องมือ CLI ดึงข้อมูลและทำรายงาน



PHP ไม่ได้มีไว้ทำแค่เว็บ — เขียนสคริปต์ CLI สำหรับงาน batch, cron, ETL ได้ดี โปรเจกต์นี้ทำเครื่องมือดึงข้อมูล repo จาก GitHub API แล้วออกรายงาน

สิ่งที่ทำได้

php bin/report.php --user=php --format=csv --output=report.csv
php bin/report.php --user=symfony --format=json --limit=10
php bin/report.php --help
  • ดึงรายการ repo ของ user/org จาก GitHub API
  • เรียงตามจำนวนดาว
  • ออกเป็น CSV หรือ JSON
  • exit code: 0 สำเร็จ, 1 error ทั่วไป, 2 argument ผิด

โครงสร้าง

gh-report/
├── bin/report.php          ← entry point
├── src/
│   ├── Cli.php              ← parse argument + help
│   ├── GitHubClient.php     ← cURL
│   └── ReportWriter.php     ← CSV / JSON
└── composer.json
{
    "require": { "php": ">=8.3", "ext-curl": "*", "ext-json": "*" },
    "autoload": { "psr-4": { "App\\": "src/" } },
    "bin": ["bin/report.php"]
}

src/Cli.php

<?php
declare(strict_types=1);

namespace App;

final class Cli
{
    public const USAGE = <<<TXT
    ใช้งาน: php bin/report.php --user=<ชื่อ> [ตัวเลือก]

      --user=NAME       ชื่อ user หรือ org บน GitHub (จำเป็น)
      --format=FORMAT   csv | json          (ค่าเริ่มต้น: csv)
      --output=FILE     เขียนลงไฟล์แทน stdout
      --limit=N         เอาแค่ N repo แรก    (ค่าเริ่มต้น: 30)
      --help            แสดงข้อความนี้
    TXT;

    /** @return array{user:string, format:string, output:?string, limit:int} */
    public static function parse(array $argv): array
    {
        $opts = getopt('', ['user:', 'format:', 'output:', 'limit:', 'help']);

        if (isset($opts['help']) || $opts === false) {
            fwrite(STDOUT, self::USAGE . "\n");
            exit(0);
        }

        $user = $opts['user'] ?? null;
        if (!is_string($user) || $user === '') {
            self::fail('ต้องระบุ --user');
        }

        $format = $opts['format'] ?? 'csv';
        if (!in_array($format, ['csv', 'json'], true)) {
            self::fail("--format ต้องเป็น csv หรือ json (ได้: $format)");
        }

        $limit = (int) ($opts['limit'] ?? 30);
        if ($limit < 1 || $limit > 100) {
            self::fail('--limit ต้องอยู่ 1–100');
        }

        return [
            'user'   => $user,
            'format' => $format,
            'output' => isset($opts['output']) ? (string) $opts['output'] : null,
            'limit'  => $limit,
        ];
    }

    public static function fail(string $message): never
    {
        fwrite(STDERR, "ผิดพลาด: $message\n\n" . self::USAGE . "\n");
        exit(2);
    }
}

getopt() เป็นตัว parse argument ในตัว PHP — 'user:' (มี :) = ต้องมีค่า, 'help' (ไม่มี :) = flag เปล่า

src/GitHubClient.php

<?php
declare(strict_types=1);

namespace App;

use RuntimeException;

final class GitHubClient
{
    private const BASE = 'https://api.github.com';

    public function __construct(private ?string $token = null) {}

    /** @return list<array{name:string, stars:int, language:?string, url:string}> */
    public function repos(string $user, int $limit): array
    {
        $result = [];
        $page = 1;

        while (count($result) < $limit) {
            $batch = $this->get("/users/{$user}/repos?per_page=100&page={$page}&sort=updated");
            if ($batch === []) {
                break;
            }
            foreach ($batch as $repo) {
                $result[] = [
                    'name'     => $repo['name'],
                    'stars'    => $repo['stargazers_count'],
                    'language' => $repo['language'] ?? null,
                    'url'      => $repo['html_url'],
                ];
            }
            $page++;
        }

        usort($result, fn ($a, $b) => $b['stars'] <=> $a['stars']);
        return array_slice($result, 0, $limit);
    }

    private function get(string $path): array
    {
        $ch = curl_init(self::BASE . $path);
        $headers = ['Accept: application/vnd.github+json', 'User-Agent: gh-report/1.0'];
        if ($this->token !== null) {
            $headers[] = 'Authorization: Bearer ' . $this->token;
        }

        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => $headers,
            CURLOPT_TIMEOUT        => 15,
            CURLOPT_CONNECTTIMEOUT => 5,
        ]);

        $body   = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
        $err    = curl_error($ch);
        curl_close($ch);

        if ($body === false) {
            throw new RuntimeException("เชื่อมต่อ GitHub ไม่ได้: $err");
        }
        if ($status === 404) {
            throw new RuntimeException("ไม่พบ user นี้บน GitHub");
        }
        if ($status === 403) {
            throw new RuntimeException('ถูก rate limit — ลองใหม่ภายหลัง หรือใส่ GITHUB_TOKEN');
        }
        if ($status !== 200) {
            throw new RuntimeException("GitHub ตอบ HTTP $status");
        }

        return json_decode($body, true, flags: JSON_THROW_ON_ERROR);
    }
}

src/ReportWriter.php

<?php
declare(strict_types=1);

namespace App;

final class ReportWriter
{
    /**
     * @param list<array<string,mixed>> $rows
     */
    public static function write(array $rows, string $format, ?string $output): void
    {
        $stream = $output !== null
            ? (fopen($output, 'w') ?: throw new \RuntimeException("เขียน $output ไม่ได้"))
            : STDOUT;

        match ($format) {
            'json' => self::json($rows, $stream),
            'csv'  => self::csv($rows, $stream),
        };

        if ($output !== null) {
            fclose($stream);
            fwrite(STDOUT, "เขียนรายงาน {$output} (" . count($rows) . " แถว)\n");
        }
    }

    private static function csv(array $rows, $stream): void
    {
        if ($rows === []) {
            return;
        }
        fwrite($stream, "\xEF\xBB\xBF");               // BOM ให้ Excel อ่าน UTF-8 ถูก
        fputcsv($stream, array_keys($rows[0]));
        foreach ($rows as $row) {
            fputcsv($stream, $row);
        }
    }

    private static function json(array $rows, $stream): void
    {
        fwrite($stream, json_encode(
            $rows,
            JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT,
        ) . "\n");
    }
}

bin/report.php

#!/usr/bin/env php
<?php
declare(strict_types=1);

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

use App\{Cli, GitHubClient, ReportWriter};

// รับเฉพาะตอนรันจาก CLI
if (PHP_SAPI !== 'cli') {
    http_response_code(403);
    exit('CLI เท่านั้น');
}

$args = Cli::parse($argv);

try {
    $client = new GitHubClient(getenv('GITHUB_TOKEN') ?: null);

    fwrite(STDERR, "กำลังดึงข้อมูล {$args['user']} ...\n");
    $repos = $client->repos($args['user'], $args['limit']);

    if ($repos === []) {
        fwrite(STDERR, "ไม่มี repo\n");
        exit(0);
    }

    ReportWriter::write($repos, $args['format'], $args['output']);
    exit(0);

} catch (\Throwable $e) {
    fwrite(STDERR, 'ผิดพลาด: ' . $e->getMessage() . "\n");
    exit(1);
}

รัน

composer dump-autoload
chmod +x bin/report.php

php bin/report.php --user=php --limit=5
กำลังดึงข้อมูล php ...
name,stars,language,url
php-src,38000,C,https://github.com/php/php-src
web-php,2100,PHP,https://github.com/php/web-php
...
php bin/report.php --user=symfony --format=json --output=symfony.json
# เขียนรายงาน symfony.json (30 แถว)

php bin/report.php --user=doesnotexist12345
# ผิดพลาด: ไม่พบ user นี้บน GitHub    (exit code 1)
echo $?    # 1

ใส่ใน cron

# ทุกวันจันทร์ 7 โมงเช้า ออกรายงานเก็บไว้
0 7 * * 1  cd /home/user/gh-report && GITHUB_TOKEN=xxx php bin/report.php --user=myorg --output=/var/reports/repos-$(date +\%F).csv
  • แยก STDOUT (ผลลัพธ์/รายงาน) กับ STDERR (ข้อความสถานะ) — pipe ได้ถูก
  • exit code บอก cron ว่าสำเร็จไหม (MAILTO จะส่งเมลเมื่อ exit ≠ 0)

แนวทางเขียน CLI ที่ดี

  • argument ผ่าน getopt() ไม่แกะ $argv เอง
  • --help เสมอ และแสดงเมื่อ argument ผิด
  • STDOUT = ข้อมูล, STDERR = สถานะ/error — ให้ pipe/redirect ได้
  • exit code มีความหมาย — 0 ok, ไม่ใช่ 0 = ล้มเหลว (2 มักหมายถึง usage ผิด)
  • รันซ้ำได้ (idempotent) — เขียนไฟล์ใหม่ทับ ไม่ทิ้ง state ค้าง
  • timeout ทุก network call — cron ไม่ควรค้างข้ามวัน
  • secret ผ่าน env (GITHUB_TOKEN) ไม่ hardcode
  • set_time_limit(0) ถ้างานยาว (CLI ไม่มี limit โดยดีฟอลต์อยู่แล้ว แต่ระบุให้ชัด)

เรื่องที่คนมักพลาด

  • echo ข้อความสถานะปนกับผลลัพธ์ใน STDOUT — php report.php > out.csv ได้ไฟล์ที่มี “กำลังดึงข้อมูล…” ปน ใช้ STDERR สำหรับสถานะ
  • ไม่ตั้ง exit code — cron/CI คิดว่าสำเร็จเสมอ แม้จริง ๆ พัง
  • ไม่ตั้ง CURLOPT_TIMEOUT — API ค้าง → สคริปต์ค้าง → cron รอบถัดไปทับซ้อน
  • ลืม User-Agent header — GitHub API ตอบ 403 ถ้าไม่มี
  • parse $argv เอง ด้วย explode('=') — พังกับ --output=/path/with=sign ใช้ getopt()
  • ไม่เช็ค fopen() คืน false — เขียนไฟล์ที่ path ไม่มีสิทธิ์แล้ว error เงียบ
  • hardcode token ในโค้ด — หลุดขึ้น git ใช้ getenv()
  • สมมติว่า API คืนข้อมูลครบหน้าเดียว — GitHub แบ่งหน้า (per_page) ต้องวนจนครบ

สรุป

  • PHP CLI: bin/*.php ขึ้นต้น #!/usr/bin/env php, เช็ค PHP_SAPI === 'cli'
  • argument: getopt('', ['user:', 'format:', 'help']) — : = ต้องมีค่า
  • STDOUT = ผลลัพธ์, STDERR = สถานะ/error, exit code มีความหมาย (0/1/2)
  • cURL พร้อม timeout + User-Agent + จัดการ 403/404, วนหน้าจนครบ
  • เขียนผล: fputcsv (+ BOM สำหรับ Excel) หรือ json_encode(JSON_UNESCAPED_UNICODE|JSON_PRETTY_PRINT)
  • รันซ้ำได้, secret ผ่าน env, เหมาะกับ cron

จบซีรีส์ PHP — จากตัวแปรตัวแรกถึง REST API, ระบบสมาชิก, เว็บ MVC และเครื่องมือ CLI ทั้งหมดเป็น PHP 8 สมัยใหม่: มี type, ปลอดภัย, ทดสอบได้ ก้าวต่อไปคือหยิบเฟรมเวิร์กอย่าง Laravel หรือ Symfony ซึ่งตอนนี้คุณจะเข้าใจว่ามันทำอะไรให้เบื้องหลัง เพราะเราสร้างมันเวอร์ชันจิ๋วมาด้วยมือแล้วทุกชิ้น