AbstractConsumerService::getTokenParts() - Code Metrics - zbateson/mail-mime-parser - Measure and Improve Code Quality continuously with Scrutinizer

AbstractConsumerService::getTokenParts() A
last analyzed 2025-09-03 23:45 UTC

↳ Parent: AbstractConsumerService

Complexity

Conditions	5
Paths	3

Size

Total Lines	8
Code Lines	5

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	6
CRAP Score	5

Importance

Changes

Metric	Value
eloc	5
c	0
b	0
f	0
dl	0
loc	8
ccs	6
cts	6
cp	1
rs	9.6111
cc	5
nc	3
nop	1
crap	5

<?php
/**
 * This file is part of the ZBateson\MailMimeParser project.
 *
 * @license http://opensource.org/licenses/bsd-license.php BSD
 */

namespace ZBateson\MailMimeParser\Header\Consumer;

use ArrayIterator;
use Iterator;
use NoRewindIterator;
use Psr\Log\LoggerInterface;
use ZBateson\MailMimeParser\Header\IHeaderPart;
use ZBateson\MailMimeParser\Header\Part\HeaderPartFactory;
use ZBateson\MailMimeParser\Header\Part\MimeToken;

/**
 * Abstract base class for all header token consumers.
 *
 * Defines the base parser that loops over tokens, consuming them and creating
 * header parts.
 *
 * @author Zaahid Bateson
 */
abstract class AbstractConsumerService implements IConsumerService
{
    protected LoggerInterface $logger;

    /**
     * @var HeaderPartFactory used to construct IHeaderPart objects
     */
    protected HeaderPartFactory $partFactory;

    /**
     * @var AbstractConsumerService[] array of sub-consumers used by this
     *      consumer if any, or an empty array if none exist.
     */
    protected array $subConsumers = [];

    /**
     * @var ?string the generated token split pattern on first run, so it doesn't
     *      need to be regenerated every time.
     */
    private ?string $tokenSplitPattern = null;

    /**
     * @param AbstractConsumerService[] $subConsumers
     */
    public function __construct(LoggerInterface $logger, HeaderPartFactory $partFactory, array $subConsumers = [])
    {
        $this->logger = $logger;
        $this->partFactory = $partFactory;
        $this->subConsumers = $subConsumers;
    }

    public function __invoke(string $value) : array
    {
        $this->logger->debug('Starting {class} for "{value}"', ['class' => static::class, 'value' => $value]);
        if ($value !== '') {
            $parts = $this->parseRawValue($value);
            $this->logger->debug(
                'Ending {class} for "{value}": parsed into {cnt} header part objects',
                ['class' => static::class, 'value' => $value, 'cnt' => \count($parts)]
            );
            return $parts;
        }
        return [];
    }

    /**
     * Returns this consumer and all unique sub consumers.
     *
     * Loops into the sub-consumers (and their sub-consumers, etc...) finding
     * all unique consumers, and returns them in an array.
     *
     * @return AbstractConsumerService[] Array of unique consumers.
     */
    protected function getAllConsumers() : array
    {
        $found = [$this];
        do {
            $current = \current($found);
            $subConsumers = $current->subConsumers;
            foreach ($subConsumers as $consumer) {
                if (!\in_array($consumer, $found)) {
                    $found[] = $consumer;
                }
            }
        } while (\next($found) !== false);
        return $found;
    }

    /**
     * Parses the raw header value into header parts.
     *
     * Calls splitTokens to split the value into token part strings, then calls
     * parseParts to parse the returned array.
     *
     * @return \ZBateson\MailMimeParser\Header\IHeaderPart[] the array of parsed
     *         parts
     */
    private function parseRawValue(string $value) : array
    {
        $tokens = $this->splitRawValue($value);
        return $this->parseTokensIntoParts(new NoRewindIterator(new ArrayIterator($tokens)));
    }

