From 3a2699ca2542c9d0863bab84462bcd1923b28aa2 Mon Sep 17 00:00:00 2001 From: Zaahid Bateson Date: Sun, 12 Aug 2018 22:54:19 -0500 Subject: [PATCH] Update and fix docblocks --- src/Container.php | 9 ++-- src/Header/Consumer/ConsumerService.php | 1 + src/Header/Consumer/ParameterConsumer.php | 3 +- src/Header/HeaderContainer.php | 2 + src/MailMimeParser.php | 3 ++ src/Message.php | 4 ++ src/Message/Helper/AbstractHelper.php | 2 + src/Message/Helper/GenericHelper.php | 2 + src/Message/Helper/MessageHelperService.php | 4 +- src/Message/Helper/MultipartHelper.php | 2 + src/Message/Helper/PrivacyHelper.php | 2 + src/Message/MessageFactory.php | 2 + src/Message/MessageParser.php | 1 - .../Part/Factory/MessagePartFactory.php | 2 +- src/Message/Part/MessagePart.php | 3 ++ src/Message/Part/MimePart.php | 10 ++-- src/Message/Part/ParentHeaderPart.php | 47 +++++++++++++++---- src/Message/Part/ParentPart.php | 6 ++- src/Message/Part/UUEncodedPart.php | 2 + src/Stream/HeaderStream.php | 2 + src/Stream/MessagePartStream.php | 11 +++-- 21 files changed, 95 insertions(+), 25 deletions(-) diff --git a/src/Container.php b/src/Container.php index 8564b9fd..713101f6 100644 --- a/src/Container.php +++ b/src/Container.php @@ -28,22 +28,23 @@ class Container { /** - * @var PartBuilderFactory + * @var PartBuilderFactory The PartBuilderFactory instance */ protected $partBuilderFactory; /** - * @var PartFactoryService + * @var PartFactoryService The PartFactoryService instance */ protected $partFactoryService; /** - * @var PartFilterFactory + * @var PartFilterFactory The PartFilterFactory instance */ protected $partFilterFactory; /** - * @var PartStreamFilterManagerFactory + * @var PartStreamFilterManagerFactory The PartStreamFilterManagerFactory + * instance */ protected $partStreamFilterManagerFactory; diff --git a/src/Header/Consumer/ConsumerService.php b/src/Header/Consumer/ConsumerService.php index 51f5bc8b..6d2ceda7 100644 --- a/src/Header/Consumer/ConsumerService.php +++ b/src/Header/Consumer/ConsumerService.php @@ -32,6 +32,7 @@ class ConsumerService * Sets up the HeaderPartFactory member variable. * * @param HeaderPartFactory $partFactory + * @param MimeLiteralPartFactory $mimeLiteralPartFactory */ public function __construct(HeaderPartFactory $partFactory, MimeLiteralPartFactory $mimeLiteralPartFactory) { diff --git a/src/Header/Consumer/ParameterConsumer.php b/src/Header/Consumer/ParameterConsumer.php index 4b859644..06af3ab3 100644 --- a/src/Header/Consumer/ParameterConsumer.php +++ b/src/Header/Consumer/ParameterConsumer.php @@ -114,7 +114,8 @@ private function getPartFor($strName, $strValue, ArrayObject $splitParts) * Returns true if the token was processed, and false otherwise. * * @param string $tokenValue - * @param array $combined + * @param ArrayObject $combined + * @param ArrayObject $splitParts * @param string $strName * @param string $strCat * @return boolean diff --git a/src/Header/HeaderContainer.php b/src/Header/HeaderContainer.php index bdc11099..0a664859 100644 --- a/src/Header/HeaderContainer.php +++ b/src/Header/HeaderContainer.php @@ -52,6 +52,8 @@ class HeaderContainer implements IteratorAggregate private $nextIndex = 0; /** + * Constructor + * * @param HeaderFactory $headerFactory */ public function __construct(HeaderFactory $headerFactory) diff --git a/src/MailMimeParser.php b/src/MailMimeParser.php index 47445e9b..2a43cdc6 100644 --- a/src/MailMimeParser.php +++ b/src/MailMimeParser.php @@ -34,6 +34,9 @@ class MailMimeParser /** * Sets up the parser. + * + * @param Container $di pass a Container object to use it for + * initialization. */ public function __construct(Container $di = null) { diff --git a/src/Message.php b/src/Message.php index 41475d73..eb8bc1df 100644 --- a/src/Message.php +++ b/src/Message.php @@ -33,6 +33,8 @@ class Message extends MimePart protected $messageHelperService; /** + * Constructor + * * @param PartStreamFilterManager $partStreamFilterManager * @param StreamFactory $streamFactory * @param PartFilterFactory $partFilterFactory @@ -343,6 +345,7 @@ public function setHtmlPart($resource, $charset = 'UTF-8') * Removes the text/plain part of the message at the passed index if one * exists. Returns true on success. * + * @param int $index * @return bool true on success */ public function removeTextPart($index = 0) @@ -375,6 +378,7 @@ public function removeAllTextParts($keepOtherPartsAsAttachments = true) * Removes the html part of the message if one exists. Returns true on * success. * + * @param int $index * @return bool true on success */ public function removeHtmlPart($index = 0) diff --git a/src/Message/Helper/AbstractHelper.php b/src/Message/Helper/AbstractHelper.php index d047478f..2af24b5a 100644 --- a/src/Message/Helper/AbstractHelper.php +++ b/src/Message/Helper/AbstractHelper.php @@ -33,6 +33,8 @@ abstract class AbstractHelper protected $partBuilderFactory; /** + * Constructor + * * @param MimePartFactory $mimePartFactory * @param UUEncodedPartFactory $uuEncodedPartFactory * @param PartBuilderFactory $partBuilderFactory diff --git a/src/Message/Helper/GenericHelper.php b/src/Message/Helper/GenericHelper.php index e0786de6..98d3e537 100644 --- a/src/Message/Helper/GenericHelper.php +++ b/src/Message/Helper/GenericHelper.php @@ -79,6 +79,7 @@ public function removeContentHeadersAndContent(ParentHeaderPart $part) * * @param ParentHeaderPart $from * @param ParentHeaderPart $to + * @param bool $move */ public function copyContentHeadersAndContent(ParentHeaderPart $from, ParentHeaderPart $to, $move = false) { @@ -141,6 +142,7 @@ public function movePartContentAndChildren(ParentHeaderPart $from, ParentHeaderP * replaced, and instead $replacement's type headers are copied to $message, * and any children below $replacement are added directly below $message. * + * @param Message $message * @param ParentHeaderPart $part * @param ParentHeaderPart $replacement */ diff --git a/src/Message/Helper/MessageHelperService.php b/src/Message/Helper/MessageHelperService.php index 6623afdd..98bccc3d 100644 --- a/src/Message/Helper/MessageHelperService.php +++ b/src/Message/Helper/MessageHelperService.php @@ -17,7 +17,7 @@ class MessageHelperService { /** - * @var PartBuilderFactory + * @var PartBuilderFactory the PartBuilderFactory */ private $partBuilderFactory; @@ -42,6 +42,8 @@ class MessageHelperService private $partFactoryService; /** + * Constructor + * * @param PartBuilderFactory $partBuilderFactory */ public function __construct(PartBuilderFactory $partBuilderFactory) diff --git a/src/Message/Helper/MultipartHelper.php b/src/Message/Helper/MultipartHelper.php index fec1e6a1..be925ad2 100644 --- a/src/Message/Helper/MultipartHelper.php +++ b/src/Message/Helper/MultipartHelper.php @@ -30,6 +30,8 @@ class MultipartHelper extends AbstractHelper private $genericHelper; /** + * Constructor + * * @param MimePartFactory $mimePartFactory * @param UUEncodedPartFactory $uuEncodedPartFactory * @param PartBuilderFactory $partBuilderFactory diff --git a/src/Message/Helper/PrivacyHelper.php b/src/Message/Helper/PrivacyHelper.php index 2d6dd147..4a7498f0 100644 --- a/src/Message/Helper/PrivacyHelper.php +++ b/src/Message/Helper/PrivacyHelper.php @@ -31,6 +31,8 @@ class PrivacyHelper extends AbstractHelper private $multipartHelper; /** + * Constructor + * * @param MimePartFactory $mimePartFactory * @param UUEncodedPartFactory $uuEncodedPartFactory * @param PartBuilderFactory $partBuilderFactory diff --git a/src/Message/MessageFactory.php b/src/Message/MessageFactory.php index 34a876e4..62419cff 100644 --- a/src/Message/MessageFactory.php +++ b/src/Message/MessageFactory.php @@ -28,6 +28,8 @@ class MessageFactory extends MimePartFactory protected $messageHelperService; /** + * Constructor + * * @param StreamFactory $sdf * @param PartStreamFilterManagerFactory $psf * @param PartFilterFactory $pf diff --git a/src/Message/MessageParser.php b/src/Message/MessageParser.php index 3922454e..50f086ea 100644 --- a/src/Message/MessageParser.php +++ b/src/Message/MessageParser.php @@ -203,7 +203,6 @@ private function readPartContent($handle, PartBuilder $partBuilder) * * @param resource $handle * @param PartBuilder $partBuilder - * @param boolean $isMessage */ protected function readPart($handle, PartBuilder $partBuilder) { diff --git a/src/Message/Part/Factory/MessagePartFactory.php b/src/Message/Part/Factory/MessagePartFactory.php index cee55b48..58aeccd3 100644 --- a/src/Message/Part/Factory/MessagePartFactory.php +++ b/src/Message/Part/Factory/MessagePartFactory.php @@ -32,7 +32,7 @@ abstract class MessagePartFactory protected $streamFactory; /** - * @static MessagePartFactory[] cached instances of MessagePartFactory + * @var MessagePartFactory[] cached instances of MessagePartFactory * sub-classes */ private static $instances = null; diff --git a/src/Message/Part/MessagePart.php b/src/Message/Part/MessagePart.php index c72d6338..816738f7 100644 --- a/src/Message/Part/MessagePart.php +++ b/src/Message/Part/MessagePart.php @@ -62,6 +62,8 @@ abstract class MessagePart protected $ignoreTransferEncoding; /** + * Constructor + * * @param PartStreamFilterManager $partStreamFilterManager * @param StreamFactory $streamFactory * @param StreamInterface $stream @@ -309,6 +311,7 @@ public function getContentStream($charset = MailMimeParser::DEFAULT_CHARSET) * The returned string is encoded to the passed $charset character encoding, * defaulting to UTF-8. * + * @param string $charset * @return string */ public function getContent($charset = MailMimeParser::DEFAULT_CHARSET) diff --git a/src/Message/Part/MimePart.php b/src/Message/Part/MimePart.php index 1aef7f87..6cfe887c 100644 --- a/src/Message/Part/MimePart.php +++ b/src/Message/Part/MimePart.php @@ -76,7 +76,8 @@ public function isTextPart() * * Parses the Content-Type header, defaults to returning text/plain if not * defined. - * + * + * @param string $default pass to override the returned value when not set * @return string */ public function getContentType($default = 'text/plain') @@ -106,7 +107,9 @@ public function getCharset() /** * Returns the content's disposition, defaulting to 'inline' if not set. - * + * + * @param string $default pass to override the default returned disposition + * when not set. * @return string */ public function getContentDisposition($default = 'inline') @@ -117,7 +120,8 @@ public function getContentDisposition($default = 'inline') /** * Returns the content-transfer-encoding used for this part, defaulting to * '7bit' if not set. - * + * + * @param string $default pass to override the default when not set. * @return string */ public function getContentTransferEncoding($default = '7bit') diff --git a/src/Message/Part/ParentHeaderPart.php b/src/Message/Part/ParentHeaderPart.php index 4e3824d1..31c15786 100644 --- a/src/Message/Part/ParentHeaderPart.php +++ b/src/Message/Part/ParentHeaderPart.php @@ -20,11 +20,13 @@ abstract class ParentHeaderPart extends ParentPart { /** - * @var HeaderContainer + * @var HeaderContainer Contains headers for this part. */ protected $headerContainer; /** + * Constructor + * * @param PartStreamFilterManager $partStreamFilterManager * @param StreamFactory $streamFactory * @param PartFilterFactory $partFilterFactory @@ -52,11 +54,14 @@ public function __construct( } /** - * Returns the AbstractHeader object for the header with the given $name + * Returns the AbstractHeader object for the header with the given $name. + * If the optional $offset is passed, and multiple headers exist with the + * same name, the one at the passed offset is returned. * * Note that mime headers aren't case sensitive. * * @param string $name + * @param int $offset * @return \ZBateson\MailMimeParser\Header\AbstractHeader */ public function getHeader($name, $offset = 0) @@ -142,13 +147,34 @@ public function getHeaderParameter($header, $param, $defaultValue = null) } /** - * Adds a header with the given $name and $value. - * - * Creates a new \ZBateson\MailMimeParser\Header\AbstractHeader object and - * registers it as a header. + * Adds a header with the given $name and $value. An optional $offset may + * be passed, which will overwrite a header if one exists with the given + * name and offset. Otherwise a new header is added. The passed $offset may + * be ignored in that case if it doesn't represent the next insert position + * for the header with the passed name... instead it would be 'pushed' on at + * the next position. + * + * ```php + * $part = $myParentHeaderPart; + * $part->setRawHeader('New-Header', 'value'); + * echo $part->getHeaderValue('New-Header'); // 'value' + * + * $part->setRawHeader('New-Header', 'second', 4); + * echo is_null($part->getHeader('New-Header', 4)); // '1' (true) + * echo $part->getHeader('New-Header', 1) + * ->getValue(); // 'second' + * ``` + * + * A new \ZBateson\MailMimeParser\Header\AbstractHeader object is created + * from the passed value. No processing on the passed string is performed, + * and so the passed name and value must be formatted correctly according to + * related RFCs. In particular, be careful to encode non-ascii data, to + * keep lines under 998 characters in length, and to follow any special + * formatting required for the type of header. * * @param string $name * @param string $value + * @param int $offset */ public function setRawHeader($name, $value, $offset = 0) { @@ -158,6 +184,10 @@ public function setRawHeader($name, $value, $offset = 0) /** * Adds a header with the given $name and $value. + * + * Note: If a header with the passed name already exists, a new header is + * created with the same name. This should only be used when that is + * intentional - in most cases setRawHeader should be called. * * Creates a new \ZBateson\MailMimeParser\Header\AbstractHeader object and * registers it as a header. @@ -172,7 +202,7 @@ public function addRawHeader($name, $value) } /** - * Removes the header with the given name + * Removes all headers from this part with the passed name. * * @param string $name */ @@ -183,7 +213,8 @@ public function removeHeader($name) } /** - * Removes the header with the given name + * Removes a single header with the passed name (in cases where more than + * one may exist, and others should be preserved). * * @param string $name */ diff --git a/src/Message/Part/ParentPart.php b/src/Message/Part/ParentPart.php index 90568b83..a3575663 100644 --- a/src/Message/Part/ParentPart.php +++ b/src/Message/Part/ParentPart.php @@ -29,6 +29,8 @@ abstract class ParentPart extends MessagePart protected $children = []; /** + * Constructor + * * @param PartStreamFilterManager $partStreamFilterManager * @param StreamFactory $streamFactory * @param PartFilterFactory $partFilterFactory @@ -181,9 +183,11 @@ public function getChildCount(PartFilter $filter = null) } /** - * Returns the part associated with the passed mime type if it exists. + * Returns the part associated with the passed mime type, at the passed + * index, if it exists. * * @param string $mimeType + * @param int $index * @return MessagePart|null */ public function getPartByMimeType($mimeType, $index = 0) diff --git a/src/Message/Part/UUEncodedPart.php b/src/Message/Part/UUEncodedPart.php index 054268a3..7d1c7fe8 100644 --- a/src/Message/Part/UUEncodedPart.php +++ b/src/Message/Part/UUEncodedPart.php @@ -37,6 +37,8 @@ class UUEncodedPart extends NonMimePart protected $filename = null; /** + * Constructor + * * @param PartStreamFilterManager $partStreamFilterManager * @param StreamFactory $streamFactory * @param PartBuilder $partBuilder diff --git a/src/Stream/HeaderStream.php b/src/Stream/HeaderStream.php index 540c65eb..082dca4f 100644 --- a/src/Stream/HeaderStream.php +++ b/src/Stream/HeaderStream.php @@ -33,6 +33,8 @@ class HeaderStream implements StreamInterface protected $part; /** + * Constructor + * * @param MessagePart $part */ public function __construct(MessagePart $part) diff --git a/src/Stream/MessagePartStream.php b/src/Stream/MessagePartStream.php index d61c907f..e8965e1b 100644 --- a/src/Stream/MessagePartStream.php +++ b/src/Stream/MessagePartStream.php @@ -12,7 +12,6 @@ use Psr\Http\Message\StreamInterface; use ZBateson\MailMimeParser\MailMimeParser; use ZBateson\MailMimeParser\Message\Part\MessagePart; -use ZBateson\MailMimeParser\Message\Part\MimePart; use ZBateson\MailMimeParser\Message\Part\ParentHeaderPart; use ZBateson\MailMimeParser\Stream\StreamFactory; @@ -36,6 +35,8 @@ class MessagePartStream implements StreamInterface protected $part; /** + * Constructor + * * @param StreamFactory $sdf * @param MessagePart $part */ @@ -48,9 +49,10 @@ public function __construct(StreamFactory $sdf, MessagePart $part) /** * Attaches and returns a CharsetStream decorator to the passed $stream. * - * If the current attached $part doesn't specify a $charset, $stream is + * If the current attached MessagePart doesn't specify a charset, $stream is * returned as-is. * + * @param StreamInterface $stream * @return StreamInterface */ private function getCharsetDecoratorForStream(StreamInterface $stream) @@ -107,7 +109,6 @@ private function getTransferEncodingDecoratorForStream(StreamInterface $stream) * Writes out the content portion of the attached mime part to the passed * $stream. * - * @param MessagePart $part * @param StreamInterface $stream */ private function writePartContentTo(StreamInterface $stream) @@ -126,8 +127,8 @@ private function writePartContentTo(StreamInterface $stream) * Creates an array of streams based on the attached part's mime boundary * and child streams. * - * ParentHeaderPart $part passed in because $this->part is declared as - * MessagePart + * @param ParentHeaderPart $part passed in because $this->part is declared + * as MessagePart * @return StreamInterface[] */ protected function getBoundaryAndChildStreams(ParentHeaderPart $part)