【PHP8.x】curl_share_errno()関数の使い方

Copy
1<?php
2
3/**
4 * curl_share_errno関数の使用例。
5 *
6 * この関数は、共有CURLハンドルで発生した最後のエラーコードを取得する方法を示します。
7 * curl_share_errnoは主にcurl_share_setopt()などの共有ハンドル関連操作で発生したエラーを報告し、
8 * 個々のCURL転送エラー（例: 接続失敗）は通常curl_errno()で取得されます。
9 */
10function getCurlShareErrorSample(): void
11{
12    // 共有CURLハンドルを初期化
13    $shareHandle = curl_share_init();
14
15    if ($shareHandle === false) {
16        echo "CURL共有ハンドルの初期化に失敗しました。\n";
17        return;
18    }
19
20    // 共有ハンドルにクッキー共有オプションを設定
21    // ここでエラーが発生する可能性は低いですが、エラーチェックのプロセスを示します。
22    // curl_share_setoptは成功時にtrue、失敗時にfalseを返します。
23    $setoptResult = curl_share_setopt($shareHandle, CURL_SHOPT_COOKIES, 1);
24
25    if ($setoptResult === false) {
26        echo "curl_share_setopt() の設定に失敗しました。\n";
27        // 共有ハンドルのエラーコードを取得
28        $errorCode = curl_share_errno($shareHandle);
29        // curl_share_strerrorでエラーコードに対応する文字列メッセージを取得
30        echo "共有ハンドルエラーコード: " . $errorCode . " (" . curl_share_strerror($errorCode) . ")\n";
31        curl_share_close($shareHandle);
32        return;
33    }
34
35    // 設定後の共有ハンドルのエラーコードをチェック
36    // エラーがなければ CURLE_OK (通常0) を返します。
37    $shareErrorCode = curl_share_errno($shareHandle);
38    if ($shareErrorCode !== CURLE_OK) {
39        echo "共有ハンドルでエラーが検出されました (コード: " . $shareErrorCode . ")\n";
40        echo "メッセージ: " . curl_share_strerror($shareErrorCode) . "\n";
41    } else {
42        echo "共有ハンドルにはエラーがありません (コード: " . $shareErrorCode . ").\n";
43    }
44
45    // 共有ハンドルを利用する通常のCURLハンドルを初期化
46    $ch = curl_init();
47    if ($ch === false) {
48        echo "CURLハンドルの初期化に失敗しました。\n";
49        curl_share_close($shareHandle);
50        return;
51    }
52
53    // リクエスト設定
54    curl_setopt($ch, CURLOPT_URL, "http://example.com");
55    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
56    curl_setopt($ch, CURLOPT_SHARE, $shareHandle); // 共有ハンドルをCURLハンドルに設定
57
58    echo "CURLリクエストを実行中...\n";
59    $response = curl_exec($ch);
60
61    if ($response === false) {
62        // 個々のCURL転送エラーはcurl_errno()で取得
63        echo "CURL転送エラーが発生しました: " . curl_error($ch) . " (コード: " . curl_errno($ch) . ")\n";
64    } else {
65        echo "CURLリクエストが成功しました。\n";
66    }
67
68    // リクエスト実行後の共有ハンドルのエラーコードを再度チェック
69    // 転送中に共有データ関連のエラーが発生した場合、ここに反映される可能性がありますが、
70    // 多くの場合、個々のCURLハンドルのエラー（curl_errno()）に集約されます。
71    $shareErrorCodeAfterExec = curl_share_errno($shareHandle);
72    if ($shareErrorCodeAfterExec !== CURLE_OK) {
73        echo "リクエスト実行後に共有ハンドルでエラーが検出されました (コード: " . $shareErrorCodeAfterExec . ")\n";
74        echo "メッセージ: " . curl_share_strerror($shareErrorCodeAfterExec) . "\n";
75    } else {
76        echo "リクエスト実行後も共有ハンドルにはエラーがありません (コード: " . $shareErrorCodeAfterExec . ").\n";
77    }
78
79    // ハンドルを閉じる
80    curl_close($ch);
81    curl_share_close($shareHandle);
82}
83
84// サンプル関数の実行
85getCurlShareErrorSample();

curl_share_errno関数は、PHPでCURLリクエストを行う際に、複数のCURLリクエスト間でクッキーなどのリソースを共有するための「共有CURLハンドル」に発生した、最後のエラーコードを取得するために使用されます。引数にはエラーコードを確認したいCurlShareHandle型の共有ハンドルを指定します。この関数は、エラーコードを表す整数値を戻り値として返します。エラーがない場合は、通常CURLE_OK（0）が返されます。

この関数は主に、curl_share_init()で共有ハンドルを作成した後、curl_share_setopt()などの共有ハンドル自体への操作が失敗した場合のエラーを検出する際に役立ちます。例えば、サンプルコードでは共有ハンドルを初期化し、その後クッキー共有オプションを設定しています。もしこの設定処理が失敗した場合、curl_share_errno()を呼び出すことで、そのエラーコードを特定できます。取得したエラーコードは、curl_share_strerror()関数と組み合わせることで、人間が理解しやすいエラーメッセージとして表示することが可能です。