    /**
     * Returns an array of regular expression separators specific to this
     * consumer.
     *
     * The returned patterns are used to split the header value into tokens for
     * the consumer to parse into parts.
     *
     * Each array element makes part of a generated regular expression that is
     * used in a call to preg_split().  RegEx patterns can be used, and care
     * should be taken to escape special characters.
     *
     * @return string[] Array of regex patterns.
     */
    abstract protected function getTokenSeparators() : array;

    /**
     * Returns a list of regular expression markers for this consumer and all
     * sub-consumers by calling getTokenSeparators().
     *
     * @return string[] Array of regular expression markers.
     */
    protected function getAllTokenSeparators() : array
    {
        $markers = $this->getTokenSeparators();
        $subConsumers = $this->getAllConsumers();
        foreach ($subConsumers as $consumer) {
            $markers = \array_merge($consumer->getTokenSeparators(), $markers);
        }
        return \array_unique($markers);
    }

    /**
     * Returns a regex pattern used to split the input header string.
     *
     * The default implementation calls
     * {@see AbstractConsumerService::getAllTokenSeparators()} and implodes the
     * returned array with the regex OR '|' character as its glue.
     *
     * @return string the regex pattern
     */
    protected function getTokenSplitPattern() : string
    {
        $sChars = \implode('|', $this->getAllTokenSeparators());
        $mimePartPattern = MimeToken::MIME_PART_PATTERN;
        return '~(' . $mimePartPattern . '|\\\\\r\n|\\\\.|' . $sChars . ')~ms';
    }

    /**
     * Returns an array of split tokens from the input string.
     *
     * The method calls preg_split using
     * {@see AbstractConsumerService::getTokenSplitPattern()}.  The split array
     * will not contain any empty parts and will contain the markers.
     *
     * @param string $rawValue the raw string
     * @return string[] the array of tokens
     */
    protected function splitRawValue($rawValue) : array
    {
        if ($this->tokenSplitPattern === null) {
            $this->tokenSplitPattern = $this->getTokenSplitPattern();
            $this->logger->debug(
                'Configuring {class} with token split pattern: {pattern}',
                ['class' => static::class, 'pattern' => $this->tokenSplitPattern]
            );
        }
        return \preg_split(
            $this->tokenSplitPattern,
            $rawValue,
            -1,
            PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY
        );
    }

    /**
     * Returns true if the passed string token marks the beginning marker for
     * the current consumer.
     *
     * @param string $token The current token
     */
    abstract protected function isStartToken(string $token) : bool;

    /**
     * Returns true if the passed string token marks the end marker for the
     * current consumer.
     *
     * @param string $token The current token
     */
    abstract protected function isEndToken(string $token) : bool;

    /**
     * Constructs and returns an IHeaderPart for the passed string token.
     *
     * If the token should be ignored, the function must return null.
     *
     * The default created part uses the instance's partFactory->newInstance
     * method.
     *
     * @param string $token the token
     * @param bool $isLiteral set to true if the token represents a literal -
     *        e.g. an escaped token
     * @return ?IHeaderPart The constructed header part or null if the token
     *         should be ignored.
     */
    protected function getPartForToken(string $token, bool $isLiteral) : ?IHeaderPart
    {
        if ($isLiteral) {
            return $this->partFactory->newToken($token, true);
        }
        // can be overridden with custom PartFactory
        return $this->partFactory->newInstance($token);
    }

    /**
     * Iterates through this consumer's sub-consumers checking if the current
     * token triggers a sub-consumer's start token and passes control onto that
     * sub-consumer's parseTokenIntoParts().
     *
     * If no sub-consumer is responsible for the current token, calls
     * {@see AbstractConsumerService::getPartForToken()} and returns it in an
     * array.
     *
     * @param Iterator<string> $tokens
     * @return IHeaderPart[]
     */
    protected function getConsumerTokenParts(Iterator $tokens) : array
    {
        $token = $tokens->current();
        $subConsumers = $this->subConsumers;
        foreach ($subConsumers as $consumer) {
            if ($consumer->isStartToken($token)) {
                $this->logger->debug(
                    'Token: "{value}" in {class} starting sub-consumer {consumer}',
                    ['value' => $token, 'class' => static::class, 'consumer' => \get_class($consumer)]
                );
                $this->advanceToNextToken($tokens, true);
                return $consumer->parseTokensIntoParts($tokens);
            }
        }
        $part = $this->getPartForToken($token, false);
        return ($part !== null) ? [$part] : [];
    }

