README

Flickering 是一个针对 Flickr 照片分享社交网络的下一代PHP API。这是一个正在进行中的项目，但它已经可以工作了，所以不用担心。

您可以在Composer上获取它，要这样做，只需运行 composer require anahkiasen/flickering。

之后，将ServiceProvider添加到app/config/app.php中的providers数组中

'Flickering\FlickeringServiceProvider',

如果您想使用外观，也将其添加到app.php中

 'Flickering' => 'Flickering\Facades\Flickering',

如果您想将API密钥/秘密存储在配置中，请发布配置文件。

$ php artisan config:publish anahkiasen/flickering

使用Flickering

创建新实例

要使用Flickering，您当然需要一个Flickr的API密钥，如果您还没有，您可以在 这里 获取一个，它们都很好，所以它们会免费给您一个。一旦您有了它，将其设置在Flickering的config/config.php文件中。或者，如果您不想/能，您始终可以通过构造函数传递您的凭据。

要开始使用Flickering，创建一个新实例，如下面的示例所示。如果您在配置文件中设置了API凭据，您不需要将任何参数传递给构造函数，因为它将自动从配置文件中获取您的密钥和密钥。

$flickering = App::make('flickering');
$flickering->handshake($apiKey, $apiSecret);

如果您不喜欢使用实例，Flickering还使用Illuminate的Facade组件来提供所有方法的静态接口。您可以创建一个新的Flickering静态实例，如下所示。如果设置了配置文件，则参数是可选的，与上面相同。

Flickering::handshake($apiKey, $apiSecret)
Flickering::handshake();    //Using the config file

在使用Flickr API之前，您必须调用一次握手。

在Flickr API上调用方法

Flickering提供了多种方式来调用API。它们在语法优雅度和对API响应的控制程度方面有所不同。

最基本（但也是最强大）的方法是简单地调用您的Flickering实例上的 ->callMethod

Flickering::callMethod('people.getPhotos', array('user_id' => '31667913@N06'));

或者，Flickering已经设置了一组智能别名，用于常见方法，因此，对于上面示例中的完全相同的事情，您也可以这样做。

Flickering::peopleGetPhotos('31667913@N06')

请注意，每个智能别名的参数都映射到由Flickr API提供的参数列表，所以在上面的示例中，我们实际上调用的是 flickr.people.getPhotos 方法，这意味着其参数的顺序和数量可以在API文档中找到。

由于改变参数顺序会很乱，因此智能别名主要用于快速调用具有少量参数的方法——如果您必须设置该方法的每个参数，则建议使用 callMethod，因为至少您会清楚地看到哪个参数映射到什么。

从API调用中获取结果

我们现在看到的所有内容都是非常基础的，和大多数Flickr API实现没有区别。这里才是有趣的地方。当你使用上述方法之一在API上发起调用时，你不会直接得到原始的JSON字符串结果（尽管你可以）。默认情况下，Flickering会返回一个Method对象，你可以用它来做各种有趣的事情。

首先，你可以通过->setParameter或通过Flickering的优雅别名在初始调用之后操作结果。

$method = Flickering::peopleGetPhotos('31667913@N06')

$method->setParameter('per_page', 25) // or
$method->setPerPage(25)

$method->getPerPage() // 25

从那里开始，Method提供了三种方法供你从结果中获取信息：->getRawResponse、->getReponse和->getResults。

• 第一个方法，正如其名称所暗示的，只是返回Flickr的原始响应，未经解析和修改。
• 第二个方法返回原始响应，但它将JSON/XML等解析为实际的PHP数组。
• 第三个方法返回一个Results实例，并接受一个可选参数，即你想要直接获取的结果子集。例如，当你从Flickr API的方法获取照片时，实际的照片将嵌套在响应数组的photos键中。你可以直接通过->getResults('photos')获取它们。你也可以通过点符号获取嵌套结果：->getResults('photos.0')。

Results类利用Underscore.php背后的力量创建一个动态的结果存储库，让你可以轻松地操作它们并从它们中获取深层嵌套的信息。你可以在数组文档中看到Underscore提供的操作能力，我还推荐你快速了解Underscore存储库是什么以及它们能做什么。

整个Flickering > Method > Request过程可以通过匹配的Flickering实例上的方法来绕过：->getRawResponseOf、->getResponseOf和->getResultsOf。所以下面的两个例子做了完全相同的事情，只是更快。

$method = Flickering::callMethod('people.getPhotos', array('user_id' => '31667913@N06'))
$results = $method->getResults('photos')

// Same thing
$results = Flickering::getResultsOf('people.getPhotos', array('user_id' => '31667913@N06'))

认证调用

由于Flickr API现在由OAuth提供支持，因此向它发送认证请求将需要用户的权限。为了加快这个过程，Flickering自带了一个Opauth 策略设置。

如果你使用你最喜欢的框架与Flickering一起，请使用它的Router来利用Flickering的getOpauth和getOpauthCallback方法。第一个必须在过程的前两个步骤中返回，第二个必须出现在你的回调页面中（可以是用户授权后发起调用同一页面）。

以下是一个使用Laravel框架的示例实现。

Route::get('flickr/auth', function() {
    Flickering::handshake();
    return Flickering::getOpauth();
});
Route::any('flickr/oauth_callback', function() {
    Flickering::handshake();
    if(Request::getMethod() == 'POST'){
        Flickering::getOpauthCallback();
        return 'Authenticated!';
    }else{
        Flickering::getOpauth();
        return 'Being redirected..';
    }
});

如果你使用任何框架，只想在普通的PHP页面上进行一些请求，示例实现可以通过基本路由和.htaccess在存储库的example文件夹中演示。

与用户一起工作

一旦用户登录，你就可以通过Flickering::getUser()方法获取用户信息，该方法将返回一个包含OAuth过程发送的各个信息的User对象。以下是一些可用的方法：

Flickering::handshake();
$user = Flickering::getUser();

// Get OAuth token
$user->getKey()

// Get Flickr's UID of the person
$user->getUid()

// Get an array of basic informations on the person
$user->getInformations()

// Get the whole schebang : photos, photosets, friends, and other informations made public by the user
$user->getPerson()

此外，Flickering有一个isAuthentified方法供你使用，它将检查OAuth凭据是否可用。

以上就是所有内容！

不要忘记在GitHub Issues中发布任何问题/错误/请求。