README

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

您可以在 Composer 中获取它，只需运行 composer require anahkiasen/flickering 即可。

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

'Flickering\FlickeringServiceProvider',

如果您想使用 facade，也请将其添加到 app.php

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

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

$ php artisan config:publish anahkiasen/flickering

使用 Flickering

创建一个新实例

要使用 Flickering，您当然需要一个来自 Flickr 的 API 密钥，如果您还没有，可以在 这里 获取，它们都很棒，所以它们会免费为您提供。一旦您有了它，就在 Flickering 的 config/config.php 文件中设置它。或者，如果您不想/能这样做，您总是可以将您的凭据传递给构造函数。

要开始使用 Flickering，创建一个新的 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会返回一个方法对象，你可以通过它执行各种有趣的操作。

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

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

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

$method->getPerPage() // 25

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

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

结果类利用了Underscore.php的强大功能，创建了一个活生生的结果存储库，允许你轻松地操作它们并从中获取深层嵌套的信息。你可以在数组文档中了解Underscore提供的操作能力，我也推荐你快速了解一下Underscore存储库是什么以及它们能做什么。

整个Flickering > 方法 > 请求过程可以通过在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一起工作，请使用它的路由器来利用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页面上做一些请求，可以在存储库的example文件夹中找到一个通过基本路由器和.htaccess实现的示例。

与用户一起工作

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

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问题中发布任何问题/错误/请求。