Merge branch 'release/v2.0.0'

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 REZO ZERO
+Copyright (c) 2019 REZO ZERO
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -3,10 +3,20 @@
 > A PHP library to rule them all, to entangle them with magic, a PHP library to gather them and bind them in darkness
 
 [![SensioLabsInsight](https://insight.sensiolabs.com/projects/ed3544de-7d64-4ef9-a551-c61a66fb668d/mini.png)](https://insight.sensiolabs.com/projects/ed3544de-7d64-4ef9-a551-c61a66fb668d)
-![License](http://img.shields.io/:license-mit-blue.svg)
+![License](http://img.shields.io/:license-mit-blue.svg?style=flat) ![Packagist](https://img.shields.io/packagist/v/rezozero/mixedfeed.svg?style=flat)
+
+- [Install](#install)
+- [Combine feeds](#combine-feeds)
+- [Use *FeedItem* instead of raw feed](#use--feeditem--instead-of-raw-feed)
+- [Feed providers](#feed-providers)
+- [Modify cache TTL](#modify-cache-ttl)
+- [Create your own feed provider](#create-your-own-feed-provider)
+  * [Create a feed provider from a *Doctrine* repository](#create-a-feed-provider-from-a--doctrine--repository)
 
 ## Install
 
+*mixedfeed* v2+ needs at least PHP 7.1, check your server configuration.
+
 ```shell
 composer require rezozero/mixedfeed
 ```
@@ -70,6 +80,10 @@ $feed = new MixedFeed([
 ]);
 
 return $feed->getItems(12);
+// Or use canonical \RZ\MixedFeed\Canonical\FeedItem objects
+// for a better compatibility and easier templating with multiple
+// social platforms.
+return $feed->getCanonicalItems(12);
 ```
 
 ## Combine feeds
@@ -95,10 +109,24 @@ For example, if you are using *Twig*, you will be able to include a sub-template
 * `normalizedDate`: This is a crucial parameter as it allows *mixedfeed* library to sort *antechronologically* multiple feeds with heterogeneous structures.
 * `canonicalMessage`: This is a useful field which contains the **text content** for each item over **all** platforms. You can use this to display items texts within a simple loop.
 
+## Use *FeedItem* instead of raw feed
+
+If you need to serialize your MixedFeed to JSON or XML again, you should not want all the raw data contained in each
+social feed item. So you can use the `$feed->getCanonicalItems(12);` method instead of `getItems` to get a more concise
+object with essential data: `RZ\MixedFeed\Canonical\FeedItem`.
+
+When FeedItem has images, `FeedItem::$images` will hold an array of `RZ\MixedFeed\Canonical\Image` objects to
+have better access to its `url`, `width` and `height` if they're available.
+
+Each feed provider must implement how to *hydrate* a `FeedItem` from the raw feed overriding `createFeedItemFromObject()`
+method.
+
 ## Feed providers
 
 |  Feed provider class  |  Description | `feedItemPlatform` |
 | -------------- | ---------------- | ------------------ |
+| Medium | Call over `https://medium.com/@username/latest` endpoint. It only needs a `$username`  | `medium` |
+| InstagramOEmbedFeed | Call over `https://api.instagram.com/oembed/` endpoint. It only needs a `$embedUrls` array | `instagram_oembed` |
 | InstagramFeed | Call over `/v1/users/$userId/media/recent/` endpoint. It needs a `$userId` and an `$accessToken` | `instagram` |
 | TwitterFeed | Call over `statuses/user_timeline` endpoint. It requires a `$userId`, a `$consumerKey`, a `$consumerSecret`, an `$accessToken` and an `$accessTokenSecret`. Be careful, this [endpoint](https://dev.twitter.com/rest/reference/get/statuses/user_timeline) can **only return up to 3,200 of a user’s most recent Tweets**, your item count could be lesser than expected. In the same way, Twitter removes retweets after retrieving the items count. | `twitter` |
 | TwitterSearchFeed | Call over `search/tweets` endpoint. It requires a `$queryParams` array, a `$consumerKey`, a `$consumerSecret`, an `$accessToken` and an `$accessTokenSecret`. Be careful, Twitter API **won’t retrieve tweets older than 7 days**, your item count could be lesser than expected. `$queryParams` must be a *key-valued* array with *query operators* according to [Twitter API documentation](https://dev.twitter.com/rest/public/search). | `twitter` |
@@ -118,6 +146,7 @@ There are plenty of APIs on the internet, and this tool won’t be able to handl
 No problem, you can easily create your own feed provider to use in *mixedfeed*. You just have to create a new *class* that
 will inherit from `RZ\MixedFeed\AbstractFeedProvider`. Then you will have to implement each method from `FeedProviderInterface`:
 
+* `createFeedItemFromObject($item)` method which transform a raw feed object into a canonical `RZ\MixedFeed\Canonical\FeedItem` and `RZ\MixedFeed\Canonical\Image`
 * `getDateTime` method to look for the critical datetime field in your feed.
 * `getFeed` method to consume your API endpoint with a count limit and take care of caching your responses. 
 This method **must convert your own feed items into `\stdClass` objects.**
@@ -141,8 +170,6 @@ protected $entityManager;
 public function __construct(\Doctrine\ORM\EntityManagerInterface $entityManager)
 {
     $this->entityManager = $entityManager;
-    $this->tags = $tags;
-    $this->timespan = $timespan;
 }
 
 protected function getFeed($count = 5)
@@ -160,6 +187,22 @@ protected function getFeed($count = 5)
         )
     );
 }
+
+protected function createFeedItemFromObject($item)
+{
+    $feedItem = new RZ\MixedFeed\Canonical\FeedItem();
+    $feedItem->setDateTime($this->getDateTime($item));
+    $feedItem->setMessage($this->getCanonicalMessage($item));
+    $feedItem->setPlatform($this->getFeedPlatform());
+
+    for ($item->images as $image) {
+        $feedItemImage = new RZ\MixedFeed\Canonical\Image();
+        $feedItemImage->setUrl($image->url);
+        $feedItem->addImage($feedItemImage);
+    }
+
+    return $feedItem;
+}
 ```
 
 Then you can define your *date-time* and *canonical message* methods to look into this object:

composer.json

@@ -19,9 +19,12 @@
         "rezo zero"
     ],
     "require": {
+        "php": ">=7.1",
         "abraham/twitteroauth": "^0.7.4",
         "doctrine/cache": "^1.6.2",
-        "guzzlehttp/guzzle": "~5.0 || ~6.0"
+        "guzzlehttp/guzzle": "~6.0",
+        "ext-json": "*",
+        "jms/serializer": "^2.1"
     },
     "autoload": {
         "psr-4": {"RZ\\MixedFeed\\": "src/"}

src/AbstractFeedProvider.php

@@ -25,6 +25,7 @@
  */
 namespace RZ\MixedFeed;
 
+use RZ\MixedFeed\Canonical\FeedItem;
 use RZ\MixedFeed\Exception\FeedProviderErrorException;
 
 /**
@@ -63,9 +64,27 @@ public function getItems($count = 5)
                 }
             }
             return $list;
-        } else {
-            throw new FeedProviderErrorException($this->getFeedPlatform(), $this->getErrors($list));
         }
+        throw new FeedProviderErrorException($this->getFeedPlatform(), $this->getErrors($list));
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getCanonicalItems($count = 5)
+    {
+        $list = $this->getFeed($count);
+
+        if ($this->isValid($list)) {
+            $items = [];
+            foreach ($list as $index => $item) {
+                if (is_object($item)) {
+                    $items[] = $this->createFeedItemFromObject($item);
+                }
+            }
+            return $items;
+        }
+        throw new FeedProviderErrorException($this->getFeedPlatform(), $this->getErrors($list));
     }
 
     /**
@@ -91,4 +110,18 @@ public function setTtl($ttl)
 
         return $this;
     }
+
+    /**
+     * @param \stdClass $item
+     *
+     * @return FeedItem
+     */
+    protected function createFeedItemFromObject($item)
+    {
+        $feedItem = new FeedItem();
+        $feedItem->setDateTime($this->getDateTime($item));
+        $feedItem->setMessage($this->getCanonicalMessage($item));
+        $feedItem->setPlatform($this->getFeedPlatform());
+        return $feedItem;
+    }
 }

src/AbstractFeedProvider/AbstractTwitterFeed.php

@@ -28,6 +28,7 @@
 use Abraham\TwitterOAuth\TwitterOAuth;
 use Doctrine\Common\Cache\CacheProvider;
 use RZ\MixedFeed\AbstractFeedProvider as BaseFeedProvider;
+use RZ\MixedFeed\Canonical\Image;
 use RZ\MixedFeed\Exception\CredentialsException;
 
 /**
@@ -143,4 +144,29 @@ public function getErrors($feed)
 
         return $errors;
     }
+
+    /**
+     * @inheritDoc
+     */
+    protected function createFeedItemFromObject($item)
+    {
+        $feedItem = parent::createFeedItemFromObject($item);
+        $feedItem->setId($item->id_str);
+        $feedItem->setAuthor($item->user->name);
+        if (isset($item->entities->urls[0])) {
+            $feedItem->setLink($item->entities->urls[0]->expanded_url);
+        }
+
+        if (isset($item->entities->media)) {
+            foreach ($item->entities->media as $media) {
+                $feedItemImage = new Image();
+                $feedItemImage->setUrl($media->media_url_https);
+                $feedItemImage->setWidth($media->sizes->large->w);
+                $feedItemImage->setHeight($media->sizes->large->h);
+                $feedItem->addImage($feedItemImage);
+            }
+        }
+
+        return $feedItem;
+    }
 }