Duncan McClean

YumYum Documentation

Duncan McClean

How it works

YumYum has a concept of feeds, each feed has it's own source (a JSON, RSS, XML feed) and has a destination, whether that be entries in a collection or terms in a taxonomy.

Whenever a feed is run, it goes through three steps:

  1. It'll use a 'source parser' to get the items from the feed and return it in such a way everything else can understand.
  2. Then, the feed items will pass through a 'transformer', this decides how to map the data from your feed item into your fields.
  3. After the data has been transformed, it will finally be saved as an entry or taxonomy term.

Viewing Run History

If you want check the last time YumYum ran your feed, you can have a look at its 'run history'.

To view the history log, click on the name of your feed in the Feeds page of the Control Panel. You should then be able to view the last 10 times the feed has been run. It'll tell you both the date/time of last run and how many items were saved as part of that run. This may be helpful if you need to troubleshoot your feed not working correctly.

History Log

Running your feed

This is probably what you installed YumYum for, to actually import & save your data! You've got two options when it comes to running your feed. You can either run it whenever you want via the CP or you can run it automatically with CRON/Laravel's scheduler.

On-demand via the CP:

  1. In your Feeds page in the Control Panel, find the feed you'd like to run.
  2. Click on the button at the end of the feed row, and click on the 'Run' option.
  3. Your feed will now be running, either on your request, or on the queue, depending on your site's configuration.

Automatically with the Laravel Scheduler:

We're only going to cover the process of actually adding YumYum's command to the Laravel scheduler, not how to setup the scheduler on your server. You can learn about that over on the Laravel documentation.

  1. Open your app/Console/Kernel.php file.
  2. Add the below snippet to the schedule method of the Kernel.php file
/**
 * Define the application's command schedule.
 *
 * @param  \Illuminate\Console\Scheduling\Schedule  $schedule
 * @return void
 */
protected function schedule(Schedule $schedule)
{
    // $schedule->command('inspire')
    //          ->hourly();

    $schedule->command('yumyum:run')
        ->hourly();
}

That snippet will run YumYum's importer every hour. You may wish to adjust the schedule on which it's run, for that you may view the Laravel documentation.

Source Parsers

If you're pulling information in from an API, you may need to provide special headers to your API requests or use a certain part of the response body as your 'feed items'. This can't be done with the built-in 'source parsers', however you can build your own, extending on YumYum's built-in code.

Source Parsers look like so:

<?php

namespace App;

use DoubleThreeDigital\YumYum\Feeds\Sources\JSON;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\Http;

class CustomJsonSource extends JSON
{
    public function handle(): Collection
    {
        $response = Http::get($this->source['url']);

        return collect($response->json()['data']); // Here we're grabbing 'feed items' from inside the response's `data` array.
    }
}

The above example extends on the built-in JSON source parser.

The handle method is where all the important code should go. From it, you should return a collection of 'feed items' which will one by one be sent to Destination Transformers before being saved.

Destination Transformers

Destination Transformers (also sometimes referred to as simply, Transformers) are classes used in between the step of getting your data and saving your data. If you're familiar with Laravel, a transformer is kind of like an API resource.

By default, YumYum uses a really simple transformer, where everything from the feed's response is then saved.

<?php

namespace DoubleThreeDigital\YumYum\Feeds\Transformers;

use DoubleThreeDigital\YumYum\Contracts\Transformer as Contract;

class Entry implements Contract
{
    protected array $item;

    public function __construct(array $item)
    {
        $this->item = $item;
    }

    public function toArray(): array
    {
        return $this->item;
    }
}

The $item is passed in to your constructor and then your toArray method should return an array of data (this is what get's saved).

However, most of the time you'll probably want to use your own, custom transformer. To make it easy, run php please yumyum:transformer, followed by the name of your transformer, for example:

php please yumyum:transformer WordPress

The comamnd will generate a WordPress transformer in your App\Transformers directory with some boilerplate code, enough for you to get started!

Mapping to fields

As you know, the toArray method should return an array of data, this is what is later saved as an Entry or Term, depending on what you have configured. Most of the time, you'll want to map the data you get back from the feed to your own fields, setup in your blueprint.

Let's take a Transistor.fm feed for example and let's map it to our custom fields.

public function toArray(): array
{
    return [
        'title' => $this->item['title'],
        'embed_url' => str_replace('https://share.transistor.fm/s/', 'https://share.transistor.fm/e/', $this->item['link']),
        'show_notes' => $this->item['description'],
    ];
}

🔥 Hot Tip: You can use array_merge to pull in existing attributes as well as your custom ones.