PHP Server SDK バージョン2.2.0リリースのお知らせ

バージョン2.2.0のリリースを発表できることを嬉しく思う。 バージョン2.2.0をリリースしました。 PHPサーバーSDKをリリースしました。

これはSDKのマイナーリリースですが、近々リリース予定のバージョン3.0.0からの新機能が満載です。SDKが提供する既存の機能へのアクセスを維持したまま、新機能の多くをすぐに使い始めることができます。

初のアップグレードリリース

PHP SDK の内部の多くの部分をリファクタリングするために膨大な作業が行われましたが、 そのリファクタリングに伴い、SDK のパブリックメソッド API の多くがバージョン 3.0.0 で変更されることになりました。

私はまた、既存のコードベースで作業しなければならない苦痛も知っており、アップグレードの時間を見つけるのは難しいかもしれません。このリリースでは、後方互換性のない変更点をできるだけ多くバックポートしています。 レガシー SMS APIと Voice API.これらの新しい名前空間の詳細については、もう少しお待ちください。

バージョン3.0.0では、多くのAPIにおけるデータアクセス方法を含む、いくつかの機能も非推奨となります。

これらの非推奨事項はすべて、ソースコードに @deprecatedアノテーションで表示されますが、私たちはさらに一歩進んで、あなたが使っている非推奨をリアルタイムのログで確認できるようにしました。

これはオプトインなので、本番環境のログにたくさんのお知らせが表示される心配はありません。また、メソッドシグネチャの変更、新しいメソッドや使用するクラスへのポインタなどを表示するために有効にできる開発機能でもあります。Nexmoクライアントを作成する際に show_deprecationsオプションを有効にするだけです。

$creds = new \Nexmo\Client\Credentials\Basic(NEXMO_API_KEY, NEXMO_API_SECRET);
$client = new \Nexmo\Client($creds, [
    'show_deprecations' => true
]);

これを有効にすると、アプリケーションをローカルで実行し、どのような非推 奨の通知が表示されるかを確認することができる！アクセスするAPIによっては、多くの非推奨事項が表示されるかもしれませんが、すべての非推奨事項の通知は、適切な修正を指し示すはずです。すべての非推奨のお知らせが解消されれば、バージョン3.0.0との完全な互換性が保たれ、シームレスなアップグレードが可能になるはずです！

非推奨事項のより完全なリストは、実際の リリースノートにある実際のリリースノートを参照してほしい：

• など、すべてのサービスレイヤーで配列アクセスは非推奨となっている。 messages(), voice(), applications()など。これらはすべて、実際の検索メソッドに置き換えられます。

• のように、検索フィルターをサービス・レイヤーに渡すことは非推奨です。 applications()のようにサービスレイヤーに検索フィルターを渡すことは非推奨です。各レイヤー専用の検索/取得関数を使用してください。

• ほとんどのエンティティはもはや配列にアクセスできないので、ゲッターメソッドを使うように変更すべきである。

• 型安全のため、ほとんどのメソッドで生の PHP 配列を使えなくなりました。非推奨の通知には、使用すべき適切なオブジェクトが示されています。

• その conversation()および user()サービス・レイヤーは非推奨であり、v3.0.0で完全に削除される予定です。

• 古い音声合成Voiceレイヤーは廃止され、v3.0.0で完全に削除される予定です。

• SMS検索は非推奨であり、v3.0.0で完全に削除される予定です。

より良いデバッグ・ツール

新機能のひとつ、API上で発生するリクエストとレスポンスの可視性が向上したことだ。

現在のSDKは、2.2.0であっても、リクエストとレスポンスへのアクセスをある程度提供しているが、どのエンティティがアクセス権を持っているかを知るのは難しい。

すべてのAPI（ただし messages()と calls()を除く)は現在、最後に作成されたリクエストとレスポンスを追跡するAPIハンドラが組み込まれている。このAPIハンドラは、どのサービスレイヤーの名前空間からでも getApiResource()で問い合わせることができます。 PSR-7 互換のリクエストやレスポンス.

$response = $client->sms()->send(
    new \Nexmo\SMS\Message\SMS(TO_NUMBER, NEXMO_NUMBER, 'A text message sent using the Nexmo SMS API')
);

$lastRequest = $client->sms()->getApiResource()->getLastRequest();
$lastResponse = $client->sms()->getApiResource()->getLastResponse();

