Skip to content

Commit

Permalink
docs: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
Yizack committed Jul 22, 2024
1 parent af00cb3 commit 911a9bf
Showing 1 changed file with 30 additions and 14 deletions.
44 changes: 30 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# instagram-feed

[![Packagist](https://img.shields.io/packagist/v/yizack/instagram-feed.svg)](https://packagist.org/packages/yizack/instagram-feed)

PHP library to retrieve an Instagram profile feed, embed the feed of your authorized Instagram accounts on your website. The library uses the Instagram Basic Display API with auto-refreshing access token support.
Expand All @@ -8,20 +9,25 @@ PHP library to retrieve an Instagram profile feed, embed the feed of your author
[![Live Demo](https://yizack.com/images/instagram-feed/demo.gif)](https://instagram-feed.yizack.com/demo/)

## Requeriments
- PHP Hosting (with `composer` and `fopen()` support)

- PHP Hosting (with `composer`, `file_get_contents()`, `file_put_contents()` support)
- Meta Developer App [[Guide]](#meta-developer-app)
- Instagram Basic Display API [[Guide]](#instagram-basic-display-api)

## Installation

To install the library, make sure you have [Composer](https://getcomposer.org/) installed and using your command terminal run the following:

```sh
composer require yizack/instagram-feed
```

## Use

Installing this library will allow you to use the `InstagramFeed` class by simply importing the composer autoload.

Import the composer autoload, use the namespace `Yizack\InstagramFeed` and initialize the `InstagramFeed` object.

```php
require "vendor/autoload.php";
use Yizack\InstagramFeed;
Expand All @@ -32,60 +38,68 @@ $feed = new InstagramFeed(
```

To retrieve your Instagram feed array use the `getFeed()` function.

```php
$array = $feed->getFeed();
```

Or loop it directly in a `foreach` method wherever you need it.

```php
foreach ($feed->getFeed() as $value) {
// your code
}
```

The `getFeed()` function also accepts a comma-separated list of fields to be returned.

```php
$array = $feed->getFeed("username,permalink,timestamp,caption,media_url");
```

For a list of all available fields see: https://developers.facebook.com/docs/instagram-basic-display-api/reference/media#fields

## About the code

### `InstagramFeed` constructor arguments

| Argument | Type | Description | Optional | Default value |
|---|---|---|---|---|
| `token` | string | Your Instagram Basic Display `long-lived-access-token`. | No | |
| `path` | string | The path where the updated file will be saved on your server. | Yes | `ig_token` |
| `filename` | string | The name of the file in which the date of the last token update will be stored. | Yes | `updated.json` |
| Argument | Type | Description | Optional | Default value |
|------------|--------|---------------------------------------------------------------------------------|----------|----------------|
| `token` | string | Your Instagram Basic Display `long-lived-access-token`. | No | |
| `path` | string | The path where the updated file will be saved on your server. | Yes | `ig_token` |
| `filename` | string | The name of the file in which the date of the last token update will be stored. | Yes | `updated.json` |

### `getFeed()` function
Updates the date of the last token update and requests feed data from an Instagram account.


Returns an array with the data of the last 25 posts with the following data for each one:

| Key | Description |
|---|---|
| `username` | Instagram username. |
| `permalink` | Instagram post permalink. |
| `timestamp` | Instagram post timestamp. |
| `caption` | Instagram post caption. |
| `id` | Instagram post identifier. |
| Key | Description |
|-------------|----------------------------|
| `username` | Instagram username. |
| `permalink` | Instagram post permalink. |
| `timestamp` | Instagram post timestamp. |
| `caption` | Instagram post caption. |
| `id` | Instagram post identifier. |

### Long-Lived Access token

This approach uses **Long-Lived Access** Tokens obtained by authorizing your Instagram account with your Meta App.

Since Long-lived tokens are valid for 60 days and can be refreshed as long as they are at least 24 hours old and not expired, the `getFeed()` method will refresh your token everytime it is been called if 24 hours have passed.

Tokens that have not been refreshed in 60 days will expire and can no longer be refreshed, so be sure to visit often the site where you placed the feed.

## Example of use

Check the [`example`](/example/) folder for details.

## Requeriments Guide

### PHP Hosting
You can use any PHP Hosting unless it does not support `fopen()`.

You can use any PHP Hosting unless it does not support `file_get_contents()` and `file_put_contents()`.

### Meta Developer App
In order to use the **Instagram API**, we must first create a **Meta App**. Follow the steps below to create a Meta App.
Expand All @@ -106,6 +120,7 @@ In order to use the **Instagram API**, we must first create a **Meta App**. Foll
[![Meta App Step 6](https://yizack.com/images/instagram-feed/meta-app-7.jpg)](https://developers.facebook.com/)

### Instagram Basic Display API

Now it is time to authorize your instagram account.

1. Back to Products > Instagram > Basic Display. Create new App.\
Expand All @@ -127,4 +142,5 @@ Now it is time to authorize your instagram account.
9. Paste your token in your code.

## Repository

[Yizack/instagram-feed](https://github.com/Yizack/instagram-feed) on GitHub.

0 comments on commit 911a9bf

Please sign in to comment.