    /**
     * Returns an array of IHeaderPart for the current token on the iterator.
     *
     * If the current token is a start token from a sub-consumer, the sub-
     * consumer's {@see AbstractConsumerService::parseTokensIntoParts()} method
     * is called.
     *
     * @param Iterator<string> $tokens The token iterator.
     * @return IHeaderPart[]
     */
    protected function getTokenParts(Iterator $tokens) : array
    {
        $token = $tokens->current();
        if ($token === "\\\r\n" || (\strlen($token) === 2 && $token[0] === '\\')) {
            $part = $this->getPartForToken(\substr($token, 1), true);
            return ($part !== null) ? [$part] : [];
        }
        return $this->getConsumerTokenParts($tokens);
    }

    /**
     * Determines if the iterator should be advanced to the next token after
     * reading tokens or finding a start token.
     *
     * The default implementation will advance for a start token, but not
     * advance on the end token of the current consumer, allowing the end token
     * to be passed up to a higher-level consumer.
     *
     * @param Iterator $tokens The token iterator.
     * @param bool $isStartToken true for the start token.
     */
    protected function advanceToNextToken(Iterator $tokens, bool $isStartToken) : static
    {
        $checkEndToken = (!$isStartToken && $tokens->valid());
        $isEndToken = ($checkEndToken && $this->isEndToken($tokens->current()));
        if (($isStartToken) || ($checkEndToken && !$isEndToken)) {
            $tokens->next();
        }
        return $this;
    }

    /**
     * Iterates over the passed token Iterator and returns an array of parsed
     * IHeaderPart objects.
     *
     * The method checks each token to see if the token matches a sub-consumer's
     * start token, or if it matches the current consumer's end token to stop
     * processing.
     *
     * If a sub-consumer's start token is matched, the sub-consumer is invoked
     * and its returned parts are merged to the current consumer's header parts.
     *
     * After all tokens are read and an array of Header\Parts are constructed,
     * the array is passed to {@see AbstractConsumerService::processParts} for
     * any final processing if there are any parts.
     *
     * @param Iterator<string> $tokens An iterator over a string of tokens
     * @return IHeaderPart[] An array of parsed parts
     */
    protected function parseTokensIntoParts(Iterator $tokens) : array
    {
        $parts = [];
        while ($tokens->valid() && !$this->isEndToken($tokens->current())) {
            $this->logger->debug('Parsing token: {token} in class: {consumer}', ['token' => $tokens->current(), 'consumer' => static::class]);
            $parts = \array_merge($parts, $this->getTokenParts($tokens));
            $this->advanceToNextToken($tokens, false);
        }
        return (empty($parts)) ? [] : $this->processParts($parts);
    }

    /**
     * Performs any final processing on the array of parsed parts before
     * returning it to the consumer client.  The passed $parts array is
     * guaranteed to not be empty.
     *
     * The default implementation simply returns the passed array after
     * filtering out null/empty parts.
     *
     * @param IHeaderPart[] $parts The parsed parts.
     * @return IHeaderPart[] Array of resulting final parts.
     */
    protected function processParts(array $parts) : array
    {
        $this->logger->debug('Processing parts array {parts} in {consumer}', ['parts' => $parts, 'consumer' => static::class]);
        return $parts;
    }
}


