【PHP8.x】CURLOPT_FTPLISTONLY定数の使い方

Copy
1<?php
2
3/**
4 * 指定されたURLへのHTTPリクエストを送信し、HTTPリダイレクト（3xxステータスコード）を自動で追跡します。
5 * システムエンジニアを目指す初心者向けに、PHP cURLエクステンションの基本的な使用法と
6 * CURLOPT_FOLLOWLOCATIONオプションの役割を簡潔に示します。
7 *
8 * @param string $url リクエストを送信するURL
9 * @return string|false リクエストの結果のコンテンツ、またはエラー時にfalse
10 */
11function fetchUrlWithFollowLocation(string $url): string|false
12{
13    // cURLセッションを初期化します。
14    $ch = curl_init();
15
16    // リクエスト対象のURLを設定します。
17    curl_setopt($ch, CURLOPT_URL, $url);
18
19    // HTTPリダイレクト（例: 301 Moved Permanently, 302 Found）があった場合に、
20    // cURLが自動的にLocationヘッダに指定された新しいURLにリクエストを追跡するよう設定します。
21    // PHP 8では、CURLOPT_FOLLOWLOCATIONのデフォルト値はfalseであるため、
22    // リダイレクトを追跡したい場合は明示的にtrueに設定する必要があります。
23    // このオプションはint型の定数CURLOPT_FOLLOWLOCATIONをtrue(1)に設定することで有効になります。
24    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
25
26    // cURLが取得したコンテンツを直接出力するのではなく、関数の戻り値として文字列で返すように設定します。
27    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
28
29    // 接続確立までの最大秒数を設定します。ネットワークの遅延時に役立ちます。
30    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
31
32    // cURL処理全体の最大実行秒数を設定します。
33    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
34
35    // cURLセッションを実行し、レスポンスを取得します。
36    $response = curl_exec($ch);
37
38    // エラーが発生したかどうかを確認します。
39    if (curl_errno($ch)) {
40        // エラーログに出力し、falseを返します。
41        error_log('cURL Error (' . curl_errno($ch) . '): ' . curl_error($ch));
42        $response = false;
43    }
44
45    // cURLセッションを閉じ、リソースを解放します。
46    curl_close($ch);
47
48    return $response;
49}
50
51// === 使用例 ===
52// リダイレクトをシミュレートするURLの例。
53// httpbin.orgはHTTPリクエスト＆レスポンスのテストに便利なサービスです。
54// この例では、まず /redirect-to にアクセスし、次に /get にリダイレクトされます。
55$exampleUrl = "http://httpbin.org/redirect-to?url=http://httpbin.org/get";
56
57echo "指定URL: " . $exampleUrl . PHP_EOL;
58echo "CURLOPT_FOLLOWLOCATION を有効にしてコンテンツを取得中..." . PHP_EOL;
59
60$content = fetchUrlWithFollowLocation($exampleUrl);
61
62if ($content !== false) {
63    echo "--- 取得成功 ---" . PHP_EOL;
64    // 取得したコンテンツの先頭200文字を表示します。
65    // mb_substrはマルチバイト文字を正しく扱います。
66    echo mb_substr($content, 0, 200, 'UTF-8') . (mb_strlen($content, 'UTF-8') > 200 ? '...' : '') . PHP_EOL;
67} else {
68    echo "--- 取得失敗 ---" . PHP_EOL;
69}

このPHPサンプルコードは、cURLエクステンションを使用して指定されたURLからコンテンツを取得し、特にHTTPリダイレクト（転送）を自動で追跡する方法を示しています。

CURLOPT_FOLLOWLOCATIONは、ウェブサーバーからのリダイレクト応答（HTTPステータスコード3xx）があった際に、cURLが自動的に新しいURLへリクエストを再送信し、最終的なコンテンツを取得するためのオプションです。PHP 8ではこのオプションのデフォルト値がfalseであるため、リダイレクトを追跡したい場合は明示的にtrue（整数値1）を設定する必要があります。これにより、元のURLが一時的に、または恒久的に別の場所へ移動していても、最終目的地のコンテンツにたどり着くことができます。

fetchUrlWithFollowLocation関数は、引数としてリクエストを送信する$url（文字列型）を受け取ります。関数内部ではcURLセッションを初期化し、CURLOPT_FOLLOWLOCATIONオプションをtrueに設定してリダイレクトを有効にしています。また、取得したコンテンツを直接出力する代わりに文字列として関数から返すため、CURLOPT_RETURNTRANSFERもtrueに設定しています。実行が成功すると、最終的に取得されたウェブページのコンテンツが文字列として戻り値となります。エラーが発生した場合はfalseが返され、エラーログに詳細が記録されます。この機能は、URLの変更が多い外部サービスからデータを取得する際に非常に役立ちます。

