laravel api handler
v0.7.3
Paket pembantu ini menyediakan fungsionalitas untuk mengurai URL permintaan REST-API.
Catatan: Versi ini untuk Laravel 5. Saat menggunakan Laravel 4 Anda perlu menggunakan versi 0.4.x.
Instal paket melalui composer dengan menjalankan
composer require marcelgwerder/laravel-api-handler
Setelah komposer selesai menambahkan penyedia layanan ke array providers di app/config/app.php :
MarcelgwerderApiHandlerApiHandlerServiceProvider::class,
Sekarang impor fasad ApiHandler ke kelas Anda:
use Marcelgwerder ApiHandler Facades ApiHandler ; Atau atur alias di app.php :
'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,
Itu saja!
Metode relasi sekarang memerlukan anotasi @Relation untuk membuktikan bahwa metode tersebut adalah metode relasi dan bukan metode lainnya (lihat edisi #11).
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Jika Anda meneruskan array sebagai parameter kedua ke parseSingle , sekarang harus ada pasangan kolom/nilai. Ini memungkinkan kami melewati beberapa kondisi seperti:
ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 )); Untuk mengganti konfigurasi, buat file bernama apihandler.php di folder config aplikasi Anda.
Periksa file konfigurasi di sumber paket untuk melihat opsi apa yang tersedia.
Penguraian URL saat ini mendukung:
Ada dua jenis sumber daya api yang didukung, satu objek dan kumpulan objek.
Jika Anda menangani permintaan GET pada sumber daya yang mewakili satu objek seperti misalnya /api/books/1 , gunakan metode parseSingle .
parseSingle($queryBuilder, $identifikasi, [$queryParams]):
id atau kolom array/pasangan nilai ( array('isbn' => '1234') ) digunakan sebagai pengidentifikasi unik objek. ApiHandler :: parseSingle ( $ book , 1 ); Jika Anda menangani permintaan GET pada sumber daya yang mewakili beberapa objek seperti /api/books misalnya, gunakan metode parseMultiple .
parseMultiple($queryBuilder, $fullTextSearchColumns, [$queryParams]):
ApiHandler :: parseMultiple ( $ book , array ( ' title ' , ' isbn ' , ' description ' )); parseSingle dan parseMultiple mengembalikan objek Result dengan metode berikut tersedia:
getBuilder(): Mengembalikan $queryBuilder asli dengan semua fungsi yang diterapkan padanya.
getResult(): Mengembalikan objek hasil yang dikembalikan oleh fungsi get() atau first() Laravel.
getResultOrFail(): Mengembalikan objek hasil yang dikembalikan oleh fungsi get() Laravel jika Anda mengharapkan banyak objek atau firstOrFail() jika Anda mengharapkan satu objek.
getResponse($resultOrFail = false): Mengembalikan objek Response Laravel termasuk isi, header, dan kode status HTTP. Jika $resultOrFail benar, metode getResultOrFail() akan digunakan secara internal, bukan getResult() .
getHeaders(): Mengembalikan array header yang telah disiapkan.
getMetaProviders(): Mengembalikan array objek penyedia meta. Masing-masing objek ini menyediakan tipe meta data tertentu melalui metode get() -nya.
cleanup($cleanup): Jika benar, array yang dihasilkan akan dibersihkan dari relasi yang ditambahkan secara tidak sengaja. Relasi seperti itu dapat ditambahkan secara otomatis jika diakses sebagai properti di pengakses model. Default global untuk pembersihan dapat ditentukan menggunakan opsi konfigurasi cleanup_relations yang defaultnya adalah false .
ApiHandler :: parseSingle ( $ books , 42 )-> cleanup ( true )-> getResponse (); Setiap parameter kueri, kecuali fungsi yang telah ditentukan sebelumnya _fields , _with , _sort , _limit , _offset , _config dan _q , diinterpretasikan sebagai filter. Pastikan untuk menghapus parameter tambahan yang tidak dimaksudkan untuk pemfilteran sebelum meneruskannya ke parseMultiple .
/api/books?title=The Lord of the Rings
Semua filter digabungkan dengan operator AND .
/api/books?title-lk=The Lord*&created_at-min=2014-03-14 12:55:02
Contoh di atas akan menghasilkan SQL berikut di mana:
WHERE ` title ` LIKE " The Lord% " AND ` created_at ` >= " 2014-03-14 12:55:02 " Dimungkinkan juga untuk menggunakan beberapa nilai untuk satu filter. Beberapa nilai dipisahkan oleh pipa | . Beberapa nilai digabungkan dengan OR kecuali jika ada akhiran -not , maka nilai tersebut digabungkan dengan AND . Misal semua buku dengan id 5 atau 6:
/api/books?id=5|6
Atau semua buku kecuali yang berid 5 atau 6:
/api/books?id-not=5|6
Hal yang sama dapat dicapai dengan menggunakan akhiran -in :
/api/books?id-in=5,6
Masing-masing akhiran not-in :
/api/books?id-not-in=5,6
| Akhiran | Operator | Arti |
|---|---|---|
| -lk | MENYUKAI | Sama seperti operator SQL LIKE |
| -bukan-lk | TIDAK SEPERTI | Sama seperti operator SQL NOT LIKE |
| -di dalam | DI DALAM | Sama seperti operator SQL IN |
| -tidak masuk | TIDAK MASUK | Sama seperti operator SQL NOT IN |
| -min | >= | Lebih besar dari atau sama dengan |
| -maks | <= | Lebih kecil dari atau sama dengan |
| -st | < | Lebih kecil dari |
| -gt | > | Lebih besar dari |
| -bukan | != | Tidak sama dengan |
Dua cara pengurutan, naik dan turun. Setiap kolom yang harus diurutkan secara descending selalu diawali dengan - .
/api/books?_sort=-title,created_at
Dua implementasi pencarian teks lengkap didukung. Anda dapat memilih mana yang akan digunakan dengan mengubah opsi fulltext di file konfigurasi menjadi default atau native .
Catatan: Saat menggunakan parameter _q kosong, pencarian akan selalu memberikan hasil kosong.
Penerapan kustom terbatas (default)
Teks tertentu dibagi menjadi kata kunci yang kemudian dicari di database. Setiap kali salah satu kata kunci ada, baris terkait disertakan dalam kumpulan hasil.
/api/books?_q=The Lord of the Rings
Contoh di atas mengembalikan setiap baris yang berisi salah satu kata kunci The , Lord , of , the , Rings di salah satu kolomnya. Kolom yang perlu dipertimbangkan dalam penelusuran teks lengkap diteruskan ke parseMultiple .
Implementasi MySQL asli
Jika versi MySQL Anda mendukung pencarian teks lengkap untuk mesin yang Anda gunakan, Anda dapat menggunakan pencarian lanjutan ini di api handler.
Ubah saja opsi konfigurasi fulltext menjadi native dan pastikan ada indeks teks lengkap yang tepat pada kolom yang Anda teruskan ke parseMultiple .
Setiap hasil juga akan berisi kolom _score yang memungkinkan Anda mengurutkan hasil berdasarkan seberapa cocoknya dengan istilah pencarian. Misalnya
/api/books?_q=The Lord of the Rings&_sort=-_score
Anda dapat menyesuaikan nama kolom ini dengan mengubah pengaturan fulltext_score_column di file konfigurasi.
Untuk menentukan jumlah maksimum kumpulan data pada hasil, gunakan _limit .
/api/books?_limit=50
Untuk menentukan offset kumpulan data pada hasil, gunakan _offset .
/api/books?_offset=20&_limit=50
Ketahuilah bahwa untuk menggunakan offset Anda juga harus selalu menentukan limit . MySQL memunculkan kesalahan untuk definisi offset tanpa batas.
Pengendali api juga mendukung hubungan Eloquent. Jadi jika Anda ingin mendapatkan semua buku beserta penulisnya, tambahkan saja penulisnya ke parameter _with .
/api/books?_with=author
Hubungan, juga bisa disarangkan:
/api/books?_with=author.awards
Agar ini berfungsi, Anda harus menambahkan anotasi @Relation ke setiap metode relasi Anda seperti:
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Hal ini diperlukan demi alasan keamanan, sehingga hanya metode relasi nyata yang dapat dipanggil dengan menggunakan _with .
Catatan: Setiap kali Anda membatasi bidang dengan _fields yang dikombinasikan dengan _with . Di bawah tenda, bidang diperluas dengan kunci utama/asing dari relasi. Eloquent membutuhkan kunci penghubung untuk mendapatkan model terkait.
Dimungkinkan untuk menambahkan informasi tambahan ke respons. Saat ini ada dua jenis penghitungan yang dapat ditambahkan ke header respons.
total-count yang mewakili jumlah semua elemen sumber daya atau lebih spesifiknya, jumlah instance pembuat kueri yang awalnya diteruskan. filter-count yang juga memperhitungkan filter. Misalnya, mereka berguna untuk mengimplementasikan penomoran halaman.
/api/books?id-gt=5&_config=meta-total-count,meta-filter-count
Semua bidang meta disediakan di header respons secara default. Header khusus berikut digunakan:
| Konfigurasi | Tajuk |
|---|---|
| meta-total-count | Meta-Total-Jumlah |
| hitungan meta-filter | Meta-Filter-Hitungan |
Secara default, meta data disertakan dalam header respons. Jika Anda ingin menyatukan semuanya di badan respons, Anda dapat meminta apa yang disebut "amplop" dengan menyertakan response-envelope di parameter _config atau dengan mengganti config.php default paket.
Amplop memiliki struktur sebagai berikut:
{
"meta" : {
},
"data" : [
]
}