エンティティや例外からのリクエストとレスポンスの取得は非推奨とし、サービス名前空間からの取得を推奨します。唯一の例外は、サービスレイヤーの新しい検索メソッドで、レイジーローディングコレクションを返すものがあります。この場合、コレクションのAPIハンドラがリクエストとレスポンスを持っている。

// Returns a lazy-loaded iterable object
$applications = $client->applications()->getAll();
assert($applications instanceof \Nexmo\Entity\IterableAPICollection);

// Start iterating, which fires off an HTTP request
$application = $applications->current();

// Get the request/response
$lastRequest = $applications->getApiResource()->getLastRequest();
$lastResponse = $applications->getApiResource()->getLastResponse();

一部のAPIはv2.2.0でも配列を返すので、メソッドのシグネチャを確認するか、不明な場合は instanceofを使用してください。バージョン3.0.0では、ほとんどすべての検索結果のインターフェースが新しくなります。

新しいSMSレイヤー

多くのお客様がレガシーのSMS機能をご利用いただいています。私たちは メッセージAPIのような新しいAPIを開発し、より多くのメッセージング機能を提供していますが、SMSのお客様を置き去りにしたいわけではありません。

そのため、SMSレイヤー全体が、厳密な型付けと完全なオブジェクト指向インターフェイスを含むように刷新された。これにより、生のPHP配列を作成することによるエラーを削減し、メッセージで利用可能な機能をより明確に把握できるようになります。また、開発者が私たちのSDKに期待するようなシンプルなインターフェイスを維持するよう努めました。

// The old messages namespace
$message = $client->message()->send([
    'to' => TO_NUMBER,
    'from' => NEXMO_NUMBER,
    'text' => 'A text message sent using the Nexmo SMS API'
]);

// The new way
$response = $client->sms()->send(
    new \Nexmo\SMS\Message\SMS(TO_NUMBER, NEXMO_NUMBER, 'A text message sent using the Nexmo SMS API')
);

古い messages()Nexmo クライアントの古い名前空間はバージョン 2.2.0 で完全に廃止され、新しい sms()名前空間を使用できます。これらは並行して使用することができるので、レガシーコードは古い名前空間を使い続けることができ、新しいコードは新しい sms()名前空間を使うことができます。

また、受信ウェブフックのインターフェースも拡張した。以前と同じように、送られてきたリクエストを解析することができます。 \Nexmo\SMS\Webhook\InboundSMSオブジェクトを返します。これにより、クエリパラメータや生のJSONポストボディ、あるいは配列を扱う場合と比較して、受信データを取得する方法がより明確になるはずです。

$inboundSMS = \Nexmo\SMS\Webhook\Factory::createFromGlobals();
echo $inboundSMS->getFrom() . PHP_EOL;
echo $inboundSMS->getTo() . PHP_EOL;
echo $inboundSMS->getText() . PHP_EOL;

新しいVoiceレイヤー

Voice APIもまた、私たちが最も多用しているAPIのひとつであり、インターフェイスをできる限りすっきりさせたかった分野でもあります。

きれいにカットするために calls()名前空間は完全に非推奨となり、その代わりに voice()名前空間を使ったまったく新しいインターフェイスに変更されました。

アイディアは新しいSMSレイヤーの時と同じで、Voice APIが提供する全てのパワーを保持しつつ、一般的なタスクを簡単にこなせるような新しくクリーンなインターフェイスを提供し、モダンなPHPプラクティスでこれを開発することでした。これらのインターフェイスのいくつかについては、他の記事でも書いたが、今回は荒削りな部分を削る絶好の機会だった。

// The old way
$call = $client->calls()->create([
    'to' => [[
        'type' => 'phone',
        'number' => TO_NUMBER
    ]],
    'from' => [
        'type' => 'phone',
        'number' => NEXMO_NUMBER
    ],
    'ncco' => [
        [
            'action' => 'talk',
            'text' => 'This is a text to speech call from Nexmo'
        ]
    ]
]);

// The new way
$outboundCall = new \Nexmo\Voice\OutboundCall(
    new \Nexmo\Voice\Endpoint\Phone(TO_NUMBER),
    new \Nexmo\Voice\Endpoint\Phone(NEXMO_NUMBER)
);
$ncco = new NCCO();
$ncco->addAction(new \Nexmo\Voice\NCCO\Action\Talk('This is a text to speech call from Nexmo'));
$outboundCall->setNCCO($ncco);

$response = $client->voice()->createOutboundCall($outboundCall);

