Merge pull request #141 from alexdebril/issue/136

Issue/136

README.md

@@ -197,6 +197,18 @@ $feedIo = new FeedIo($client, $logger);
 
 ```
 
+## Dealing with missing timezones
+
+Sometimes you have to consume feeds in which the timezone is missing from the dates. In some use-cases, you may need to specify the feed's timezone to get an accurate value, so feed-io offers a workaround for that : 
+
+```php
+$feedIo->getDateTimeBuilder()->setFeedTimezone(new \DateTimeZone($feedTimezone));
+$result = $feedIo->read($feedUrl);
+$feedIo->getDateTimeBuilder()->resetFeedTimezone();
+``` 
+
+Don't forget to reset `feedTimezone` after fetching the result, or you'll end up with all feeds located in the same timezone.
+
 ## Online documentation and API reference
 
 The whole documentation and API reference is available at https://feed-io.net/documentation.html

examples/force-timezone.php

@@ -0,0 +1,44 @@
+<?php
+/*
+ * This file is part of the feed-io package.
+ *
+ * (c) Alexandre Debril <alex.debril@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require __DIR__.DIRECTORY_SEPARATOR.'bootstrap.php';
+
+$feedIo = \FeedIo\Factory::create()->getFeedIo();
+
+$feedIo->getDateTimeBuilder()->setFeedTimezone(new \DateTimeZone('-0500'));
+$result = $feedIo->read('http://news.php.net/group.php?group=php.announce&format=rss');
+
+echo "First item's pubDate raw value in the feed"  .PHP_EOL;
+
+$domItems = $result->getDocument()->getDOMDocument()->getElementsByTagName('item');
+
+/** @var \DOMElement $firstDomItem */
+$firstDomItem = $domItems->item(0);
+$pubDate = $firstDomItem->getElementsByTagName('pubDate')->item(0);
+
+var_dump($pubDate->nodeValue);
+
+$pubDateTime = new \DateTime($pubDate->nodeValue);
+
+echo "here is its timestamp : {$pubDateTime->getTimestamp()}" . PHP_EOL;
+
+$feed = $result->getFeed();
+
+/** @var \FeedIo\Feed\ItemInterface $item */
+$feed->rewind();
+$item = $feed->current();
+
+echo "var_dump the first item's pubDate after parsing. It's the same date converted in your local configuration's timezone" . PHP_EOL;
+var_dump($item->getLastModified());
+echo "here is its timestamp : {$item->getLastModified()->getTimestamp()}" . PHP_EOL;
+
+if($pubDateTime->getTimestamp() === $item->getLastModified()->getTimestamp()) {
+    echo "HOURAY, both timestamps match !" . PHP_EOL;
+}

examples/missing-timezone.php

@@ -0,0 +1,39 @@
+<?php
+/*
+ * This file is part of the feed-io package.
+ *
+ * (c) Alexandre Debril <alex.debril@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require __DIR__.DIRECTORY_SEPARATOR.'bootstrap.php';
+
+echo 'see https://github.com/alexdebril/feed-io/issues/134 for full explanations' . PHP_EOL;
+
+$dateTimeBuilder = new \FeedIo\Rule\DateTimeBuilder();
+$pubDate = 'Wed, 02 Aug 2017 07:21:29';
+
+echo 'the publish date\'s timezone is America/chicago but $dateTimeBuilder ignores it. The date below is wrong'  . PHP_EOL;
+
+$dateTime = $dateTimeBuilder->convertToDateTime($pubDate);
+
+var_dump($dateTime);
+echo "timestamp : {$dateTime->getTimestamp()}" . PHP_EOL;
+
+echo 'after setting the feed\'s timezone in the builder\'s attributes, the date is right' . PHP_EOL;
+
+$dateTimeBuilder->setFeedTimezone(new \DateTimeZone('America/Chicago'));
+
+$dateTime = $dateTimeBuilder->convertToDateTime($pubDate);
+
+var_dump($dateTime);
+echo "timestamp : {$dateTime->getTimestamp()}" . PHP_EOL;
+
+echo 'if I really want the date in its original timezone, I can set it' . PHP_EOL;
+
+$dateTime->setTimezone(new \DateTimeZone('America/Chicago'));
+
+var_dump($dateTime);
+echo "timestamp : {$dateTime->getTimestamp()}" . PHP_EOL;

src/FeedIo/Adapter/ClientInterface.php

@@ -10,6 +10,8 @@
 
 namespace FeedIo\Adapter;
 
+use FeedIo\Adapter\ResponseInterface;
+
 /**
  * Describes a HTTP Client used by \FeedIo\Reader
  *
@@ -26,5 +28,5 @@ interface ClientInterface
      * @throws \FeedIo\Adapter\ServerErrorException
      * @return \FeedIo\Adapter\ResponseInterface
      */
-    public function getResponse($url, \DateTime $modifiedSince);
+    public function getResponse(string $url, \DateTime $modifiedSince) : ResponseInterface;
 }

src/FeedIo/Adapter/FileSystem/Client.php

@@ -12,6 +12,7 @@
 
 use FeedIo\Adapter\ClientInterface;
 use FeedIo\Adapter\NotFoundException;
+use FeedIo\Adapter\ResponseInterface;
 
 /**
  * Filesystem client
@@ -25,7 +26,7 @@ class Client implements ClientInterface
      * @throws \FeedIo\Adapter\NotFoundException
      * @return \FeedIo\Adapter\ResponseInterface
      */
-    public function getResponse($path, \DateTime $modifiedSince)
+    public function getResponse(string $path, \DateTime $modifiedSince) : ResponseInterface
     {
         if (file_exists($path)) {
             return new Response(

src/FeedIo/Adapter/FileSystem/Response.php

@@ -32,7 +32,7 @@ class Response implements ResponseInterface
      * @param string    $fileContent
      * @param \DateTime $lastModified
      */
-    public function __construct($fileContent, \DateTime $lastModified)
+    public function __construct(string $fileContent, \DateTime $lastModified)
     {
         $this->fileContent  = $fileContent;
         $this->lastModified = $lastModified;
@@ -41,40 +41,40 @@ public function __construct($fileContent, \DateTime $lastModified)
     /**
     * @return boolean
     */
-    public function isModified()
+    public function isModified() : bool
     {
         return true;
     }
 
     /**
      * @return string
      */
-    public function getBody()
+    public function getBody() : ? string
     {
         return $this->fileContent;
     }
 
     /**
-     * @return array
+     * @return iterable
      */
-    public function getHeaders()
+    public function getHeaders() : iterable
     {
-        return array();
+        return [];
     }
 
     /**
      * @param  string $name
-     * @return string
+     * @return iterable
      */
-    public function getHeader($name)
+    public function getHeader(string $name) : iterable
     {
-        return '';
+        return [];
     }
 
     /**
      * @return \DateTime
      */
-    public function getLastModified()
+    public function getLastModified() : ?\DateTime
     {
         return $this->lastModified;
     }

src/FeedIo/Adapter/Guzzle/Client.php

@@ -12,6 +12,7 @@
 
 use FeedIo\Adapter\ClientInterface;
 use FeedIo\Adapter\NotFoundException;
+use FeedIo\Adapter\ResponseInterface;
 use FeedIo\Adapter\ServerErrorException;
 use GuzzleHttp\Exception\BadResponseException;
 
@@ -40,7 +41,7 @@ public function __construct(\GuzzleHttp\ClientInterface $guzzleClient)
      * @throws \FeedIo\Adapter\ServerErrorException
      * @return \FeedIo\Adapter\ResponseInterface
      */
-    public function getResponse($url, \DateTime $modifiedSince)
+    public function getResponse(string $url, \DateTime $modifiedSince) : ResponseInterface
     {
         try {
             $options = [

src/FeedIo/Adapter/Guzzle/Response.php

@@ -36,46 +36,46 @@ public function __construct(PsrResponseInterface $psrResponse)
     /**
      * @return boolean
      */
-    public function isModified()
+    public function isModified() : bool
     {
         return $this->psrResponse->getStatusCode() != 304 && $this->psrResponse->getBody()->getSize() > 0;
     }
 
     /**
-     * @return \Psr\Http\Message\StreamInterface
+     * @return string
      */
-    public function getBody()
+    public function getBody() : ? string
     {
         return $this->psrResponse->getBody()->getContents();
     }
 
     /**
      * @return \DateTime|null
      */
-    public function getLastModified()
+    public function getLastModified() : ?\DateTime
     {
         if ($this->psrResponse->hasHeader(static::HTTP_LAST_MODIFIED)) {
-            $lastModified = \DateTime::createFromFormat(\DateTime::RFC2822, $this->getHeader(static::HTTP_LAST_MODIFIED));
+            $lastModified = \DateTime::createFromFormat(\DateTime::RFC2822, $this->getHeader(static::HTTP_LAST_MODIFIED)[0]);
 
             return false === $lastModified ? null : $lastModified;
         }
 
-        return;
+        return null;
     }
 
     /**
-     * @return array
+     * @return iterable
      */
-    public function getHeaders()
+    public function getHeaders()  : iterable
     {
         return $this->psrResponse->getHeaders();
     }
 
     /**
      * @param  string       $name
-     * @return string[]
+     * @return iterable
      */
-    public function getHeader($name)
+    public function getHeader(string $name) : iterable
     {
         return $this->psrResponse->getHeader($name);
     }

src/FeedIo/Adapter/NullClient.php

@@ -21,7 +21,7 @@ class NullClient implements ClientInterface
      * @param  \DateTime                         $modifiedSince
      * @return \FeedIo\Adapter\ResponseInterface
      */
-    public function getResponse($url, \DateTime $modifiedSince)
+    public function getResponse(string $url, \DateTime $modifiedSince) : ResponseInterface
     {
         return new NullResponse();
     }

src/FeedIo/Adapter/NullResponse.php

@@ -19,41 +19,41 @@ class NullResponse implements ResponseInterface
     /**
      * @return string
      */
-    public function getBody()
+    public function getBody() : ? string
     {
-        return;
+        return null;
     }
 
     /**
     * @return boolean
     */
-    public function isModified()
+    public function isModified() : bool
     {
         return true;
     }
 
     /**
      * @return \DateTime
      */
-    public function getLastModified()
+    public function getLastModified() : ?\DateTime
     {
         return new \DateTime('@0');
     }
 
     /**
-     * @return array
+     * @return iterable
      */
-    public function getHeaders()
+    public function getHeaders() : iterable
     {
-        return array();
+        return [];
     }
 
     /**
      * @param  string       $name
-     * @return array|string
+     * @return iterable
      */
-    public function getHeader($name)
+    public function getHeader(string $name) : iterable
     {
-        return $name;
+        return [];
     }
 }

src/FeedIo/Adapter/ResponseInterface.php

@@ -20,26 +20,26 @@ interface ResponseInterface
     /**
      * @return string
      */
-    public function getBody();
+    public function getBody() : ? string;
 
     /**
      * @return \DateTime
      */
-    public function getLastModified();
+    public function getLastModified() : ?\DateTime;
 
     /**
-     * @return array
+     * @return iterable
      */
-    public function getHeaders();
+    public function getHeaders() : iterable;
 
     /**
      * @param  string $name
-     * @return string
+     * @return iterable
      */
-    public function getHeader($name);
+    public function getHeader(string $name): iterable;
 
     /**
      * @return boolean
      */
-    public function isModified();
+    public function isModified() : bool;
 }