README

轻松将Instagram动态集成到您的项目中。

本包的目标是将Instagram动态集成到项目中变得尽可能简单和用户友好，使用Instagram的基本显示API。该包将动态存储在您的缓存中，并提供您按自己的时间表刷新动态的能力。

注意此包需要PHP 8。如果您不喜欢它，则可以继续使用v2。

安装

composer require dymantic/laravel-instagram-feed

注意如果您是从v2.*升级，请参阅升级指南，因为有一些破坏性更改。另外注意 此版本需要PHP 8及以上版本，所以如果您仍在PHP 7上，且在安装时没有指定版本，Composer将拉取^v2，在这种情况下，您应该阅读此页面。

教程

这个过程中的一些部分可能有点令人困惑，尤其是如果您不熟悉OAuth流程。我包括了一个教程，以尝试使事情更清晰。对这个教程的反馈或改进将非常受欢迎。

开始之前

要使用Instagram基本显示API，您需要设置一个具有正确权限的Facebook应用。如果您还没有，请访问Facebook开发者文档并按照说明进行。

Instagram媒体的处理方式

Instagram通过此API提供三种媒体类型：图片、视频和轮播图。本包简化为仅包含图片和视频的动态。如果您不想包含任何视频，可以使用ignore_video配置选项。对于轮播图项目，使用轮播图的第一项。如果忽略视频，将使用第一张图片，如果存在的话。轮播图项目有一个children属性，其中包含实际的轮播图项目。

关于忽略视频的说明

如果您选择忽略视频，您的动态大小可能小于您请求的限制。如果您预计会忽略视频帖子，您可能需要增加您获取的帖子数量（见下文“获取动态”）。

设置

使用php artisan vendor:publish发布必要的迁移和配置，并使用php artisan migrate运行迁移。

配置

如上所述发布供应商资产将为您提供一个config/instagram-feed.php文件。在开始之前，您需要添加配置。文件中的注释解释了每个设置。

// config/instagram-feed.php

<?php

return [
    /*
     * The client_id from registering your app on Instagram
     */
    'client_id'           => 'YOUR INSTAGRAM CLIENT ID',

    /*
     * The client secret from registering your app on Instagram,
     * This is not the same as an access token.
     */
    'client_secret'       => 'YOUR INSTAGRAM CLIENT SECRET',

    /*
     * The base url used to generate to auth callback route for instagram.
     * This defaults to your APP_URL, so normally you may leave it as null
     */
    'base_url' => null,

    /*
     * The route that will respond to the Instagram callback during the OAuth process.
     * Only enter the path without the leading slash. You need to ensure that you have registered
     * a redirect_uri for your instagram app that is equal to combining the
     *  app url (from config) and this route
     */
    'auth_callback_route' => 'instagram/auth/callback',

    /*
     * On success of the OAuth process you will be redirected to this route.
     * You may use query strings to carry messages
     */
    'success_redirect_to' => 'instagram-auth-success',

    /*
     * If the OAuth process fails for some reason you will be redirected to this route.
     * You may use query strings to carry messages
     */
    'failure_redirect_to' => 'instagram-auth-failure'

    /*
     * You may filter out video media types by setting this to true. Carousel media
     * will become the first image in the carousel, and if there are no images, then
     * the entire carousel will be ignored.
     */
     'ignore_video' => false,

    /*
     * You may set an email address below if you wish to be notified of errors when
     * attempting to refresh the Instagram feed.
     */
    'notify_on_error' => null,
];

个人资料

本包提供了一个Dymantic\InstagramFeed\Profile模型，该模型对应于Instagram个人资料/帐户。您需要在您的应用程序/网站上为每个要使用的动态创建一个个人资料。创建个人资料后，您需要授权个人资料才能获取其动态。

创建个人资料

您可以在代码中以编程方式创建个人资料，如下所示。您只需要为个人资料提供一个唯一的用户名。这不需要与Instagram用户名匹配，可以是您希望用来引用个人资料的任何名称。

$profile = \Dymantic\InstagramFeed\Profile::new('my profile');

对于一个项目只有一个配置文件是相当常见的用例，因此这个包包含了一个 artisan 命令来快速创建配置文件，这样你就不需要为用户构建必要的 UI。运行 php artisan instagram-feed:profile {username} 将会创建一个带有该用户名的配置文件，你可以按需使用。