新しい voice()レイヤーはすべてオブジェクト指向なので、NCCOや基本的な呼び出しのために配列構造を構築する方法を覚えておく必要はもうない。利用可能なオプションはすべて、新しい \Nexmo\Voice\OutboundCallオブジェクトのセッターメソッドとして公開される。 \Nexmo\Voice\OutboundCallオブジェクトは様々なエンドポイントをより良くサポートしている。

NCCOを扱うことは、私にとっていつも悩みの種だった。PHPでは配列をJSONに変換するのは簡単なのですが、NCCOのオプションをすべて覚えようとすると、大抵は（確かに素晴らしい）PHPの ドキュメント.

SDKにはNCCOビルダーが同梱されるようになったので、強く型付けされたオブジェクトでNCCOを構築することができ、着信NCCOリクエストや発信コールの一部として送信するNCCOのJSONを簡単に生成することができます。

$ncco = new \Nexmo\Voice\NCCO\NCCO();
$ncco
    ->addAction(
        new \Nexmo\Voice\NCCO\Action\Talk('Welcome to the amazing Nexmo conference call')
    )
    ->addAction(
        new \Nexmo\Voice\NCCO\Action\Conversation('amazing-conference-call')
    )
;

header('Content-Type: application/json');
$json = json_encode($ncco);
echo($json);

音声API Voice APIは Webhook コールバックに大きく依存しているため、このリリースではより完全な着信 Webhook パーサーも導入しています。このパーサーはSMSパーサーと同じインターフェースですが、Voice APIのライフサイクルに関連するオブジェクトを返します。

$inboundVAPI = \Nexmo\Voice\Webhook\Factory::createFromGlobals();
if ($inboundVAPI instanceof \Nexmo\Voice\Webhook\Event) {
    echo $inboundVAPI->getTo() . PHP_EOL;
    echo $inboundVAPI->getFrom() . PHP_EOL;
    echo $inboundVAPI->getStatus() . PHP_EOL;
    echo $inboundVAPI->getUuid() . PHP_EOL;  
}

if ($inboundVAPI instanceof \Nexmo\Voice\Webhook\Record) {
    echo $inboundVAPI->getRecordingUrl() . PHP_EOL;
}

// And other types can also be returned

アップデートの検証

最後に大幅なリファクタリングが行われた主要APIは Verify製品で verify()ネームスペースの下にある。このリファクタリングはSMSやVoiceほど大規模なものではありませんでしたが、注意すべき新機能がいくつかあります。

一つ目は、検証リクエストの作成方法が明確になったことである。これは現在 \Nexmo\Verify\Requestオブジェクトによって処理されるようになり、検証プロセスを開始するためのインターフェイスがすっきりしました。

このオブジェクトは強く型付けされており、より汎用的な \Nexmo\Verify\Verificationオブジェクトに比べ、検証リクエストに期待されるものをより適切に表現しています。後方互換性のために \Nexmo\Verify\Verificationが返されますが、v3.0.0では変更されます。

// The old way
$verification = new \Nexmo\Verify\Verification(NUMBER, BRAND_NAME);
$client->verify()->start($verification);

// The new way
$request = new \Nexmo\Verify\Request(NUMBER, BRAND_NAME);
$response = $client->verify()->start($request);

次のイベントのチェック、キャンセル、トリガーが簡単になった。オブジェクトをインスタンス化したり \Nexmo\Verify\Verificationオブジェクトをインスタンス化したり、シリアライズしてセッション経由で移動させたりする必要はもうありません。サービス層は verify()サービスレイヤーは、VerifyリクエストIDを直接受け取ることだけを処理するようになりました。

// The old way
$verification = new \Nexmo\Verify\Verification(REQUEST_ID);
$result = $client->verify()->check($verification, CODE);

// The new way
$result = $client->verify()->check(REQUEST_ID, CODE);

これは大きな変更ではないが、v3.0.0ではオブジェクトの代わりに文字列のリクエストIDしか受け付けないので、注意が必要である。

より簡単なアップグレードの約束

バージョン2.1.0と互換性のあるコードであれば、変更なしですぐに2.2.0と互換性があるはずです。このリリースは、可能な限り最新の状態に保ちながら、あなた自身の時間でアップグレードを行う機会を与えるだけです。

今後、PHP SDK はより正式な非推奨情報やアップグレードパスを提供し続け、 開発者ができるだけ早く変更に対応できるようにします。

また、バージョン3.0.0のリリースでお会いしましょう！