README

此包旨在提供一个简单的方式来与iTunes Store API进行交互，适用于Laravel >= 5.3应用程序。

此包可用于生产环境，但仍应被视为一个正在进行中的项目。发现了错误？有功能请求？请开启一个问题或更好的，发送一个PR！

安装

您可以通过composer安装此包

$ composer require atomescrochus/laravel-itunes-search-api

如果您正在使用Laravel >=5.5，该包将使用自动发现功能。对于更早的版本，您必须安装包的服务提供者和别名

// config/app.php
'providers' => [
    ...
    Atomescrochus\ItunesStore\ItunesSearchAPIProvider::class,
];

// no need to add aliases, the packages bind itselfs as "ItunesSearch"

如果您想更改默认值，您还必须发布配置文件

php artisan vendor:publish --provider="Atomescrochus\ItunesStore\ItunesSearchAPIProvider" --tag="config"

使用方法

// here is an example query to search iTunes Store's API

// Set cache duration as an integer (number of minutes), can be 0
ItunesSearch::setCacheDuration(120) // optional, default is set in config

// You can execute a basic search, and hope for the best
$results = ItunesSearch::query("poker face lady gaga"); // limited to 15 results by default

// You can also send an optional array of other parameters supported by the API, for example
$results = ItunesSearch::query("poker face lady gaga", ['country' => 'CA', 'limit' => 10]);

// You can also execute a lookup (https://affiliate.itunes.apple.com/resources/documentation/itunes-store-web-service-search-api/#lookup)
$results = ItunesSearch::lookup(902122445); // defaults to lookup by iTunes Store ID
$results = ItunesSearch::lookup(468749, 'amgArtistId') // you can do other type of lookups
$results = ItunesSearch::lookup("468749,909253", 'amgArtistId'); // you can also search for multiple ids like so

// And like the query() method, you can send an optional array of parameters
$results = ItunesSearch::lookup(909253, 'id', ['country' => 'CA', 'limit' => 10]); 

// If you ever find yourself that you want to check your local cache for a result, without actually
// polling the Search API (for example, in cache you already know you've been rate limited):
$results = ItunesSearch::cacheOnly()->query("poker face lady gaga");
// if you want to poll again after setting cacheOnly(), you need to reverse the behavior
$results = ItunesSearch::cacheOnly(false)->lookup(909253); 

// In case you only want to check if the query exists in the cache, without actually pulling the data:
$existInCache = ItunesSearch::inCache()->query("poker face lady gaga"); // returns boolean
$existInCache = ItunesSearch::inCache()->lookup(909253); // returns boolean

缓存和iTunes Store API的速率限制

目前，API的调用限制约为每分钟20次（可能有所变化）。

目前，唯一的了解您是否遇到了商店的速率限制的方法是我们遇到HTTP响应为403 Forbidden。没有方法知道何时过期，或您还有多少次调用，或任何有用的信息（是的，这很糟糕）。

为了帮助您管理速率限制，我们提供了一个名为rateLimited的参数到搜索返回的结果对象。如果设置为true，表示我们遇到了403，这意味着您已被速率限制。

当然，我们无法阻止您在速率限制的情况下继续调用API，所以如果您发现rateLimited被设置为true，您有责任稍作停顿。

关于速率限制的最后一件事：由于我们默认缓存结果，如果遇到403，我们将返回一个空的响应而不缓存结果，不考虑您可能设置的缓存设置。这样，如果您在正常的缓存时间内再次进行相同的调用，但不再被速率限制，您将不会收到空的结果。

结果

在上面的例子中，$results返回的是一个对象，包含：结果集合；结果计数值；一个布尔值，用于知道是否被速率限制；一个布尔值，用于知道结果是否来自缓存数据；一个布尔值，用于知道是否仅请求在缓存中搜索；原始响应数据；以及发送到API的未格式化查询。

变更日志

有关最近更改的更多信息，请参阅变更日志。

测试

即将推出。

贡献

请参阅CONTRIBUTING和CONDUCT以获取详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件发送至jp@atomescroch.us，而不是使用问题跟踪器。

鸣谢

• [Jean-Philippe Murray][link-author]
• [所有贡献者][link-contributors]

许可

MIT许可（MIT）。请参阅许可文件以获取更多信息。