Copy
1<?php
2
3/**
4 * FTPサーバーからディレクトリのファイル名リストのみを取得し、ローカルファイルに保存します。
5 *
6 * この関数は、CURLOPT_FTPLISTONLY を使用してFTPディレクトリからファイル名のみのリストを取得し、
7 * CURLOPT_FILE を使用してその出力を指定されたローカルファイルに直接書き込む方法を示します。
8 *
9 * @param string $ftpUrl FTPディレクトリのURL (例: "ftp://ftp.example.com/pub/")
10 * @param string $outputFilePath リストを保存するローカルファイルのパス。
11 * @return bool 成功した場合は true、失敗した場合は false を返します。
12 */
13function getFtpFileListAndSave(string $ftpUrl, string $outputFilePath): bool
14{
15    // cURLセッションを初期化します。
16    $ch = curl_init();
17
18    if ($ch === false) {
19        echo "エラー: cURLセッションの初期化に失敗しました。\n";
20        return false;
21    }
22
23    // FTPリストを書き込むためのファイルを開きます。
24    $fileHandle = fopen($outputFilePath, 'w');
25    if ($fileHandle === false) {
26        echo "エラー: 出力ファイルを開けませんでした: " . $outputFilePath . "\n";
27        curl_close($ch);
28        return false;
29    }
30
31    // cURLオプションを設定します。
32    curl_setopt($ch, CURLOPT_URL, $ftpUrl);
33    // CURLOPT_FTPLISTONLY を使用して、詳細なリストではなくファイル名のみを取得します。
34    // このオプションに true を設定すると、FTPサーバはディレクトリ内のファイル名のみを返します。
35    curl_setopt($ch, CURLOPT_FTPLISTONLY, true);
36    // CURLOPT_FILE を使用して、cURLの出力を標準出力ではなく、指定したファイルハンドルに直接書き込みます。
37    curl_setopt($ch, CURLOPT_FILE, $fileHandle);
38    // オプション: 接続と操作のタイムアウトを設定します。
39    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10); // 接続試行の最大秒数
40    curl_setopt($ch, CURLOPT_TIMEOUT, 30);       // 全操作の最大秒数
41
42    // cURLセッションを実行します。
43    $success = curl_exec($ch);
44
45    // cURLエラーを確認します。
46    if ($success === false) {
47        echo "cURLエラー: " . curl_error($ch) . "\n";
48    }
49
50    // ファイルハンドルを閉じます。
51    fclose($fileHandle);
52
53    // cURLセッションを閉じます。
54    curl_close($ch);
55
56    if ($success) {
57        echo "FTPリストが正常に " . $outputFilePath . " に保存されました。\n";
58    } else {
59        echo "FTPリストの取得に失敗しました。\n";
60    }
61
62    return (bool) $success;
63}
64
65// --- 使用例 ---
66// 重要: 動作確認のためには、"ftp://ftp.example.com/path/to/directory/" を実際にアクセス可能な
67// FTPディレクトリのURLに置き換えてください。
68// この例では、設定しないと失敗する可能性のあるプレースホルダーを使用します。
69$ftpDirectoryUrl = "ftp://ftp.example.com/path/to/directory/"; // プレースホルダーURL
70$outputFileName = "ftp_listing.txt"; // リストを保存するファイル名
71
72echo "FTPディレクトリ (" . $ftpDirectoryUrl . ") からファイルリストを取得し、" . $outputFileName . " に保存しようとしています。\n";
73
74if (getFtpFileListAndSave($ftpDirectoryUrl, $outputFileName)) {
75    echo "操作は正常に完了しました。\n";
76    // 成功した場合、作成されたファイルの内容を表示できます（オプション）。
77    // echo "\n" . $outputFileName . " の内容:\n";
78    // echo file_get_contents($outputFileName);
79} else {
80    echo "操作は失敗しました。\n";
81}
82
83?>

このPHPコードは、FTPサーバー上の特定のディレクトリからファイル名の一覧だけを取得し、その結果をローカルファイルに直接保存する関数getFtpFileListAndSaveを示しています。

CURLOPT_FTPLISTONLYオプションをtrueに設定することで、FTPサーバーはディレクトリの詳細情報ではなく、ファイル名のみを返します。これにより、必要な情報だけを効率的に取得できます。また、CURLOPT_FILEオプションには、fopen関数で開いたローカルファイルのハンドルを設定します。これにより、cURLが取得したファイル名リストの出力を、プログラムの標準出力ではなく、指定されたファイルに直接書き込むことが可能となり、メモリ消費を抑えつつ高速に処理できます。

getFtpFileListAndSave関数は、取得元のFTPディレクトリのURLを$ftpUrl引数で、リストを保存するローカルファイルのパスを$outputFilePath引数で受け取ります。処理が成功した場合はtrueを、cURLセッションの初期化失敗、ファイルオープンエラー、FTP通信エラーなどが発生した場合はfalseを戻り値として返します。このサンプルは、cURLを使ったFTP操作における効率的なデータ取得とファイル保存の基本的なパターンを提供します。