SoapClient::__construct

(PHP 5, PHP 7, PHP 8)

SoapClient::__construct — SoapClient のコンストラクタ

説明

public SoapClient::__construct(?string $wsdl, array $options = [])

SOAP サービスに接続するための SoapClient オブジェクトを生成します。

パラメータ

wsdl

サービスを記述した WSDL ファイルまたは URI。これは自動的にクライアントを設定します。指定されない場合、クライアントは非WSDL モードで動作します。

注意:
デフォルトでは、 WSDL ファイルはパフォーマンスのためキャッシュされます。このキャッシュ機能を無効にしたり、設定を変更する場合は、 SOAP 設定オプションや cache_wsdl オプションを参照ください。

options

SOAP クライアントに指定する追加オプションを連想配列で指定します。 wsdl が指定された場合、このパラメータはオプションです。指定されない場合、 location とurl オプションを指定する必要があります。

location string

リクエストを送信する SOAP サーバーのURL

wsdl パラメータが指定されない場合、必須です。 wsdl と location が指定された場合、 location オプションは WSDL ファイルで指定されたあらゆる location を上書きします。

uri string

SOAP サービスのターゲット名前空間です。

wsdl が指定されていない場合、このパラメータは必須です。そうでない場合、この値は無視されます。

style int

SOAP_RPC と SOAP_DOCUMENT を使うと、このクライアントで使うバインディングスタイルを指定します。 SOAP_RPC は RPCスタイルのバインディングを指定します。この場合の SOAP リクエストのボディには、関数コールの標準エンコーディングが含まれます。 SOAP_DOCUMENT はドキュメントスタイルのバインディングを指定します。この場合の SOAP リクエストのボディには、サービス定義を記した XML ドキュメントが含まれます。

wsdl が指定された場合、このオプションは無視され、スタイルは WDSL ファイルから読み込まれます。

このオプションと wsdl パラメータを両方指定しなかった場合、 RPCスタイルを使います。

use int

SOAP_ENCODED や SOAP_LITERAL を使うと、このクライアントで使うエンコーディングスタイルを指定します。 SOAP_ENCODED は、 SOAP 仕様で定義された型を使い、エンコーディングを指定します。 SOAP_LITERAL は、サービスで定義されたスキームを使い、エンコーディングを指定します。

wsdl が指定された場合、このオプションは無視され、エンコーディングは WDSL ファイルから読み込まれます。

このオプションと wsdl パラメータを両方指定しなかった場合、 "encoded" スタイルを使います。

soap_version int

使用する SOAP プロトコルのバージョンを指定します: SOAP 1.1 の場合は SOAP_1_1 を指定します。 SOAP 1.2 の場合は SOAP_1_2 を指定します。

省略した場合は、SOAP 1.1 を使います。

authentication int

HTTP 認証をリクエスト時に使う際の、認証方法を指定します。 SOAP_AUTHENTICATION_BASIC と SOAP_AUTHENTICATION_DIGEST が指定できます。

省略された場合、かつ login オプションが指定されると Basic 認証を使います。

login string

Basic 認証と、Digest 認証で使うユーザー名を指定します。

password string

Basic 認証と、Digest 認証で使うパスワードを指定します。

HTTPS クライアント認証で使う passphrase と混同しないようにして下さい。

local_cert string

HTTPS 認証で使うクライアント証明書のパス。証明書ファイルは、証明書と秘密鍵が両方入った状態で、 PEMエンコードされている必要があります。

このファイルには、発行者のチェインも含めることができます。それらを含める場合、クライアント証明書の後に置く必要があります。

stream_context でも設定できます。この場合、秘密鍵のファイルは別に指定できます。

passphrase string

local_cert オプションで指定したクライアント証明書のためのパスフレーズ。

Basic 認証や Digest 認証で使う password と混同しないようにして下さい。

stream_context でも設定できます。

proxy_host string

HTTPリクエスト時に使う、プロキシサーバーとして用いるホスト名を指定します。

proxy_port オプションも指定する必要があります。

proxy_port int

proxy_host で指定したプロキシサーバーに接続する際に使うポート番号。

proxy_login string

proxy_host で指定したプロキシサーバーに接続する際に、 Basic 認証で用いるオプションのユーザー名

proxy_password string

proxy_host で指定したプロキシサーバーに接続する際に、 Basic 認証で用いるオプションのパスワード

compression int

SOAP リクエストとレスポンスの圧縮を有効にします。

この値は、3つの値をビット演算のOR で指定します: オプションの SOAP_COMPRESSION_ACCEPT は、"Accept-Encoding" ヘッダを指定します。 SOAP_COMPRESSION_GZIP や SOAP_COMPRESSION_DEFLATE は、使用する圧縮アルゴリズムと、リクエストで使う圧縮レベルを 1 から 9 の間の数値で指定します。たとえば、双方向の gzip 圧縮を最高の圧縮レベルで行う場合は、 SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9 を指定します。

