Skip to content

mateusjatenee/php-json-feed

Repository files navigation

PHP Json Feed

Build Status Latest Stable Version Total Downloads Latest Unstable Version License

bitmoji

This library provides a way to generate JSON feeds, a format recently introduced to the community.

Installation via Composer

$ composer require mateusjatenee/php-json-feed

Laravel Installation

On your config/app.php file, register the service provider:

'providers' => [
    ...
    Mateusjatenee\JsonFeed\JsonFeedServiceProvider::class,
];

And on the aliases array, register the facade:

'aliases' => [
    ...
    'JsonFeed' => Mateusjatenee\JsonFeed\Facades\JsonFeed::class,
];

Usage

The library is really simple to use and actually does not depend on Laravel itself, though it allows you to use a config file (not yet). It automatically filters formats the JSON and removes any unnecessary property.

If you're not using Laravel, jump to this part.

How to use it? Let's take the following JSON as an example:

{
    "title": "My JSON Feed test",
    "home_page_url": "https://mguimaraes.co",
    "feed_url": "https://mguimaraes.co/feeds/json",
    "author": {
        "url": "https://twitter.com/mateusjatenee",
        "name": "Mateus Guimarães"
    },
    "icon": "https://mguimaraes.co/assets/img/icons/apple-touch-icon-72x72.png",
    "favicon": "https://mguimaraes.co/assets/img/icons/favicon.ico",
    "version": "https://jsonfeed.org/version/1",
    "items": [
        {
            "content_text": "Great book. It's the best book.",
            "date_published": "2017-05-22T00:00:00+00:00",
            "title": "1984",
            "author": {
                "name": "Mateus",
                "url": "https://mguimaraes.co"
            },
            "content_html": "<p>Great book. It's the best book.</p>",
            "id": "abc123",
            "url": "https://mguimaraes.co",
            "external_url": "https://laravel.com",
            "date_modified": "2017-05-22T00:00:00+00:00"
        },
        {
            "content_text": "Great book. It's the best book.",
            "date_published": "2017-05-22T00:00:00+00:00",
            "title": "1984",
            "author": {
                "name": "Mateus",
                "url": "https://mguimaraes.co"
            },
            "content_html": "<p>Great book. It's the best book.</p>",
            "id": "abc123",
            "url": "https://mguimaraes.co",
            "external_url": "https://laravel.com",
            "date_modified": "2017-05-22T00:00:00+00:00"
        }
    ]
}

To do this, first you need to set the config — you can set it at any time during runtime (on a Service Provider, perhaps) using the Facade or instantiating it through the container (i.e app('jsonFeed'))

<?php

use Mateusjatenee\JsonFeed\Facades\JsonFeed;

$config = [
    'title' => 'My JSON Feed test',
    'home_page_url' => 'https://mguimaraes.co',
    'feed_url' => 'https://mguimaraes.co/feeds/json',
    'author' => [
        'url' => 'https://twitter.com/mateusjatenee',
        'name' => 'Mateus Guimarães',
    ],
    'icon' => 'https://mguimaraes.co/assets/img/icons/apple-touch-icon-72x72.png',
    'favicon' => 'https://mguimaraes.co/assets/img/icons/favicon.ico',
];

JsonFeed::setConfig($config);

Then, you need to set the items. The items may be an array of objects or a collection of objects. We're gonna talk about this a bit later.

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use JsonFeed;

class JsonFeedController extends Controller
{
    public function index()
    {
        $posts = App\Post::all();

        return JsonFeed::setItems($posts)->toJson();
    }
}

All at once

Alternatively, you may do all at once, specially if you are not using Laravel.

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use JsonFeed;

class JsonFeedController extends Controller
{
    public function index()
    {
        $posts = App\Post::all();

        $config = [
            'title' => 'My JSON Feed test',
            'home_page_url' => 'https://mguimaraes.co',
            'feed_url' => 'https://mguimaraes.co/feeds/json',
            'author' => [
                'url' => 'https://twitter.com/mateusjatenee',
                'name' => 'Mateus Guimarães',
            ],
            'icon' => 'https://mguimaraes.co/assets/img/icons/apple-touch-icon-72x72.png',
            'favicon' => 'https://mguimaraes.co/assets/img/icons/favicon.ico',
        ];

        return JsonFeed::start($config, $posts)->toJson();
    }
}

How to get each item properties

It's really simple. An item only requires an id, the other fields are optional but highly recommended. First of all, your model (or any other object that is gonna be used on the json feed) needs to implement \Mateusjatenee\JsonFeed\Contracts\FeedItemContract and it's only method - getFeedId(). It should return an unique Id relative to that item. Below is a list of each method and what it does.

Method What it does Expects
getFeedId Gets a unique ID string
getFeedUrl Gets the URL of the resource string
getFeedExternalUrl Gets the URL of the page elsewhere string
getFeedTitle Gets the resource title string
getFeedContentHtml Gets the HTML of the content string
getFeedContentText Gets the text of the content string
getFeedSummary Gets the resource summary string
getFeedImage Gets the resource image string
getFeedBannerImage Gets the resource banner image string
getFeedDatePublished Gets the resource published date. The lib automatically converts it to the specific date format. string
getFeedDateModified Gets the resource modified date. The lib automatically converts it to the specific date format. string
getFeedAuthor Gets the resource author. If not specified, the same as the top level one is going to be used. string
getTags Gets the resource tags. array

You may find all accepted methods on the JSON Feed Spec

Running tests

$ composer test

License

This library is licensed under the MIT license. Please see LICENSE for more details.

Changelog

Please see CHANGELOG for more details.

Contributing

Please see CONTRIBUTING for more details.