breaking change to improve message date handling

.scrutinizer.yml

@@ -1,8 +1,2 @@
 filter:
     paths: [src/*]
-
-tools:
-    external_code_coverage: true
-    php_mess_detector: true
-    php_code_sniffer: true
-    php_pdepend: true

README.md

@@ -5,6 +5,8 @@ kodus/mail
 
 [Simple](#objectives) services for sending UTF-8 e-mail.
 
+See [UPGRADING.md](UPGRADING.md) for upgrade instructions.
+
 
 ## Features
 
@@ -116,7 +118,8 @@ To run the integration tests, you will need to set up a local SMTP server for te
 
 On Windows, try [Papercut](https://papercut.codeplex.com/) or [SMTP4Dev](http://smtp4dev.codeplex.com/).
 
-On Linux, you will likely just have to set up an actual, local SMTP daemon. (Have fun with that!)
+On Linux, you will likely just have to set up an actual, local SMTP daemon. (see `.travis.yml` for an
+example of installing and starting `smtp-sink` which comes with `postfix`.)
 
 You may need to copy `integration.suite.dist.yml` to `integration.suite.yml` to customize the
 SMTP host-name, port-number, etc.

UPGRADING.md

@@ -0,0 +1,8 @@
+UPGRADING
+=========
+
+## 0.1.x to 0.2.x
+
+`Message::getDate()` now returns `DateTimeInterface` - it previously returned a UNIX (integer) timestamp.
+
+`Message::setDate()` still accepts UNIX timestamps and strings, and now also `DateTime` and `DateTimeImmutable`.

src/MIMEWriter.php

@@ -35,7 +35,7 @@ public function writeMessage(Message $message)
      */
     public function writeMessageHeaders(Message $message)
     {
-        $this->writeHeader("Date", date("r", $message->getDate()));
+        $this->writeHeader("Date", $message->getDate()->format("r"));
 
         $this->writeAddressHeader("To", $message->getTo());
         $this->writeAddressHeader("From", $message->getFrom());

src/Message.php

@@ -2,6 +2,8 @@
 
 namespace Kodus\Mail;
 
+use DateTimeImmutable;
+use DateTimeInterface;
 use InvalidArgumentException;
 
 /**
@@ -45,7 +47,7 @@ class Message
     private $subject;
 
     /**
-     * @var int timestamp
+     * @var DateTimeInterface
      */
     private $date;
 
@@ -224,7 +226,7 @@ public function getBCC()
      *
      * Some systems may choose to include the text of the "BCC" field only in the author's copy,
      * while others may also include it in the text sent to all those indicated in the "BCC" list.
-     * 
+     *
      * @param Address|Address[] $address
      */
     public function setBCC($address)
@@ -281,21 +283,30 @@ public function setSubject($subject)
     }
 
     /**
-     * @return int timestamp
+     * @return DateTimeInterface
      */
     public function getDate()
     {
         return $this->date;
     }
 
     /**
-     * @param int|string $date integer timestamp, or a string compatible with the strtotime() function
+     * @param int|string|DateTimeInterface $date DateTime in Sender's timezone (or a UNIX integer timestamp;
+     *                                           or a string that is compatible with the strtotime() function)
      */
     public function setDate($date)
     {
-        $this->date = is_int($date)
-            ? $date
-            : strtotime($date);
+        if ($date instanceof DateTimeInterface) {
+            $this->date = $date;
+        } elseif (is_int($date)) {
+            $this->date = DateTimeImmutable::createFromFormat("U", $date)
+                ->setTimezone(timezone_open(date_default_timezone_get()));
+        } elseif (is_string($date)) {
+            $this->date = DateTimeImmutable::createFromFormat("U", strtotime($date))
+                ->setTimezone(timezone_open(date_default_timezone_get()));
+        } else {
+            throw new InvalidArgumentException("invalid date given: " . var_export($date, true));
+        }
     }
 
     /**

tests/_support/Helper/Integration.php

@@ -8,6 +8,11 @@
 
 class Integration extends \Codeception\Module
 {
+    public function _before()
+    {
+        date_default_timezone_set("Europe/Copenhagen");
+    }
+
     /**
      * @return \Kodus\Mail\SMTP\Connector\SocketConnector
      */

tests/_support/Helper/Unit.php

@@ -6,5 +6,8 @@
 
 class Unit extends \Codeception\Module
 {
-
+    public function _before()
+    {
+        date_default_timezone_set("Europe/Copenhagen");
+    }
 }

tests/unit/MessageCest.php

@@ -2,6 +2,8 @@
 
 namespace Kodus\Mail\Test\Unit;
 
+use DateTime;
+use DateTimeZone;
 use InvalidArgumentException;
 use Kodus\Mail\Address;
 use Kodus\Mail\Header;
@@ -63,4 +65,52 @@ function () use ($message) {
             }
         );
     }
+
+    public function setDate(UnitTester $I)
+    {
+        $message = new Message(
+            new Address("[email protected]"),
+            new Address("[email protected]"),
+            "Hello, Bob",
+            null
+        );
+
+        // try setting a Date from a string in two different system timezones:
+
+        date_default_timezone_set("Europe/Copenhagen");
+
+        $message->setDate("Thu, 15 Sep 2016 17:20:54");
+
+        $I->assertSame("Thu, 15 Sep 2016 17:20:54 +0200", $message->getDate()->format("r"));
+
+        date_default_timezone_set("UTC");
+
+        $message->setDate("Thu, 15 Sep 2016 17:20:54");
+
+        $I->assertSame("Thu, 15 Sep 2016 17:20:54 +0000", $message->getDate()->format("r"));
+
+        // try setting a Date from an UNIX timestamp in two different system timezones:
+
+        date_default_timezone_set("Europe/Copenhagen");
+
+        $message->setDate(1473952854);
+
+        $I->assertSame("Thu, 15 Sep 2016 17:20:54 +0200", $message->getDate()->format("r"));
+
+        date_default_timezone_set("UTC");
+
+        $message->setDate(1473952854);
+
+        $I->assertSame("Thu, 15 Sep 2016 15:20:54 +0000", $message->getDate()->format("r"));
+
+        // try setting a Date from a DateTime instance:
+
+        $date = new DateTime("@" . strtotime("Thu, 15 Sep 2016 17:20:54 +0200"));
+
+        $date->setTimezone(new DateTimeZone("Europe/Copenhagen"));
+
+        $message->setDate($date);
+
+        $I->assertSame("Thu, 15 Sep 2016 17:20:54 +0200", $message->getDate()->format("r"));
+    }
 }