require PHP 7.1 and upgrade codebase with static type-hints

kodus · Aug 15, 2018 · bbaff5b · bbaff5b
1 parent 1f33848
commit bbaff5b
Show file tree

Hide file tree

Showing 28 changed files with 155 additions and 176 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -1,9 +1,9 @@
 language: php
 
 php:
-  - 7.0
   - 7.1
   - 7.2
+  - 7.3
 
 before_script:
   - 'composer update --prefer-source'

diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 kodus/mail
 ==========
 
-[![PHP Version](https://img.shields.io/badge/php-7.0%2B-blue.svg)](https://packagist.org/packages/kodus/mail)
+[![PHP Version](https://img.shields.io/badge/php-7.1%2B-blue.svg)](https://packagist.org/packages/kodus/mail)
 [![Build Status](https://travis-ci.org/kodus/mail.svg?branch=master)](https://travis-ci.org/kodus/mail)
 [![Code Coverage](https://scrutinizer-ci.com/g/kodus/mail/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/kodus/mail/?branch=master)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/kodus/mail/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/kodus/mail/?branch=master)

diff --git a/UPGRADING.md b/UPGRADING.md
@@ -3,7 +3,9 @@ UPGRADING
 
 ## 1.0.0
 
-There are no breaking changes from 0.2.x, but this release requires PHP 7.0 or later.
+This release requires PHP 7.1 or later - APIs have not changed since 0.2.x, but static type-hints
+have been added, so you may need to add type-hints to custom implementations of any interfaces defined
+by this package.
 
 ## 0.1.x to 0.2.x
 

diff --git a/composer.json b/composer.json
@@ -12,7 +12,7 @@
     "minimum-stability": "dev",
     "prefer-stable": true,
     "require": {
-        "php": ">= 7.0",
+        "php": ">= 7.1",
         "psr/log": "^1"
     },
     "require-dev": {

diff --git a/src/Address.php b/src/Address.php
@@ -22,12 +22,12 @@ class Address
 
     /**
      * @param string      $email valid e-mail address
-     * @param string|null $name  display name
+     * @param string|null $name  display name (optional)
      *
      * @throws InvalidArgumentException for invalid e-mail address
      * @throws RuntimeException on attempted CRLF name injection
      */
-    public function __construct($email, $name = null)
+    public function __construct(string $email, ?string $name = null)
     {
         if (! self::isValidEmail($email)) {
             throw new InvalidArgumentException("invalid e-mail address");
@@ -43,28 +43,17 @@ public function __construct($email, $name = null)
         $this->name = $name;
     }
 
-    /**
-     * @param string $email
-     *
-     * @return bool
-     */
-    public static function isValidEmail($email)
+    public static function isValidEmail(string $email): bool
     {
         return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
     }
 
-    /**
-     * @return string
-     */
-    public function getEmail()
+    public function getEmail(): string
     {
         return $this->email;
     }
 
-    /**
-     * @return string|null
-     */
-    public function getName()
+    public function getName(): ?string
     {
         return $this->name;
     }

diff --git a/src/Attachment.php b/src/Attachment.php
@@ -29,7 +29,7 @@ class Attachment
      * @param string          $filename  logical filename
      * @param string          $mime_type MIME-type
      */
-    public function __construct($content, $filename, $mime_type = self::DEFAULT_MIME_TYPE)
+    public function __construct($content, string $filename, string $mime_type = self::DEFAULT_MIME_TYPE)
     {
         $this->content = $content;
         $this->filename = $filename;
@@ -45,7 +45,7 @@ public function __construct($content, $filename, $mime_type = self::DEFAULT_MIME
      *
      * @return self
      */
-    public static function fromFile($path, $filename = null, $mime_type = self::DEFAULT_MIME_TYPE)
+    public static function fromFile(string $path, ?string $filename = null, string $mime_type = self::DEFAULT_MIME_TYPE): self
     {
         return new self(
             fopen($path, "r"),
@@ -62,18 +62,12 @@ public function getContent()
         return $this->content;
     }
 
-    /**
-     * @return string
-     */
-    public function getFilename()
+    public function getFilename(): string
     {
         return $this->filename;
     }
 
-    /**
-     * @return string
-     */
-    public function getMIMEType()
+    public function getMIMEType(): string
     {
         return $this->mime_type;
     }

diff --git a/src/Header.php b/src/Header.php
@@ -14,28 +14,18 @@ class Header
      */
     private $value;
 
-    /**
-     * @param string $name
-     * @param string $value
-     */
-    public function __construct($name, $value)
+    public function __construct(string $name, string $value)
     {
         $this->name = $name;
         $this->value = $value;
     }
 
-    /**
-     * @return string
-     */
-    public function getName()
+    public function getName(): string
     {
         return $this->name;
     }
 
-    /**
-     * @return string
-     */
-    public function getValue()
+    public function getValue(): string
     {
         return $this->value;
     }

diff --git a/src/InlineAttachment.php b/src/InlineAttachment.php
@@ -37,15 +37,15 @@ public function __construct(Attachment $attachment)
     /**
      * @return Attachment
      */
-    public function getAttachment()
+    public function getAttachment(): Attachment
     {
         return $this->attachment;
     }
 
     /**
      * @return string
      */
-    public function getContentID()
+    public function getContentID(): string
     {
         return $this->content_id;
     }

diff --git a/src/MIMEWriter.php b/src/MIMEWriter.php
@@ -4,7 +4,7 @@
 
 class MIMEWriter extends Writer
 {
-    public function writeMessage(Message $message)
+    public function writeMessage(Message $message): void
     {
         $this->writeMessageHeaders($message);
 
@@ -30,10 +30,7 @@ public function writeMessage(Message $message)
         }
     }
 
-    /**
-     * @param Message $message
-     */
-    public function writeMessageHeaders(Message $message)
+    public function writeMessageHeaders(Message $message): void
     {
         $this->writeHeader("Date", $message->getDate()->format("r"));
 
@@ -78,7 +75,7 @@ public function writeMessageHeaders(Message $message)
      *
      * @param Message $message
      */
-    public function writeMessageWithAttachments(Message $message)
+    public function writeMessageWithAttachments(Message $message): void
     {
         if (empty($message->getAttachments())) {
             $this->writeMessageBody($message);
@@ -111,7 +108,7 @@ public function writeMessageWithAttachments(Message $message)
      *
      * @param Message $message
      */
-    public function writeMessageBody(Message $message)
+    public function writeMessageBody(Message $message): void
     {
         $text = $message->getText();
         $html = $message->getHTML();
@@ -143,7 +140,7 @@ public function writeMessageBody(Message $message)
      *
      * @param string $content
      */
-    public function writeTextPart($content)
+    public function writeTextPart(string $content): void
     {
         $this->writeContentTypeHeader("text/plain; charset=UTF-8");
         $this->writeQuotedPrintableEncodingHeader();
@@ -157,7 +154,7 @@ public function writeTextPart($content)
      *
      * @param string $content
      */
-    public function writeHTMLPart($content)
+    public function writeHTMLPart(string $content): void
     {
         $this->writeContentTypeHeader("text/html; charset=UTF-8");
         $this->writeQuotedPrintableEncodingHeader();
@@ -172,7 +169,7 @@ public function writeHTMLPart($content)
      * @param Attachment  $attachment
      * @param string|null Content ID (for inline Attachments)
      */
-    public function writeAttachmentPart(Attachment $attachment, $content_id = null)
+    public function writeAttachmentPart(Attachment $attachment, ?string $content_id = null): void
     {
         $filename = $attachment->getFilename();
 
@@ -195,15 +192,15 @@ public function writeAttachmentPart(Attachment $attachment, $content_id = null)
     /**
      * @param string $boundary
      */
-    public function writeMultipartBoundary($boundary)
+    public function writeMultipartBoundary(string $boundary): void
     {
         $this->writeLine("--{$boundary}");
     }
 
     /**
      * @param string $boundary
      */
-    public function writeMultipartBoundaryEnd($boundary)
+    public function writeMultipartBoundaryEnd(string $boundary): void
     {
         $this->writeLine("--{$boundary}--");
     }
@@ -212,7 +209,7 @@ public function writeMultipartBoundaryEnd($boundary)
      * @param string $name
      * @param string $value
      */
-    public function writeHeader($name, $value)
+    public function writeHeader(string $name, string $value): void
     {
         $value = $this->escapeHeaderValue($value);
 
@@ -223,7 +220,7 @@ public function writeHeader($name, $value)
      * @param string    $name      header name
      * @param Address[] $addresses list of Address objects
      */
-    public function writeAddressHeader($name, $addresses)
+    public function writeAddressHeader(string $name, array $addresses): void
     {
         if (count($addresses)) {
             $this->writeHeader(
@@ -249,55 +246,55 @@ function (Address $address) {
     /**
      * @param string $type
      */
-    public function writeContentTypeHeader($type)
+    public function writeContentTypeHeader(string $type): void
     {
         $this->writeHeader("Content-Type", $type);
     }
 
     /**
      * @param string $boundary
      */
-    public function writeMixedContentTypeHeader($boundary)
+    public function writeMixedContentTypeHeader(string $boundary): void
     {
         $this->writeContentTypeHeader("multipart/mixed; boundary=\"{$boundary}\"");
     }
 
     /**
      * @param string $boundary
      */
-    public function writeAlternativeContentTypeHeader($boundary)
+    public function writeAlternativeContentTypeHeader(string $boundary): void
     {
         $this->writeContentTypeHeader("multipart/alternative; boundary=\"{$boundary}\"");
     }
 
     /**
      * @param string $boundary
      */
-    public function writeRelatedContentTypeHeader($boundary)
+    public function writeRelatedContentTypeHeader(string $boundary): void
     {
         $this->writeContentTypeHeader("multipart/related; boundary=\"{$boundary}\"");
     }
 
     /**
      * Writes the "Content-Transfer-Encoding" header with value "quoted-printable"
      */
-    public function writeQuotedPrintableEncodingHeader()
+    public function writeQuotedPrintableEncodingHeader(): void
     {
         $this->writeContentEncodingHeader("quoted-printable");
     }
 
     /**
      * Writes the "Content-Transfer-Encoding" header with value "base64"
      */
-    public function writeBase64EncodingHeader()
+    public function writeBase64EncodingHeader(): void
     {
         $this->writeContentEncodingHeader("base64");
     }
 
     /**
      * @param string $encoding encoding (e.g. "quoted-printable", "base64" or "8bit")
      */
-    protected function writeContentEncodingHeader($encoding)
+    protected function writeContentEncodingHeader($encoding): void
     {
         $this->writeHeader("Content-Transfer-Encoding", $encoding);
     }
@@ -309,7 +306,7 @@ protected function writeContentEncodingHeader($encoding)
      *
      * @return string
      */
-    protected function createMultipartBoundaryName($prefix)
+    protected function createMultipartBoundaryName(string $prefix): string
     {
         static $boundary_index = 1;
 
@@ -323,7 +320,7 @@ protected function createMultipartBoundaryName($prefix)
      *
      * @return string
      */
-    protected function escapeHeaderValue($value)
+    protected function escapeHeaderValue(string $value): string
     {
         return preg_match('/[\x80-\xFF]/', $value) === 1
             ? "=?UTF-8?Q?" . quoted_printable_encode($value) . "?="
@@ -337,7 +334,7 @@ protected function escapeHeaderValue($value)
      *
      * @return string
      */
-    protected function adjustLineBreaks($value)
+    protected function adjustLineBreaks(string $value): string
     {
         return preg_replace('/(?>\r\n|\n|\r)/u', "\r\n", $value);
     }

diff --git a/src/MailService.php b/src/MailService.php
@@ -8,9 +8,14 @@
 interface MailService
 {
     /**
+     * Send the message, by whatever means is defined by the implementation.
+     *
+     * Success is assumed (hence, there is no return status) but the implementation or
+     * underlying transport could throw runtime-exceptions, which you may wish to handle.
+     *
      * @param Message $message
      *
      * @return void
      */
-    public function send(Message $message);
+    public function send(Message $message): void;
 }