(PHP 5, PHP 7, PHP 8)
SoapClient::__construct — SoapClient のコンストラクタ
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 以降では、
SOAP_SSL_METHOD_TLS
を指定しても同様に意味がありません。
これより前のバージョンでは、
この定数を指定すると TLS 1.0 を強制的に使っていました。
SSL バージョン 2 と 3 はセキュアでないとみなされています。 よってインストール済みの OpenSSL ライブラリではサポートされていない可能性があることに注意しましょう。
このオプションは
PHP 8.1.0 以降では 推奨されません。
個別の TLS のバージョンを指定できる、
より柔軟性に富んだ代替があります。
stream_context
オプションを
'crypto_method'
コンテキストパラメータと一緒に使うようにして下さい。
例1 TLS 1.3 だけを指定する
<?php
$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 をスローします。
例2 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));
?>
例3 SOAP_SINGLE_ELEMENT_ARRAYS
の機能を使う
/* 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" }