获取授权

一旦你有了配置文件，你可以在它上面调用 getInstagramAuthUrl() 方法来获取一个用于向用户提供认证的链接。当用户访问该链接时，他们可以授权访问你的应用（或不授权）。如果一切顺利，用户将会被重定向回你在配置文件中设置的 success_redirect_to 路由。如果未授权，你将会被重定向到配置的 failure_redirect_to 路由。

如果你没有正确设置你的 client_id 和/或 client_secret，或者你的 Instagram 应用不接受用户，Instagram 不会进行重定向，用户将会看到 Instagram 的错误信息。

忽略默认的认证回调路由

在某些情况下，你可能需要忽略配置中的认证回调路由，以便你可以自行处理该路由。为此，你可以在你的 AppServiceProvider 中调用 Instagram::ignoreRoutes()。

刷新访问令牌

API 的长期访问令牌在 60 天后过期。这个包包含了一个 artisan 命令来处理这个问题，你只需要确保它至少每 60 天运行一次。命令是 php artisan instagram-feed:refresh-tokens

获取流

一旦你的配置文件进行了认证，你可以直接从 InstagramFeed 类中检索流，或者首先获取配置文件，然后调用其上的 feed 方法。

$feed = \Dymantic\InstagramFeed\InstagramFeed::for('my profile');

或者

$profile = \Dymantic\InstagramFeed\Profile::for('my profile')
$feed = $profile?->feed();

一旦流被检索，它将会被永久缓存，并且相同的缓存结果将会返回，直到你 refresh 流。通常这是通过计划好的 chron job 来完成的。

限制流中的项目数量

默认情况下，流中的项目数量为 20。当你获取流时，你可以传递一个可选的整数参数，例如：\Dymantic\InstagramFeed\InstagramFeed::for('my profile', 15) 或者 $profile?->feed(15) 以限制数量。

获取所有帖子（无限制）

如果你想要获取所有帖子（最多 1000 条），你可以将 null 作为限制参数传递给 refreshFeed 或 feed 方法。这个包将会进行多次请求以获取你所有的历史帖子，最多 1000 条。然后你可以使用帖子的时间戳进行排序、分页等。

设置限制和缓存

当流从缓存中提供时，限制将不起作用。如果你想要将限制更改为之前使用的限制，你将不得不 refresh 流。

设置限制和忽略视频

如果你选择忽略视频，你的流大小可能小于你请求的限制。如果你预计会忽略视频帖子，你可能想要增加你检索的帖子数量。

更新流

你可以像获取流一样刷新流。

$feed = \Dymantic\InstagramFeed\InstagramFeed::for('my profile')->refresh();

或者

$profile = \Dymantic\InstagramFeed\Profile::for('my profile')
$feed = $profile?->refreshFeed();

刷新动态返回一个InstagramFeed实例，然而，与获取常规动态不同，此方法如果在发生错误时可能会抛出异常。想法是在某个地方的后台刷新您的动态，通常是在计划任务中。此包包含一个Artisan命令php artisan instagram-feed:refresh，该命令将刷新所有授权的配置文件，并在发生错误时处理错误。如果您在配置中设置了电子邮件地址，则在发生错误时，该地址将被通知。建议使用Laravel的调度功能以您认为合适的频率运行此命令。

使用动态

一旦您有了动态，您可以将其发送到您的视图，在那里它可以被迭代，每个动态中的项目都是一个InstagramMedia类的实例。

// somewhere in a Controller
public function show() {
    $feed = \Dymantic\InstagramFeed\InstagramFeed::for('my profile');

    return view('instagram-feed', ['instagram_feed' => $feed]);
}

// instagram-feed.blade.php

@foreach($instagram_feed as $post)
    <img src={{ $post->url }} alt="A post from my instagram">
@endforeach

如果您想对动态的项目有更多的控制，您可以在动态上调用collect方法来检索动态项目作为Laravel Collection。

动态项目

每个动态项目都是一个InstagramMedia类的实例，并提供以下属性和方法

dymantic / laravel-instagram-feed

维护者

详细信息