encoding string

内部的な文字エンコーディングを指定します。リクエストはここで指定されたエンコーディングから、常に UTF-8 に変換して送られ、レスポンスはこのエンコーディングに変換されます。

trace bool

リクエストやレスポンスのキャプチャを行います。キャプチャした情報は SoapClient::__getLastRequest(), SoapClient::__getLastRequestHeaders(), SoapClient::__getLastResponse(), SoapClient::__getLastResponseHeaders(). を使ってアクセスできます。

省略した場合のデフォルト値は false です。

classmap array

WSDL 型を PHP クラスにマッピングするために使用可能です。このオプションには、キーとしてWSDL 型、値として PHP クラスの名前を持つ配列を指定する必要があります。型の名前は、要素の(タグ)名前と一致させる必要はないことに注意して下さい。

指定するクラス名は、常に名前空間で完全修飾されているべきですし、 \ で始まってはいけません。正しい名前は、 ::class を使えば生成できます。

クラスのインスタンスを生成する場合、コンストラクタはコールされず、個別のプロパティに対してマジックメソッド __set() と __get() がコールされる点にも注意して下さい。

typemap array

ユーザー定義のコールバック関数を使って、型マッピングを定義します。型マッピングは配列で定義され、キーは type_name (XML 要素型を指定した文字列)、 type_ns (名前空間URI を指定した文字列)、 from_xml (文字列を受け取り、オブジェクトを返す callable)、 to_xml (オブジェクトをひとつ受け取り、文字列を返す callable) です。

exceptions bool

エラーが起きた際に、 SoapFault をスローするかどうかを指定します。

デフォルトは true です。

connection_timeout int

SOAP サービスに接続する際のタイムアウト秒数を指定します。これを使用しても、レスポンスが遅いサービスのタイムアウトを定義することはできません。サービスのコールが完了するまでの待ち時間を制限するには、 default_socket_timeout が使えます。

cache_wsdl int

wsdl を指定した場合、かつ soap.wsdl_cache_enabled が有効になっている場合に、このオプションはキャッシュのタイプを指定します。 WSDL_CACHE_NONE, WSDL_CACHE_DISK, WSDL_CACHE_MEMORY, WSDL_CACHE_BOTH のいずれかが指定できます。

ふたつのタイプのキャッシュが利用できます。 WSDL を現在のプロセスのメモリにキャッシュするインメモリのキャッシュと、 WSDL をディスク上にキャッシュし、全てのプロセスと共有するディスクキャッシュがあります。ディスクキャッシュで使うディレクトリは soap.wsdl_cache_dir で指定できます。どちらのタイプのキャッシュでも、 soap.wsdl_cache_ttl で指定した寿命があります。インメモリキャッシュの場合、 soap.wsdl_cache_limit でキャッシュエントリの数の最大値も指定できます。

この値を指定しない場合、 soap.wsdl_cache オプションの値を使います。

user_agent string

リクエストをする際に User-Agent で使う値。

stream_context でも指定できます。

この値を指定しない場合、 "PHP-SOAP/" の後に、 PHP_VERSION の値を付けたものを使います。

stream_context resource

追加のオプションを設定できる stream context。これは stream_context_create() で生成できます。

このコンテキストには、 socket context options, SSL context options, HTTP context options が含まれます: content_type, header, max_redirects, protocol_version, user_agent が設定できます。

'header' コンテキストオプションで指定された場合、以下のHTTPヘッダは自動生成され、無視されることに注意して下さい: host, connection, user-agent, content-length, content-type, cookie, authorization, proxy-authorization

features int

以下の機能を有効にするための、ひとつ以上のビットマスク:

SOAP_SINGLE_ELEMENT_ARRAYS

レスポンスを配列にデコードする際には、特定の親要素の中で要素名が一度または複数回現れるかをデフォルトで自動検知します。一度しか現れない要素については、オブジェクトのプロパティを通じてコンテンツに直接アクセスできます。複数回現れる要素については、プロパティには配列が含まれ、マッチする要素の内容の配列が入ります。

SOAP_SINGLE_ELEMENT_ARRAYS が有効になった場合、一度しか現れない要素は要素数がひとつの配列になります。これは全ての要素と一貫性を保つためです。これは、レスポンスにスキーマを含んでいるWSDLを使っている場合にのみ意味があります。具体的には、以下の例を参照ください。

SOAP_USE_XSI_ARRAY_TYPE

use オプションを使ったり、 WSDL プロパティを encoded に設定した場合に、配列の型をスキーマ特有のそれにするのではなく、 SOAP-ENC:Array にします。

