Merge branch 'feature/93' into develop

Close #93

CHANGELOG.md

@@ -10,7 +10,9 @@ All notable changes to this project will be documented in this file, in reverse
 
 ### Changed
 
-- Nothing.
+- [#93](https://github.com/zendframework/zend-feed/pull/93) `Writer\Feed`, `Writer\Entry` and `Writer\Deleted` all now accept
+  `DateTimeImmutable` instances as an arguments to methods that previously only
+  accepted `DateTime` or Unix Timestamps, such as `Writer\Feed::setDateModified()`.
 
 ### Deprecated
 

docs/book/writer.md

@@ -213,9 +213,9 @@ Method | Description
 `setFeedLink()` | Set a URI to an XML feed, whether it is to the feed being generated, or an alternate URI pointing to the same feed but in a different format. At a minimum, it is recommended to include a link to the feed being generated so it has an identifiable final URI allowing a client to track its location changes without necessitating constant redirects. The parameters are the feed URI and type (one of "atom", "rss", or "rdf").
 `addAuthors()` | Sets the data for authors. The parameter is an array of array,s where each sub-array may contain the keys "name", "email", and "uri". The "uri" value is only applicable for Atom feeds, since RSS contains no facility to show it. For RSS 2.0, rendering will create two elements: an author element containing the email reference with the name in brackets, and a Dublin Core creator element only containing the name.
 `addAuthor()` | Sets the data for a single author following the same array format as described above for a single sub-array.
-`setDateCreated()` | Sets the date on which this feed was created. Generally only applicable to Atom, where it represents the date the resource described by an Atom 1.0 document was created. The expected parameter may be a UNIX timestamp or a `DateTime` object.
-`setDateModified()` | Sets the date on which this feed was last modified. The expected parameter may be a UNIX timestamp or a `DateTime` object.
-`setLastBuildDate()` | Sets the date on which this feed was last build. The expected parameter may be a UNIX timestamp or a `DateTime` object. This will only be rendered for RSS 2.0 feeds, and is automatically rendered as the current date by default when not explicitly set.
+`setDateCreated()` | Sets the date on which this feed was created. Generally only applicable to Atom, where it represents the date the resource described by an Atom 1.0 document was created. The expected parameter may be a UNIX timestamp or an object implementing `DateTimeInterface` such as `DateTime` or `DateTimeImmutable`.
+`setDateModified()` | Sets the date on which this feed was last modified. The expected parameter may be a UNIX timestamp or an object implementing `DateTimeInterface` such as `DateTime` or `DateTimeImmutable`.
+`setLastBuildDate()` | Sets the date on which this feed was last build. The expected parameter may be a UNIX timestamp or an object implementing `DateTimeInterface` such as `DateTime` or `DateTimeImmutable`. This will only be rendered for RSS 2.0 feeds, and is automatically rendered as the current date by default when not explicitly set.
 `setLanguage()` | Sets the language of the feed. This will be omitted unless set.
 `setGenerator()` | Allows the setting of a generator. The parameter should be an array containing the keys "name", "version", and "uri". If omitted a default generator will be added referencing `Zend\Feed\Writer`, the current zend-version version, and the Framework's URI.
 `setCopyright()` | Sets a copyright notice associated with the feed.
@@ -257,8 +257,8 @@ Method | Description
 `setLink()` | Set a URI to the HTML website containing the same or similar information as this entry (i.e. if the feed is from a blog, it should provide the blog article's URI where the HTML version of the entry can be read).
 `addAuthors()` | Sets the data for authors. The parameter is an array of array,s where each sub-array may contain the keys "name", "email", and "uri". The "uri" value is only applicable for Atom feeds, since RSS contains no facility to show it. For RSS 2.0, rendering will create two elements: an author element containing the email reference with the name in brackets, and a Dublin Core creator element only containing the name.
 `addAuthor()` | Sets the data for a single author following the same format as described above for a single sub-array.
-`setDateCreated()` | Sets the date on which this entry was created. Generally only applicable to Atom where it represents the date the resource described by an Atom 1.0 document was created. The expected parameter may be a UNIX timestamp or a `DateTime` object. If omitted, the date used will be the current date and time.
-`setDateModified()` | Sets the date on which this entry was last modified. The expected parameter may be a UNIX timestamp or a `DateTime` object. If omitted, the date used will be the current date and time.
+`setDateCreated()` | Sets the date on which this entry was created. Generally only applicable to Atom where it represents the date the resource described by an Atom 1.0 document was created. The expected parameter may be a UNIX timestamp or an object implementing `DateTimeInterface` such as `DateTime` or `DateTimeImmutable`. If omitted, the date used will be the current date and time.
+`setDateModified()` | Sets the date on which this entry was last modified. The expected parameter may be a UNIX timestamp or an object implementing `DateTimeInterface` such as `DateTime` or `DateTimeImmutable`. If omitted, the date used will be the current date and time.
 `setCopyright()` | Sets a copyright notice associated with the entry.
 `addCategories()` | Accepts an array of categories for rendering, where each element is itself an array whose possible keys include "term", "label", and "scheme". The "term" is a typically a category name suitable for inclusion in a URI. The "label" may be a human readable category name supporting special characters (it is encoded during rendering) and is a required key. The "scheme" (called the domain in RSS) is optional but must be a valid URI.
 `addCategory()` | Sets the data for a single category following the same format as described above for a single sub-array.

src/Writer/AbstractFeed.php

@@ -10,6 +10,7 @@
 namespace Zend\Feed\Writer;
 
 use DateTime;
+use DateTimeInterface;
 use Zend\Feed\Uri;
 use Zend\Validator;
 
@@ -128,17 +129,19 @@ public function setCopyright($copyright)
     /**
      * Set the feed creation date
      *
-     * @param null|int|DateTime
+     * @param null|int|DateTimeInterface
      * @throws Exception\InvalidArgumentException
      * @return AbstractFeed
      */
     public function setDateCreated($date = null)
     {
         if ($date === null) {
             $date = new DateTime();
-        } elseif (is_int($date)) {
+        }
+        if (is_int($date)) {
             $date = new DateTime('@' . $date);
-        } elseif (! $date instanceof DateTime) {
+        }
+        if (! $date instanceof DateTimeInterface) {
             throw new Exception\InvalidArgumentException('Invalid DateTime object or UNIX Timestamp'
                                                          . ' passed as parameter');
         }
@@ -150,17 +153,19 @@ public function setDateCreated($date = null)
     /**
      * Set the feed modification date
      *
-     * @param null|int|DateTime
+     * @param null|int|DateTimeInterface
      * @throws Exception\InvalidArgumentException
      * @return AbstractFeed
      */
     public function setDateModified($date = null)
     {
         if ($date === null) {
             $date = new DateTime();
-        } elseif (is_int($date)) {
+        }
+        if (is_int($date)) {
             $date = new DateTime('@' . $date);
-        } elseif (! $date instanceof DateTime) {
+        }
+        if (! $date instanceof DateTimeInterface) {
             throw new Exception\InvalidArgumentException('Invalid DateTime object or UNIX Timestamp'
                                                          . ' passed as parameter');
         }
@@ -172,17 +177,19 @@ public function setDateModified($date = null)
     /**
      * Set the feed last-build date. Ignored for Atom 1.0.
      *
-     * @param null|int|DateTime
+     * @param null|int|DateTimeInterface
      * @throws Exception\InvalidArgumentException
      * @return AbstractFeed
      */
     public function setLastBuildDate($date = null)
     {
         if ($date === null) {
             $date = new DateTime();
-        } elseif (is_int($date)) {
+        }
+        if (is_int($date)) {
             $date = new DateTime('@' . $date);
-        } elseif (! $date instanceof DateTime) {
+        }
+        if (! $date instanceof DateTimeInterface) {
             throw new Exception\InvalidArgumentException('Invalid DateTime object or UNIX Timestamp'
                                                          . ' passed as parameter');
         }

src/Writer/Deleted.php

@@ -10,6 +10,7 @@
 namespace Zend\Feed\Writer;
 
 use DateTime;
+use DateTimeInterface;
 use Zend\Feed\Uri;
 
 /**
@@ -132,17 +133,19 @@ public function getReference()
     /**
      * Set when
      *
-     * @param null|string|DateTime $date
+     * @param null|int|DateTimeInterface $date
      * @throws Exception\InvalidArgumentException
      * @return Deleted
      */
     public function setWhen($date = null)
     {
         if ($date === null) {
             $date = new DateTime();
-        } elseif (is_int($date)) {
+        }
+        if (is_int($date)) {
             $date = new DateTime('@' . $date);
-        } elseif (! $date instanceof DateTime) {
+        }
+        if (! $date instanceof DateTimeInterface) {
             throw new Exception\InvalidArgumentException('Invalid DateTime object or UNIX Timestamp'
             . ' passed as parameter');
         }

src/Writer/Entry.php

@@ -10,6 +10,7 @@
 namespace Zend\Feed\Writer;
 
 use DateTime;
+use DateTimeInterface;
 use Zend\Feed\Uri;
 
 /**
@@ -178,17 +179,19 @@ public function setContent($content)
     /**
      * Set the feed creation date
      *
-     * @param null|int|DateTime $date
+     * @param null|int|DateTimeInterface $date
      * @throws Exception\InvalidArgumentException
      * @return Entry
      */
     public function setDateCreated($date = null)
     {
         if ($date === null) {
             $date = new DateTime();
-        } elseif (is_int($date)) {
+        }
+        if (is_int($date)) {
             $date = new DateTime('@' . $date);
-        } elseif (! $date instanceof DateTime) {
+        }
+        if (! $date instanceof DateTimeInterface) {
             throw new Exception\InvalidArgumentException(
                 'Invalid DateTime object or UNIX Timestamp passed as parameter'
             );
@@ -201,17 +204,19 @@ public function setDateCreated($date = null)
     /**
      * Set the feed modification date
      *
-     * @param null|int|DateTime $date
+     * @param null|int|DateTimeInterface $date
      * @throws Exception\InvalidArgumentException
      * @return Entry
      */
     public function setDateModified($date = null)
     {
         if ($date === null) {
             $date = new DateTime();
-        } elseif (is_int($date)) {
+        }
+        if (is_int($date)) {
             $date = new DateTime('@' . $date);
-        } elseif (! $date instanceof DateTime) {
+        }
+        if (! $date instanceof DateTimeInterface) {
             throw new Exception\InvalidArgumentException(
                 'Invalid DateTime object or UNIX Timestamp passed as parameter'
             );

test/Writer/DeletedTest.php

@@ -10,6 +10,7 @@
 namespace ZendTest\Feed\Writer;
 
 use DateTime;
+use DateTimeImmutable;
 use PHPUnit\Framework\TestCase;
 use Zend\Feed\Writer;
 use Zend\Feed\Writer\Exception\InvalidArgumentException;
@@ -89,6 +90,14 @@ public function testSetWhenUsesDateTimeObject()
         $this->assertEquals($myDate, $entry->getWhen());
     }
 
+    public function testSetWhenUsesDateTimeImmutableObject()
+    {
+        $myDate = new DateTimeImmutable('@' . 1234567890);
+        $entry = new Writer\Deleted;
+        $entry->setWhen($myDate);
+        $this->assertEquals($myDate, $entry->getWhen());
+    }
+
     public function testSetWhenThrowsExceptionOnInvalidParameter()
     {
         $entry = new Writer\Deleted;

test/Writer/EntryTest.php

@@ -10,6 +10,7 @@
 namespace ZendTest\Feed\Writer;
 
 use DateTime;
+use DateTimeImmutable;
 use PHPUnit\Framework\TestCase;
 use Zend\Feed\Writer;
 use Zend\Feed\Writer\Exception\ExceptionInterface;
@@ -240,6 +241,14 @@ public function testSetDateCreatedUsesDateTimeObject()
         $this->assertEquals($myDate, $entry->getDateCreated());
     }
 
+    public function testSetDateCreatedUsesDateTimeImmutableObject()
+    {
+        $myDate = new DateTimeImmutable('@' . 1234567890);
+        $entry = new Writer\Entry;
+        $entry->setDateCreated($myDate);
+        $this->assertEquals($myDate, $entry->getDateCreated());
+    }
+
     public function testSetDateModifiedDefaultsToCurrentTime()
     {
         $entry = new Writer\Entry;
@@ -286,6 +295,14 @@ public function testSetDateModifiedUsesDateTimeObject()
         $this->assertEquals($myDate, $entry->getDateModified());
     }
 
+    public function testSetDateModifiedUsesDateTimeImmutableObject()
+    {
+        $myDate = new DateTimeImmutable('@' . 1234567890);
+        $entry = new Writer\Entry;
+        $entry->setDateModified($myDate);
+        $this->assertEquals($myDate, $entry->getDateModified());
+    }
+
     public function testSetDateCreatedThrowsExceptionOnInvalidParameter()
     {
         $entry = new Writer\Entry;

test/Writer/FeedTest.php

@@ -10,6 +10,7 @@
 namespace ZendTest\Feed\Writer;
 
 use DateTime;
+use DateTimeImmutable;
 use PHPUnit\Framework\TestCase;
 use Zend\Feed\Writer;
 use Zend\Feed\Writer\Deleted;
@@ -180,6 +181,14 @@ public function testSetDateCreatedUsesDateTimeObject()
         $this->assertEquals($myDate, $writer->getDateCreated());
     }
 
+    public function testSetDateCreatedUsesDateTimeImmutableObject()
+    {
+        $myDate = new DateTimeImmutable('@' . 1234567890);
+        $writer = new Writer\Feed;
+        $writer->setDateCreated($myDate);
+        $this->assertEquals($myDate, $writer->getDateCreated());
+    }
+
     public function testSetDateModifiedDefaultsToCurrentTime()
     {
         $writer = new Writer\Feed;
@@ -226,6 +235,14 @@ public function testSetDateModifiedUsesDateTimeObject()
         $this->assertEquals($myDate, $writer->getDateModified());
     }
 
+    public function testSetDateModifiedUsesDateTimeImmutableObject()
+    {
+        $myDate = new DateTimeImmutable('@' . 1234567890);
+        $writer = new Writer\Feed;
+        $writer->setDateModified($myDate);
+        $this->assertEquals($myDate, $writer->getDateModified());
+    }
+
     public function testSetDateCreatedThrowsExceptionOnInvalidParameter()
     {
         $writer = new Writer\Feed;
@@ -304,6 +321,14 @@ public function testSetLastBuildDateUsesDateTimeObject()
         $this->assertEquals($myDate, $writer->getLastBuildDate());
     }
 
+    public function testSetLastBuildDateUsesDateTimeImmutableObject()
+    {
+        $myDate = new DateTimeImmutable('@' . 1234567890);
+        $writer = new Writer\Feed;
+        $writer->setLastBuildDate($myDate);
+        $this->assertEquals($myDate, $writer->getLastBuildDate());
+    }
+
     public function testSetLastBuildDateThrowsExceptionOnInvalidParameter()
     {
         $writer = new Writer\Feed;