Documentation about PHP 7.1 migration

README.md

@@ -37,7 +37,7 @@ Use Composer to add feed-io into your project's requirements :
 
 feed-io requires :
 
-- php 7.0+
+- php 7.1+
 - psr/log 1.0
 - guzzlehttp/guzzle 6.2+
 
@@ -46,6 +46,14 @@ it suggests :
 
 Monolog is not the only library suitable to handle feed-io's logs, you can use any PSR/Log compliant library instead.
 
+## Still on PHP 5 ?
+
+No problem, you can still install feed-io 3.0. This version will be supported until the end of PHP 5.6 security fixes (31 december 2018).
+
+## Why skipping PHP 7.0 ?
+
+feed-io 4 requires PHP 7.1+ because return types cannot be nullable in PHP 7.0.
+
 # Fetching the repository
 
 Do this if you want to contribute (and you're welcome to do so):

UPGRADE-4.0.md

@@ -0,0 +1,55 @@
+# UPGRADE FROM 3.x to 4.0
+
+The major change in version 4.0 is the full migration to PHP 7.1. It has an impact on interface implementations.
+
+## Types are explicit
+
+From now on, all types are explicits in method signatures. It has an impact on classes that implements :
+
+ - \FeedIo\FeedInterface 
+ - \FeedIo\Feed\ItemInterface
+ - \FeedIo\Feed\NodeInterface
+ - \FeedIo\Feed\ElementsAwareInterface
+ - \FeedIo\Feed\Item\AuthorInterface
+ - \FeedIo\Feed\Item\MediaInterface
+ - \FeedIo\Feed\Node\CategoryInterface
+ - \FeedIo\Feed\Node\ElementInterface
+
+For instance, `FeedIo\FeedInterface::setUrl($url)` becomes :
+
+```php
+    /**
+     * @param string $url
+     * @return FeedInterface
+     */
+    public function setUrl(string $url) : FeedInterface;
+```
+As a consequence, you need to adapt any class that implements `FeedIo\FeedInterface` according to the new signature : 
+
+```php
+    /**
+     * @param string $url
+     * @return FeedInterface
+     */
+    public function setUrl($url)
+    {
+        $this->url = $url;
+
+        return $this;
+    }
+```
+becomes : 
+
+```php
+    /**
+     * @param string $url
+     * @return FeedInterface
+     */
+    public function setUrl(string $url) : FeedInterface
+    {
+        $this->url = $url;
+
+        return $this;
+    } 
+```
+You should refer to the new interfaces declaration to get the full list of concerned functions.