function DescriptionFactory::removeSuperfluousStartingWhitespace

Removes the superfluous from a multi-line description.

When a description has more than one line then it can happen that the second and subsequent lines have an additional indentation. This is commonly in use with tags like this:

{since 1.1.0 This is an example description where we have an indentation in the second and subsequent lines.

If we do not normalize the indentation then we have superfluous whitespace on the second and subsequent lines and this may cause rendering issues when, for example, using a Markdown converter.

1 call to DescriptionFactory::removeSuperfluousStartingWhitespace()

DescriptionFactory::lex in vendor/phpdocumentor/reflection-docblock/src/DocBlock/DescriptionFactory.php

Strips the contents from superfluous whitespace and splits the description into a series of tokens.

File

vendor/phpdocumentor/reflection-docblock/src/DocBlock/DescriptionFactory.php, line 146

Class

DescriptionFactory

Creates a new Description object given a body of text.

Namespace

phpDocumentor\Reflection\DocBlock

Code

private function removeSuperfluousStartingWhitespace(string $contents) : string {
    $lines = Utils::pregSplit("/\r\n?|\n/", $contents);
    // if there is only one line then we don't have lines with superfluous whitespace and
    // can use the contents as-is
    if (count($lines) <= 1) {
        return $contents;
    }
    // determine how many whitespace characters need to be stripped
    $startingSpaceCount = 9999999;
    for ($i = 1, $iMax = count($lines); $i < $iMax; ++$i) {
        // lines with a no length do not count as they are not indented at all
        if (trim($lines[$i]) === '') {
            continue;
        }
        // determine the number of prefixing spaces by checking the difference in line length before and after
        // an ltrim
        $startingSpaceCount = min($startingSpaceCount, strlen($lines[$i]) - strlen(ltrim($lines[$i])));
    }
    // strip the number of spaces from each line
    if ($startingSpaceCount > 0) {
        for ($i = 1, $iMax = count($lines); $i < $iMax; ++$i) {
            $lines[$i] = substr($lines[$i], $startingSpaceCount);
        }
    }
    return implode("\n", $lines);
}