laravel api handler
v0.7.3
Этот вспомогательный пакет предоставляет функции для анализа URL-адреса запроса REST-API.
Примечание. Эта версия предназначена для Laravel 5. При использовании Laravel 4 вам необходимо использовать версию 0.4.x.
Установите пакет через композитор, запустив
composer require marcelgwerder/laravel-api-handler
Как только композитор закончит, добавьте поставщика услуг в массив providers в app/config/app.php :
MarcelgwerderApiHandlerApiHandlerServiceProvider::class,
Теперь импортируйте фасад ApiHandler в свои классы:
use Marcelgwerder ApiHandler Facades ApiHandler ; Или установите псевдоним в app.php :
'ApiHandler' => MarcelgwerderApiHandlerFacadesApiHandler::class,
Вот и все!
Методам отношений теперь требуется аннотация @Relation чтобы доказать, что они являются методами отношений, а не какими-либо другими методами (см. проблему № 11).
/**
* @Relation
*/
public function author () {
return $ this -> belongsTo ( ' Author ' );
} Если вы передадите массив в качестве второго параметра в parseSingle , теперь должны быть пары столбец/значение. Это позволяет нам передавать несколько условий, таких как:
ApiHandler :: parseSingle ( $ books , array ( ' id_origin ' => ' Random Bookstore Ltd ' , ' id ' => 1337 )); Чтобы переопределить конфигурацию, создайте файл с именем apihandler.php в папке конфигурации вашего приложения.
Проверьте файл конфигурации в исходном коде пакета, чтобы узнать, какие параметры доступны.
Анализ URL-адресов в настоящее время поддерживает:
Поддерживаются два типа ресурсов API: один объект и коллекция объектов.
Если вы обрабатываете запрос GET к ресурсу, представляющему один объект, например /api/books/1 , используйте метод parseSingle .
parseSingle($queryBuilder, $identification, [$queryParams]):
id , или пары столбец/значение массива ( array('isbn' => '1234') ), используемое в качестве уникального идентификатора объекта. ApiHandler :: parseSingle ( $ book , 1 ); Если вы обрабатываете запрос GET к ресурсу, представляющему несколько объектов, например /api/books , используйте метод 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): возвращает объект Response Laravel, включая тело, заголовки и код состояния HTTP. Если $resultOrFail имеет значение true, метод getResultOrFail() будет использоваться внутри вместо getResult() .
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 " Также возможно использовать несколько значений для одного фильтра. Несколько значений разделяются вертикальной чертой | . Несколько значений объединяются с помощью OR за исключением случаев, когда имеется суффикс -not , тогда они объединяются с помощью AND . Например, все книги с идентификатором 5 или 6:
/api/books?id=5|6
Или все книги, кроме книг с идентификатором 5 или 6:
/api/books?id-not=5|6
Того же самого можно добиться, используя суффикс -in :
/api/books?id-in=5,6
Соответственно суффикс not-in :
/api/books?id-not-in=5,6
| Суффикс | Оператор | Значение |
|---|---|---|
| -лк | НРАВИТЬСЯ | То же, что и оператор SQL LIKE . |
| -не-лк | НЕ НРАВИТСЯ | То же, что и оператор SQL NOT LIKE . |
| -в | В | То же, что и оператор SQL IN |
| -не-в | НЕ В | То же, что и оператор SQL NOT IN . |
| -мин | >= | Больше или равно |
| -макс | <= | Меньше или равно |
| -ст | < | Меньше, чем |
| -gt | > | Больше, чем |
| -нет | != | Не равно |
Два способа сортировки: по возрастанию и по убыванию. Каждый столбец, который следует отсортировать по убыванию, всегда начинается с - .
/api/books?_sort=-title,created_at
Поддерживаются две реализации полнотекстового поиска. Вы можете выбрать, какой из них использовать, изменив fulltext параметр в файле конфигурации на default или native .
Примечание. При использовании пустого параметра _q поиск всегда будет возвращать пустой результат.
Ограниченная пользовательская реализация (по умолчанию)
Данный текст разбивается на ключевые слова, которые затем ищутся в базе данных. Всякий раз, когда одно из ключевых слов существует, соответствующая строка включается в набор результатов.
/api/books?_q=The Lord of the Rings
В приведенном выше примере возвращается каждая строка, содержащая одно из ключевых слов 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 нужны связывающие ключи для получения связанных моделей.
К ответу можно добавить дополнительную информацию. В настоящее время существует два типа счетчиков, которые можно добавлять в заголовки ответов.
total-count , который представляет собой количество всех элементов ресурса или, если быть более точным, количество первоначально переданного экземпляра построителя запросов. filter-count , которое дополнительно учитывает фильтры. Например, они могут быть полезны для реализации нумерации страниц.
/api/books?id-gt=5&_config=meta-total-count,meta-filter-count
Все метаполя по умолчанию предоставляются в заголовке ответа. Используются следующие пользовательские заголовки:
| Конфигурация | Заголовок |
|---|---|
| мета-общее количество | Мета-общее количество |
| количество мета-фильтров | Мета-фильтр-счетчик |
По умолчанию метаданные включаются в заголовок ответа. Если вы хотите собрать все вместе в теле ответа, вы можете запросить так называемый «конверт», либо включив response-envelope в параметр _config , либо переопределив стандартный config.php пакета.
Конверт имеет следующую структуру:
{
"meta" : {
},
"data" : [
]
}