1		<?php
2		/**
3		* This file is part of the ZBateson\MailMimeParser project.
4		*
5		* @license http://opensource.org/licenses/bsd-license.php BSD
6		*/
7
8		namespace ZBateson\MailMimeParser\Header\Consumer;
9
10		use ArrayIterator;
11		use Iterator;
12		use NoRewindIterator;
13		use Psr\Log\LoggerInterface;
14		use ZBateson\MailMimeParser\Header\IHeaderPart;
15		use ZBateson\MailMimeParser\Header\Part\HeaderPartFactory;
16		use ZBateson\MailMimeParser\Header\Part\MimeToken;
17
18		/**
19		* Abstract base class for all header token consumers.
20		*
21		* Defines the base parser that loops over tokens, consuming them and creating
22		* header parts.
23		*
24		* @author Zaahid Bateson
25		*/
26		abstract class AbstractConsumerService implements IConsumerService
27		{
28		protected LoggerInterface $logger;
29
30		/**
31		* @var HeaderPartFactory used to construct IHeaderPart objects
32		*/
33		protected HeaderPartFactory $partFactory;
34
35		/**
36		* @var AbstractConsumerService[] array of sub-consumers used by this
37		* consumer if any, or an empty array if none exist.
38		*/
39		protected array $subConsumers = [];
40
41		/**
42		* @var ?string the generated token split pattern on first run, so it doesn't
43		* need to be regenerated every time.
44		*/
45		private ?string $tokenSplitPattern = null;
46
47		/**
48		* @param AbstractConsumerService[] $subConsumers
49		*/
50	83	public function __construct(LoggerInterface $logger, HeaderPartFactory $partFactory, array $subConsumers = [])
51		{
52	83	$this->logger = $logger;
53	83	$this->partFactory = $partFactory;
54	83	$this->subConsumers = $subConsumers;
55		}
56
57	189	public function __invoke(string $value) : array
58		{
59	189	$this->logger->debug('Starting {class} for "{value}"', ['class' => static::class, 'value' => $value]);
60	189	if ($value !== '') {
61	188	$parts = $this->parseRawValue($value);
62	188	$this->logger->debug(
63	188	'Ending {class} for "{value}": parsed into {cnt} header part objects',
64	188	['class' => static::class, 'value' => $value, 'cnt' => \count($parts)]
65	188	);
66	188	return $parts;
67		}
68	1	return [];
69		}
70
71		/**
72		* Returns this consumer and all unique sub consumers.
73		*
74		* Loops into the sub-consumers (and their sub-consumers, etc...) finding
75		* all unique consumers, and returns them in an array.
76		*
77		* @return AbstractConsumerService[] Array of unique consumers.
78		*/
79	84	protected function getAllConsumers() : array
80		{
81	84	$found = [$this];
82		do {
83	84	$current = \current($found);
84	84	$subConsumers = $current->subConsumers;
85	84	foreach ($subConsumers as $consumer) {
86	74	if (!\in_array($consumer, $found)) {
87	74	$found[] = $consumer;
88		}
89		}
90	84	} while (\next($found) !== false);
91	84	return $found;
92		}
93
94		/**
95		* Parses the raw header value into header parts.
96		*
97		* Calls splitTokens to split the value into token part strings, then calls
98		* parseParts to parse the returned array.
99		*
100		* @return \ZBateson\MailMimeParser\Header\IHeaderPart[] the array of parsed
101		* parts
102		*/
103	188	private function parseRawValue(string $value) : array
104		{
105	188	$tokens = $this->splitRawValue($value);
106	188	return $this->parseTokensIntoParts(new NoRewindIterator(new ArrayIterator($tokens)));
107		}
108
109		/**
110		* Returns an array of regular expression separators specific to this
111		* consumer.
112		*
113		* The returned patterns are used to split the header value into tokens for
114		* the consumer to parse into parts.
115		*
116		* Each array element makes part of a generated regular expression that is
117		* used in a call to preg_split(). RegEx patterns can be used, and care
118		* should be taken to escape special characters.
119		*
120		* @return string[] Array of regex patterns.
121		*/
122		abstract protected function getTokenSeparators() : array;
123
124		/**
125		* Returns a list of regular expression markers for this consumer and all
126		* sub-consumers by calling getTokenSeparators().
127		*
128		* @return string[] Array of regular expression markers.
129		*/
130	84	protected function getAllTokenSeparators() : array
131		{
132	84	$markers = $this->getTokenSeparators();
133	84	$subConsumers = $this->getAllConsumers();
134	84	foreach ($subConsumers as $consumer) {
135	84	$markers = \array_merge($consumer->getTokenSeparators(), $markers);
136		}
137	84	return \array_unique($markers);
138		}
139
140		/**
141		* Returns a regex pattern used to split the input header string.
142		*
143		* The default implementation calls
144		* {@see AbstractConsumerService::getAllTokenSeparators()} and implodes the
145		* returned array with the regex OR '\|' character as its glue.
146		*
147		* @return string the regex pattern
148		*/
149	66	protected function getTokenSplitPattern() : string
150		{
151	66	$sChars = \implode('\|', $this->getAllTokenSeparators());
152	66	$mimePartPattern = MimeToken::MIME_PART_PATTERN;
153	66	return '~(' . $mimePartPattern . '\|\\\\\r\n\|\\\\.\|' . $sChars . ')~ms';
154		}
155
156		/**
157		* Returns an array of split tokens from the input string.
158		*
159		* The method calls preg_split using
160		* {@see AbstractConsumerService::getTokenSplitPattern()}. The split array
161		* will not contain any empty parts and will contain the markers.
162		*
163		* @param string $rawValue the raw string
164		* @return string[] the array of tokens
165		*/
166	188	protected function splitRawValue($rawValue) : array
167		{
168	188	if ($this->tokenSplitPattern === null) {
169	84	$this->tokenSplitPattern = $this->getTokenSplitPattern();
170	84	$this->logger->debug(
171	84	'Configuring {class} with token split pattern: {pattern}',
172	84	['class' => static::class, 'pattern' => $this->tokenSplitPattern]
173	84	);
174		}
175	188	return \preg_split(
176	188	$this->tokenSplitPattern,
177	188	$rawValue,
178	188	-1,
179	188	PREG_SPLIT_DELIM_CAPTURE \| PREG_SPLIT_NO_EMPTY
180	188	);
181		}
182
183		/**
184		* Returns true if the passed string token marks the beginning marker for
185		* the current consumer.
186		*
187		* @param string $token The current token
188		*/
189		abstract protected function isStartToken(string $token) : bool;
190
191		/**
192		* Returns true if the passed string token marks the end marker for the
193		* current consumer.
194		*
195		* @param string $token The current token
196		*/
197		abstract protected function isEndToken(string $token) : bool;
198
199		/**
200		* Constructs and returns an IHeaderPart for the passed string token.
201		*
202		* If the token should be ignored, the function must return null.
203		*
204		* The default created part uses the instance's partFactory->newInstance
205		* method.
206		*
207		* @param string $token the token
208		* @param bool $isLiteral set to true if the token represents a literal -
209		* e.g. an escaped token
210		* @return ?IHeaderPart The constructed header part or null if the token
211		* should be ignored.
212		*/
213	160	protected function getPartForToken(string $token, bool $isLiteral) : ?IHeaderPart
214		{
215	160	if ($isLiteral) {
216	3	return $this->partFactory->newToken($token, true);
217		}
218		// can be overridden with custom PartFactory
219	160	return $this->partFactory->newInstance($token);
220		}
221
222		/**
223		* Iterates through this consumer's sub-consumers checking if the current
224		* token triggers a sub-consumer's start token and passes control onto that
225		* sub-consumer's parseTokenIntoParts().
226		*
227		* If no sub-consumer is responsible for the current token, calls
228		* {@see AbstractConsumerService::getPartForToken()} and returns it in an
229		* array.
230		*
231		* @param Iterator<string> $tokens
232		* @return IHeaderPart[]
233		*/
234	188	protected function getConsumerTokenParts(Iterator $tokens) : array
235		{
236	188	$token = $tokens->current();
237	188	$subConsumers = $this->subConsumers;
238	188	foreach ($subConsumers as $consumer) {
239	178	if ($consumer->isStartToken($token)) {
240	158	$this->logger->debug(
241	158	'Token: "{value}" in {class} starting sub-consumer {consumer}',
242	158	['value' => $token, 'class' => static::class, 'consumer' => \get_class($consumer)]
243	158	);
244	158	$this->advanceToNextToken($tokens, true);
245	158	return $consumer->parseTokensIntoParts($tokens);
246		}
247		}
248	188	$part = $this->getPartForToken($token, false);
249	188	return ($part !== null) ? [$part] : [];
250		}
251
252		/**
253		* Returns an array of IHeaderPart for the current token on the iterator.
254		*
255		* If the current token is a start token from a sub-consumer, the sub-
256		* consumer's {@see AbstractConsumerService::parseTokensIntoParts()} method
257		* is called.
258		*
259		* @param Iterator<string> $tokens The token iterator.
260		* @return IHeaderPart[]
261		*/
262	186	protected function getTokenParts(Iterator $tokens) : array
263		{
264	186	$token = $tokens->current();
265	186	if ($token === "\\\r\n" \|\| (\strlen($token) === 2 && $token[0] === '\\')) {
266	11	$part = $this->getPartForToken(\substr($token, 1), true);
267	11	return ($part !== null) ? [$part] : [];
268		}
269	186	return $this->getConsumerTokenParts($tokens);
270		}
271
272		/**
273		* Determines if the iterator should be advanced to the next token after
274		* reading tokens or finding a start token.
275		*
276		* The default implementation will advance for a start token, but not
277		* advance on the end token of the current consumer, allowing the end token
278		* to be passed up to a higher-level consumer.
279		*
280		* @param Iterator $tokens The token iterator.
281		* @param bool $isStartToken true for the start token.
282		*/
283	185	protected function advanceToNextToken(Iterator $tokens, bool $isStartToken) : static
284		{
285	185	$checkEndToken = (!$isStartToken && $tokens->valid());
286	185	$isEndToken = ($checkEndToken && $this->isEndToken($tokens->current()));
287	185	if (($isStartToken) \|\| ($checkEndToken && !$isEndToken)) {
288	185	$tokens->next();
289		}
290	185	return $this;
291		}
292
293		/**
294		* Iterates over the passed token Iterator and returns an array of parsed
295		* IHeaderPart objects.
296		*
297		* The method checks each token to see if the token matches a sub-consumer's
298		* start token, or if it matches the current consumer's end token to stop
299		* processing.
300		*
301		* If a sub-consumer's start token is matched, the sub-consumer is invoked
302		* and its returned parts are merged to the current consumer's header parts.
303		*
304		* After all tokens are read and an array of Header\Parts are constructed,
305		* the array is passed to {@see AbstractConsumerService::processParts} for
306		* any final processing if there are any parts.
307		*
308		* @param Iterator<string> $tokens An iterator over a string of tokens
309		* @return IHeaderPart[] An array of parsed parts
310		*/
311	188	protected function parseTokensIntoParts(Iterator $tokens) : array
312		{
313	188	$parts = [];
314	188	while ($tokens->valid() && !$this->isEndToken($tokens->current())) {
315	188	$this->logger->debug('Parsing token: {token} in class: {consumer}', ['token' => $tokens->current(), 'consumer' => static::class]);
316	188	$parts = \array_merge($parts, $this->getTokenParts($tokens));
317	188	$this->advanceToNextToken($tokens, false);
318		}
319	188	return (empty($parts)) ? [] : $this->processParts($parts);
320		}
321
322		/**
323		* Performs any final processing on the array of parsed parts before
324		* returning it to the consumer client. The passed $parts array is
325		* guaranteed to not be empty.
326		*
327		* The default implementation simply returns the passed array after
328		* filtering out null/empty parts.
329		*
330		* @param IHeaderPart[] $parts The parsed parts.
331		* @return IHeaderPart[] Array of resulting final parts.
332		*/
333	110	protected function processParts(array $parts) : array
334		{
335	110	$this->logger->debug('Processing parts array {parts} in {consumer}', ['parts' => $parts, 'consumer' => static::class]);
336	110	return $parts;
337		}
338		}
339

zbateson / mail-mime-parser

AbstractConsumerService::getTokenParts() A last analyzed 2025-09-03 23:45 UTC

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like

AbstractConsumerService::getTokenParts() A
last analyzed 2025-09-03 23:45 UTC