重要な点として、curl_share_errno()は、個々のCURLリクエスト（curl_init()で作成されたハンドル）の実行中に発生する、ネットワーク接続の失敗やURLが見つからないといった転送に関するエラーを直接報告するものではありません。そのような転送エラーは、別途curl_errno()関数を使用して個別に取得します。curl_share_errno()は、共有リソースの管理に関する問題の特定に特化しており、共有設定における予期せぬ挙動の原因究明に役立ちます。

Copy
1<?php
2
3/**
4 * 共有cURLハンドルにおけるエラーコードの取得方法を示すサンプルコード。
5 * curl_share_errno関数は、CurlShareHandleに紐づく最後のエラーコードを返します。
6 * 通常、共有ハンドルの初期化やオプション設定が成功した場合、エラーコードはCURLSHE_OK (0) となります。
7 */
8function demonstrateCurlShareErrno(): void
9{
10    echo "--- curl_share_errno 関数のデモンストレーション ---\n";
11
12    // 1. 共有 cURL ハンドルを初期化します。
13    // このハンドルは、複数の cURL リクエスト間でクッキーや DNS キャッシュなどの情報を共有するために使用されます。
14    $shareHandle = curl_share_init();
15
16    // ハンドルの初期化に失敗した場合は、エラーメッセージを出力して終了します。
17    if (!$shareHandle) {
18        echo "エラー: 共有 cURL ハンドルの初期化に失敗しました。\n";
19        exit(1);
20    }
21
22    echo "共有 cURL ハンドルを正常に初期化しました。\n";
23
24    // 2. 共有ハンドルにオプションを設定します。
25    // ここでは、DNSキャッシュを共有するように設定する例です。
26    // curl_share_setopt は成功すると true を、失敗すると false を返します。
27    if (!curl_share_setopt($shareHandle, CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS)) {
28        // オプション設定に失敗した場合、curl_share_errno でエラーコードを取得できる可能性があります。
29        // ただし、PHPレベルでの引数バリデーションエラーの場合は、libcurlのエラーとはならず、
30        // curl_share_errno が 0 (CURLSHE_OK) を返すこともあります。
31        $errorCode = curl_share_errno($shareHandle);
32        echo "警告: DNSキャッシュ共有オプションの設定に失敗しました。エラーコード: " . $errorCode . "\n";
33        if ($errorCode !== CURLSHE_OK) {
34            // curl_share_strerror はエラーコードに対応する文字列メッセージを返します。
35            echo "詳細エラーメッセージ: " . curl_share_strerror($errorCode) . "\n";
36        }
37        // ここでは処理を続行しますが、実際のアプリケーションではより適切なエラーハンドリングが必要です。
38    } else {
39        echo "DNSキャッシュ共有オプションを正常に設定しました。\n";
40    }
41
42    // 3. 共有ハンドルの現在のエラーコードを取得します。
43    // エラーがなければ CURLSHE_OK (0) が返されます。
44    // CURLSHE_OK は libcurl の共有ハンドルの成功コード定数です。
45    $currentErrorCode = curl_share_errno($shareHandle);
46
47    echo "\n共有ハンドルで現在検出されたエラーコード: " . $currentErrorCode . "\n";
48
49    if ($currentErrorCode !== CURLSHE_OK) {
50        echo "共有ハンドルでエラーが検出されました。エラーコード: " . $currentErrorCode . "\n";
51        echo "エラーメッセージ: " . curl_share_strerror($currentErrorCode) . "\n";
52    } else {
53        echo "現在の共有ハンドルにはエラーがありません (CURLSHE_OK: 0)。\n";
54    }
55
56    // 4. 共有 cURL ハンドルを閉じ、関連するリソースを解放します。
57    curl_share_close($shareHandle);
58    echo "共有 cURL ハンドルを閉じました。\n";
59
60    echo "--- デモンストレーション終了 ---\n";
61}
62
63// 関数を実行します。
64demonstrateCurlShareErrno();

curl_share_errno関数は、PHP 8で提供される、共有cURLハンドルに発生した最後のエラーコードを取得するための関数です。

この関数は引数としてCurlShareHandle型の共有cURLハンドルを受け取ります。このハンドルはcurl_share_init関数で作成され、複数のcURLリクエスト間でクッキーやDNSキャッシュなどの情報を共有するために利用される特別なオブジェクトです。

戻り値は整数型（int）で、指定された共有ハンドルに紐づくエラーコードが返されます。通常、共有ハンドルの初期化やオプション設定が成功した場合、戻り値はCURLSHE_OKという定数（値は0）となり、エラーがないことを示します。

もし共有ハンドルのオプション設定などで問題が発生した場合、この関数を呼び出すことで、その問題を示す具体的なエラーコード（0以外の整数）を取得できます。例えば、curl_share_setoptで不適切なオプションを設定しようとした際に、エラーの有無を確認する目的で使用されます。取得したエラーコードは、curl_share_strerror関数と組み合わせることで、エラーの内容を文字列で確認し、より詳細なデバッグやエラーハンドリングに役立てることが可能です。システム開発において、共有cURLハンドルを安全かつ確実に利用するためには、この関数を用いて適切なエラーハンドリングを行うことが重要となります。