glastree_on_gitea
This commit is contained in:
@@ -0,0 +1,292 @@
|
||||
<?php
|
||||
/**
|
||||
* This file is part of the ZBateson\MailMimeParser project.
|
||||
*
|
||||
* @license http://opensource.org/licenses/bsd-license.php BSD
|
||||
*/
|
||||
|
||||
namespace ZBateson\MailMimeParser\Message;
|
||||
|
||||
use RecursiveIterator;
|
||||
|
||||
/**
|
||||
* An interface representing a message part that contains children.
|
||||
*
|
||||
* An IMultiPart object may have any number of child parts, or may be a child
|
||||
* itself with its own parent or parents.
|
||||
*
|
||||
* @author Zaahid Bateson
|
||||
*/
|
||||
interface IMultiPart extends IMessagePart
|
||||
{
|
||||
/**
|
||||
* Returns the part at the given 0-based index for this part (part 0) and
|
||||
* all parts under it, or null if not found with the passed filter function.
|
||||
*
|
||||
* Note that the first part returned is the current part itself. This is
|
||||
* usually desirable for queries with a passed filter, e.g. looking for an
|
||||
* part with a specific Content-Type that may be satisfied by the current
|
||||
* part.
|
||||
*
|
||||
* The passed callable must accept an {@see IMessagePart} as an argument,
|
||||
* and return true if it should be accepted, or false to filter the part
|
||||
* out. Some default filters are provided by static functions returning
|
||||
* callables in {@see PartFilter}.
|
||||
*
|
||||
* @see IMultiPart::getAllParts() to get an array of all parts with an
|
||||
* optional filter.
|
||||
* @see IMultiPart::getPartCount() to get the number of parts with an
|
||||
* optional filter.
|
||||
* @see IMultiPart::getChild() to get a direct child of the current part.
|
||||
* @param int $index The 0-based index (0 being this part if $fnFilter is
|
||||
* null or this part is satisfied by the filter).
|
||||
* @param callable $fnFilter Optional function accepting an IMessagePart and
|
||||
* returning true if the part should be included.
|
||||
* @return IMessagePart|null A matching part, or null if not found.
|
||||
*/
|
||||
public function getPart(int $index, ?callable $fnFilter = null) : ?IMessagePart;
|
||||
|
||||
/**
|
||||
* Returns the current part, all child parts, and child parts of all
|
||||
* children optionally filtering them with the provided PartFilter.
|
||||
*
|
||||
* Note that the first part returned is the current part itself. This is
|
||||
* often desirable for queries with a passed filter, e.g. looking for an
|
||||
* IMessagePart with a specific Content-Type that may be satisfied by the
|
||||
* current part.
|
||||
*
|
||||
* The passed callable must accept an {@see IMessagePart} as an argument,
|
||||
* and return true if it should be accepted, or false to filter the part
|
||||
* out. Some default filters are provided by static functions returning
|
||||
* callables in {@see PartFilter}.
|
||||
*
|
||||
* @see IMultiPart::getPart() to find a part at a specific 0-based index
|
||||
* with an optional filter.
|
||||
* @see IMultiPart::getPartCount() to get the number of parts with an
|
||||
* optional filter.
|
||||
* @see IMultiPart::getChildParts() to get an array of all direct children
|
||||
* of the current part.
|
||||
* @param callable $fnFilter Optional function accepting an IMessagePart and
|
||||
* returning true if the part should be included.
|
||||
* @return IMessagePart[] An array of matching parts.
|
||||
*/
|
||||
public function getAllParts(?callable $fnFilter = null) : array;
|
||||
|
||||
/**
|
||||
* Returns the total number of parts in this and all children.
|
||||
*
|
||||
* Note that the current part is considered, so the minimum getPartCount is
|
||||
* 1 without a filter.
|
||||
*
|
||||
* The passed callable must accept an {@see IMessagePart} as an argument,
|
||||
* and return true if it should be accepted, or false to filter the part
|
||||
* out. Some default filters are provided by static functions returning
|
||||
* callables in {@see PartFilter}.
|
||||
*
|
||||
* @see IMultiPart::getPart() to find a part at a specific 0-based index
|
||||
* with an optional filter.
|
||||
* @see IMultiPart::getAllParts() to get an array of all parts with an
|
||||
* optional filter.
|
||||
* @see IMultiPart::getChildCount() to get a count of direct children of
|
||||
* this part.
|
||||
* @param callable $fnFilter Optional function accepting an IMessagePart and
|
||||
* returning true if the part should be included.
|
||||
* @return int The number of matching parts.
|
||||
*/
|
||||
public function getPartCount(?callable $fnFilter = null) : int;
|
||||
|
||||
/**
|
||||
* Returns the direct child at the given 0-based index and optional filter,
|
||||
* or null if none exist or do not match.
|
||||
*
|
||||
* The passed callable must accept an {@see IMessagePart} as an argument,
|
||||
* and return true if it should be accepted, or false to filter the part
|
||||
* out. Some default filters are provided by static functions returning
|
||||
* callables in {@see PartFilter}.
|
||||
*
|
||||
* @see IMultiPart::getChildParts() to get an array of all direct children
|
||||
* of the current part.
|
||||
* @see IMultiPart::getChildCount() to get a count of direct children of
|
||||
* this part.
|
||||
* @see IMultiPart::getChildIterator() to get an iterator of children of
|
||||
* this part.
|
||||
* @see IMultiPart::getPart() to find a part at a specific 0-based index
|
||||
* with an optional filter.
|
||||
* @param int $index 0-based index
|
||||
* @param callable $fnFilter Optional function accepting an IMessagePart and
|
||||
* returning true if the part should be included.
|
||||
* @return IMessagePart|null The matching direct child part or null if not
|
||||
* found.
|
||||
*/
|
||||
public function getChild(int $index, ?callable $fnFilter = null) : ?IMessagePart;
|
||||
|
||||
/**
|
||||
* Returns an array of all direct child parts, optionally filtering them
|
||||
* with a passed callable.
|
||||
*
|
||||
* The passed callable must accept an {@see IMessagePart} as an argument,
|
||||
* and return true if it should be accepted, or false to filter the part
|
||||
* out. Some default filters are provided by static functions returning
|
||||
* callables in {@see PartFilter}.
|
||||
*
|
||||
* @see IMultiPart::getChild() to get a direct child of the current part.
|
||||
* @see IMultiPart::getChildCount() to get a count of direct children of
|
||||
* this part.
|
||||
* @see IMultiPart::getChildIterator() to get an iterator of children of
|
||||
* this part.
|
||||
* @see IMultiPart::getAllParts() to get an array of all parts with an
|
||||
* optional filter.
|
||||
* @param callable $fnFilter Optional function accepting an IMessagePart and
|
||||
* returning true if the part should be included.
|
||||
* @return IMessagePart[] An array of matching child parts.
|
||||
*/
|
||||
public function getChildParts(?callable $fnFilter = null) : array;
|
||||
|
||||
/**
|
||||
* Returns the number of direct children under this part (optionally
|
||||
* counting only filtered items if a callable filter is passed).
|
||||
*
|
||||
* The passed callable must accept an {@see IMessagePart} as an argument,
|
||||
* and return true if it should be accepted, or false to filter the part
|
||||
* out. Some default filters are provided by static functions returning
|
||||
* callables in {@see PartFilter}.
|
||||
*
|
||||
* @see IMultiPart::getChild() to get a direct child of the current part.
|
||||
* @see IMultiPart::getChildParts() to get an array of all direct children
|
||||
* of the current part.
|
||||
* @see IMultiPart::getChildIterator() to get an iterator of children of
|
||||
* this part.
|
||||
* @see IMultiPart::getPartCount() to get the number of parts with an
|
||||
* optional filter.
|
||||
* @param callable $fnFilter Optional function accepting an IMessagePart and
|
||||
* returning true if the part should be included.
|
||||
* @return int The number of children, or number of children matching the
|
||||
* the passed filtering callable.
|
||||
*/
|
||||
public function getChildCount(?callable $fnFilter = null) : int;
|
||||
|
||||
/**
|
||||
* Returns a \RecursiveIterator of child parts.
|
||||
*
|
||||
* The {@see https://www.php.net/manual/en/class.recursiveiterator.php \RecursiveIterator}
|
||||
* allows iterating over direct children, or using
|
||||
* a {@see https://www.php.net/manual/en/class.recursiveiteratoriterator.php \RecursiveIteratorIterator}
|
||||
* to iterate over direct children, and all their children.
|
||||
*
|
||||
* @see https://www.php.net/manual/en/class.recursiveiterator.php
|
||||
* RecursiveIterator
|
||||
* @see https://www.php.net/manual/en/class.recursiveiteratoriterator.php
|
||||
* RecursiveIteratorIterator
|
||||
* @see IMultiPart::getChild() to get a direct child of the current part.
|
||||
* @see IMultiPart::getChildParts() to get an array of all direct children
|
||||
* of the current part.
|
||||
* @see IMultiPart::getChildCount() to get a count of direct children of
|
||||
* this part.
|
||||
* @see IMultiPart::getAllParts() to get an array of all parts with an
|
||||
* optional filter.
|
||||
* @return RecursiveIterator<IMessagePart>
|
||||
*/
|
||||
public function getChildIterator() : RecursiveIterator;
|
||||
|
||||
/**
|
||||
* Returns the part that has a content type matching the passed mime type at
|
||||
* the given index, or null if there are no matching parts.
|
||||
*
|
||||
* Creates a filter that looks at the return value of
|
||||
* {@see IMessagePart::getContentType()} for all parts (including the
|
||||
* current part) and returns a matching one at the given 0-based index.
|
||||
*
|
||||
* @see IMultiPart::getAllPartsByMimeType() to get all parts that match a
|
||||
* mime type.
|
||||
* @see IMultiPart::getCountOfPartsByMimeType() to get a count of parts with
|
||||
* a mime type.
|
||||
* @param string $mimeType The mime type to find.
|
||||
* @param int $index Optional 0-based index (defaulting to '0').
|
||||
* @return IMessagePart|null The part.
|
||||
*/
|
||||
public function getPartByMimeType(string $mimeType, int $index = 0) : ?IMessagePart;
|
||||
|
||||
/**
|
||||
* Returns an array of all parts that have a content type matching the
|
||||
* passed mime type.
|
||||
*
|
||||
* Creates a filter that looks at the return value of
|
||||
* {@see IMessagePart::getContentType()} for all parts (including the
|
||||
* current part), returning an array of matching parts.
|
||||
*
|
||||
* @see IMultiPart::getPartByMimeType() to get a part by mime type.
|
||||
* @see IMultiPart::getCountOfPartsByMimeType() to get a count of parts with
|
||||
* a mime type.
|
||||
* @param string $mimeType The mime type to find.
|
||||
* @return IMessagePart[] An array of matching parts.
|
||||
*/
|
||||
public function getAllPartsByMimeType(string $mimeType) : array;
|
||||
|
||||
/**
|
||||
* Returns the number of parts that have content types matching the passed
|
||||
* mime type.
|
||||
*
|
||||
* @see IMultiPart::getPartByMimeType() to get a part by mime type.
|
||||
* @see IMultiPart::getAllPartsByMimeType() to get all parts that match a
|
||||
* mime type.
|
||||
* @param string $mimeType The mime type to find.
|
||||
* @return int The number of matching parts.
|
||||
*/
|
||||
public function getCountOfPartsByMimeType(string $mimeType) : int;
|
||||
|
||||
/**
|
||||
* Returns a part that has the given Content ID, or null if not found.
|
||||
*
|
||||
* Calls {@see IMessagePart::getContentId()} to find a matching part.
|
||||
*
|
||||
* @param string $contentId The content ID to find a part for.
|
||||
* @return IMessagePart|null The matching part.
|
||||
*/
|
||||
public function getPartByContentId(string $contentId) : ?IMessagePart;
|
||||
|
||||
/**
|
||||
* Registers the passed part as a child of the current part.
|
||||
*
|
||||
* If the $position parameter is non-null, adds the part at the passed
|
||||
* position index, otherwise adds it as the last child.
|
||||
*
|
||||
* @param MessagePart $part The part to add.
|
||||
* @param int $position Optional insertion position 0-based index.
|
||||
*/
|
||||
public function addChild(MessagePart $part, ?int $position = null) : static;
|
||||
|
||||
/**
|
||||
* Removes the child part from this part and returns its previous position
|
||||
* or null if it wasn't found.
|
||||
*
|
||||
* Note that if the part is not a direct child of this part, the returned
|
||||
* position is its index within its parent (calls removePart on its direct
|
||||
* parent).
|
||||
*
|
||||
* This also means that parts from unrelated parts/messages could be removed
|
||||
* by a call to removePart -- it will always remove the part from its parent
|
||||
* if it has one, essentially calling
|
||||
* ```php $part->getParent()->removePart(); ```.
|
||||
*
|
||||
* @param IMessagePart $part The part to remove
|
||||
* @return int|null The previous index position of the part within its old
|
||||
* parent.
|
||||
*/
|
||||
public function removePart(IMessagePart $part) : ?int;
|
||||
|
||||
/**
|
||||
* Removes all parts below the current part. If a callable filter is
|
||||
* passed, removes only those matching the passed filter. The number of
|
||||
* removed parts is returned.
|
||||
*
|
||||
* Note: the current part will not be removed. Although the function naming
|
||||
* matches getAllParts, which returns the current part, it also doesn't only
|
||||
* remove direct children like getChildParts. Internally this function uses
|
||||
* getAllParts but the current part is filtered out if returned.
|
||||
*
|
||||
* @param callable $fnFilter Optional function accepting an IMessagePart and
|
||||
* returning true if the part should be included.
|
||||
* @return int The number of removed parts.
|
||||
*/
|
||||
public function removeAllParts(?callable $fnFilter = null) : int;
|
||||
}
|
||||
Reference in New Issue
Block a user