SOAP_WAIT_ONE_WAY_CALLS

WDSL が一方向のリクエストを指定していた場合であっても、レスポンスを待つ。

keep_alive bool

Connection: Keep-Alive ヘッダや Connection: close を送信するかどうかを boolean で指定します。

デフォルトは true です。

ssl_method string

セキュアな HTTP 接続で用いる、 SSL または TLS のバージョンを指定します。 SOAP_SSL_METHOD_SSLv2 や SOAP_SSL_METHOD_SSLv3 を指定すると、それぞれ SSL 2、 SSL 3 を強制的に使います。 SOAP_SSL_METHOD_SSLv23 を指定しても意味がありません。これは後方互換のためだけに存在しています。 PHP 7.2.0 以降では、 SOAP_SSL_METHOD_TLS を指定しても同様に意味がありません。これより前のバージョンでは、この定数を指定すると TLS 1.0 を強制的に使っていました。

SSL バージョン 2 と 3 はセキュアでないとみなされています。よってインストール済みの OpenSSL ライブラリではサポートされていない可能性があることに注意しましょう。

このオプションは PHP 8.1.0 以降では 推奨されません。個別の TLS のバージョンを指定できる、より柔軟性に富んだ代替があります。 stream_context オプションを 'crypto_method' コンテキストパラメータと一緒に使うようにして下さい。

<?php
// TLS 1.3 のみを使うよう指定
$context = stream_context_create([
    'ssl' => [
        'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_3_CLIENT
     ]
]);
$client = new SoapClient("some.wsdl", ['context' => $context]);

エラー / 例外

SoapClient::__construct() は、非 WSDL モードで location や uri オプションを指定しなかったときに E_ERROR エラーとなります。

wsdl URI が読み込めなかった場合に SoapFault をスローします。

例

例1 SoapClient::__construct() の例

<?php

$client = new SoapClient("some.wsdl");

$client = new SoapClient("some.wsdl", array('soap_version'   => SOAP_1_2));

$client = new SoapClient("some.wsdl", array('login'          => "some_name",
                                            'password'       => "some_password"));

$client = new SoapClient("some.wsdl", array('proxy_host'     => "localhost",
                                            'proxy_port'     => 8080));

$client = new SoapClient("some.wsdl", array('proxy_host'     => "localhost",
                                            'proxy_port'     => 8080,
                                            'proxy_login'    => "some_name",
                                            'proxy_password' => "some_password"));

$client = new SoapClient("some.wsdl", array('local_cert'     => "cert_key.pem"));

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
                                     'uri'      => "http://test-uri/"));

$client = new SoapClient(null, array('location' => "http://localhost/soap.php",
                                     'uri'      => "http://test-uri/",
                                     'style'    => SOAP_DOCUMENT,
                                     'use'      => SOAP_LITERAL));

$client = new SoapClient("some.wsdl",
  array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 9));

$client = new SoapClient("some.wsdl", array('encoding'=>'ISO-8859-1'));

class MyBook {
    public $title;
    public $author;
}

$client = new SoapClient("books.wsdl", array('classmap' => array('book' => "MyBook")));

$typemap = array(
    array("type_ns"  => "http://schemas.example.com",
         "type_name" => "book",
         "from_xml"  => "unserialize_book",
         "to_xml"    => "serialize_book")
);
$client = new SoapClient("books.wsdl", array('typemap' => $typemap));

?>

例2 SOAP_SINGLE_ELEMENT_ARRAYS の機能を使う

<?php
/* Assuming a response like this, and an appropriate WSDL:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns="urn:example">
    <SOAP-ENV:Body>
        <response>
            <collection>
                <item>Single</item>
            </collection>
            <collection>
                <item>First</item>
                <item>Second</item>
            </collection>
        </response>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
*/

echo "Default:\n";

$client = new TestSoapClient(__DIR__ . '/temp.wsdl');
$response = $client->exampleRequest();
var_dump( $response->collection[0]->item );
var_dump( $response->collection[1]->item );

echo "\nWith SOAP_SINGLE_ELEMENT_ARRAYS:\n";

$client = new TestSoapClient(__DIR__ . '/temp.wsdl', ['features' => SOAP_SINGLE_ELEMENT_ARRAYS]);
$response = $client->exampleRequest();
var_dump( $response->collection[0]->item );
var_dump( $response->collection[1]->item );

上の例の出力は以下となります。

Default:
string(6) "Single"
array(2) {
  [0] =>
  string(5) "First"
  [1] =>
  string(6) "Second"
}

With SOAP_SINGLE_ELEMENT_ARRAYS:
array(1) {
  [0] =>
  string(6) "Single"
}
array(2) {
  [0] =>
  string(5) "First"
  [1] =>
  string(6) "Second"
}