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สำเร็จ,1error ทั่วไป,2argument ผิด
โครงสร้าง
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 มีความหมาย —
0ok, ไม่ใช่ 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-Agentheader — 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 ซึ่งตอนนี้คุณจะเข้าใจว่ามันทำอะไรให้เบื้องหลัง เพราะเราสร้างมันเวอร์ชันจิ๋วมาด้วยมือแล้วทุกชิ้น