laravel api handler
v0.7.3
このヘルパー パッケージは、REST-API リクエストの URL を解析する機能を提供します。
注:このバージョンは Laravel 5 用です。Laravel 4 を使用する場合は、バージョン 0.4.x を使用する必要があります。
次のコマンドを実行して、composer を介してパッケージをインストールします。
composer require marcelgwerder/laravel-api-handler
Composer が完了したら、サービス プロバイダーをapp/config/app.phpのproviders配列に追加します。
MarcelgwerderApiHandlerApiHandlerServiceProvider::class,
次に、 ApiHandlerファサードをクラスにインポートします。
use Marcelgwerder ApiHandler Facades ApiHandler ;または、 app.phpでエイリアスを設定します。
'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,
それでおしまい！
リレーション メソッドは、リレーション メソッドであり、他のメソッドではないことを証明するために@Relationアノテーションが必要になりました (問題 #11 を参照)。
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
}parseSingleの 2 番目のパラメーターとして配列を渡す場合は、列と値のペアが必要になります。これにより、次のような複数の条件を渡すことができます。
ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 ));構成をオーバーライドするには、アプリの config フォルダーにapihandler.phpというファイルを作成します。
パッケージ ソースの構成ファイルをチェックして、使用可能なオプションを確認してください。
URL 解析は現在以下をサポートしています。
単一オブジェクトとオブジェクトのコレクションという 2 種類の API リソースがサポートされています。
/api/books/1などの単一オブジェクトを表すリソースに対する GET リクエストを処理する場合は、 parseSingleメソッドを使用します。
parseSingle($queryBuilder, $identification, [$queryParams]):
id列で使用される整数、またはオブジェクトの一意の識別子として使用される配列の列と値のペア ( array('isbn' => '1234') )。 ApiHandler :: parseSingle ( $ book , 1 );/api/booksなどの複数のオブジェクトを表すリソースに対する GET リクエストを処理する場合は、 parseMultipleメソッドを使用します。
parseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams]):
ApiHandler :: parseMultiple ( $ book , array ( ' title ' , ' isbn ' , ' description ' ));parseSingleとparseMultipleどちらも、次のメソッドを使用できるResultオブジェクトを返します。
getBuilder():すべての関数が適用された元の$queryBuilder返します。
getResult(): Laravelのget()またはfirst()関数によって返された結果オブジェクトを返します。
getResultOrFail():複数のオブジェクトが期待される場合は Laravel のget()関数によって返された結果オブジェクトを返し、単一のオブジェクトが期待される場合はfirstOrFail()関数によって返されます。
getResponse($resultOrFail = false):本文、ヘッダー、HTTP ステータスコードを含む Laravel Responseオブジェクトを返します。 $resultOrFailが true の場合、 getResult()の代わりにgetResultOrFail()メソッドが内部的に使用されます。
getHeaders():準備されたヘッダーの配列を返します。
getMetaProviders():メタ プロバイダー オブジェクトの配列を返します。これらの各オブジェクトは、そのget()メソッドを通じて特定のタイプのメタデータを提供します。
cleanup($cleanup): true の場合、結果の配列は意図せず追加された関係からクリーンアップされます。このような関係は、モデル アクセサーのプロパティとしてアクセスされる場合、自動的に追加されます。クリーンアップのグローバルデフォルトは、構成オプションcleanup_relationsを使用して定義できます。デフォルトはfalseです。
ApiHandler :: parseSingle ( $ books , 42 )-> cleanup ( true )-> getResponse ();定義済み関数_fields 、 _with 、 _sort 、 _limit 、 _offset 、 _config 、 _qを除くすべてのクエリ パラメーターは、フィルターとして解釈されます。フィルタリングを目的としていない追加のパラメータは、 parseMultipleに渡す前に必ず削除してください。
/api/books?title=The Lord of the Rings
すべてのフィルターはAND演算子で結合されます。
/api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02
上記の例では、次の SQL が生成されます。
WHERE ` title ` LIKE " The Lord% " AND ` created_at ` >= " 2014-03-14 12:55:02 " 1 つのフィルターに複数の値を使用することもできます。複数の値はパイプ|で区切られます。 。複数の値はORで結合されますが、 -not接尾辞がある場合はANDで結合されます。たとえば、ID が 5 または 6 のすべての書籍:
/api/books?id=5|6
または、ID 5 または 6 の本を除くすべての本:
/api/books?id-not=5|6
-inサフィックスを使用しても同じことが実現できます。
/api/books?id-in=5,6
それぞれのnot-in接尾辞:
/api/books?id-not-in=5,6
| サフィックス | オペレーター | 意味 |
|---|---|---|
| -lk | のように | SQL LIKE演算子と同じ |
| -not-lk | 好きじゃない | SQL NOT LIKE演算子と同じ |
| -で | で | SQL IN演算子と同じ |
| -入っていない | 入っていない | SQL NOT IN演算子と同じ |
| -分 | >= | 以上 |
| -最大 | <= | 以下 |
| -st | < | より小さい |
| -gt | > | より大きい |
| -ない | != | 等しくありません |
昇順と降順の 2 つの並べ替え方法。降順でソートする必要があるすべての列は常に-で始まります。
/api/books?_sort=-title,created_at
全文検索の 2 つの実装がサポートされています。構成ファイルのfulltextオプションをdefaultまたはnativeいずれかに変更することで、どちらを使用するかを選択できます。
注:空の_qパラメータを使用すると、検索では常に空の結果が返されます。
限定的なカスタム実装 (デフォルト)
指定されたテキストはキーワードに分割され、データベース内で検索されます。いずれかのキーワードが存在する場合は、対応する行が結果セットに含まれます。
/api/books?_q=The Lord of the Rings
上記の例では、列の 1 つにキーワードThe 、 Lord 、 of 、 the 、 Ringsのいずれかを含むすべての行が返されます。全文検索で考慮される列はparseMultipleに渡されます。
ネイティブ MySQL 実装
MySQL バージョンが使用するエンジンの全文検索をサポートしている場合は、API ハンドラーでこの高度な検索を使用できます。
fulltext構成オプションをnativeに変更し、 parseMultipleに渡す列に適切なフルテキスト インデックスがあることを確認するだけです。
各結果には_score列も含まれており、検索語との一致度に応じて結果を並べ替えることができます。例えば
/api/books?_q=The Lord of the Rings&_sort=-_score
構成ファイルのfulltext_score_column設定を変更することで、この列の名前を調整できます。
結果内のデータセットの最大量を定義するには、 _limitを使用します。
/api/books?_limit=50
結果内のデータセットのオフセットを定義するには、 _offsetを使用します。
/api/books?_offset=20&_limit=50
offset使用するには、常にlimitも指定する必要があることに注意してください。 MySQL は、制限のないオフセット定義に対してエラーをスローします。
API ハンドラーは Eloquent リレーションシップもサポートします。したがって、すべての書籍とその著者を取得したい場合は、その著者を_withパラメータに追加するだけです。
/api/books?_with=author
関係はネストすることもできます。
/api/books?_with=author.awards
ただし、これを機能させるには、次のように@Relationアノテーションを各リレーション メソッドに追加する必要があります。
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
}これは、 _with使用して実際のリレーション メソッドのみを呼び出せるようにするため、セキュリティ上の理由から必要です。
注: _fieldsと_withを組み合わせてフィールドを制限する場合。内部では、フィールドはリレーションの主キー/外部キーを使用して拡張されます。 Eloquent では、関連モデルを取得するにはリンク キーが必要です。
応答に追加情報を追加することができます。現在、応答ヘッダーに追加できるカウントは 2 種類あります。
total-countは、リソースのすべての要素の数、より具体的には、最初に渡されたクエリ ビルダー インスタンスの数を表します。フィルタをさらに考慮するfilter-count 。たとえば、ページネーションを実装するのに役立ちます。
/api/books?id-gt=5&_config=meta-total-count,meta-filter-count
すべてのメタ フィールドは、デフォルトで応答ヘッダーに提供されます。次のカスタム ヘッダーが使用されます。
| 構成 | ヘッダ |
|---|---|
| メタ合計数 | メタ合計数 |
| メタフィルターカウント | メタフィルター数 |
デフォルトでは、メタデータは応答ヘッダーに含まれます。応答本文にすべてをまとめたい場合は、 _configパラメーターにresponse-envelopeを含めるか、パッケージのデフォルトのconfig.phpをオーバーライドすることで、いわゆる「エンベロープ」をリクエストできます。
エンベロープは次のような構造になっています。
{
"meta" : {
},
"data" : [
]
}
