Add a new DefineStrategy to replace the DefinedSymbolCollector

[llaville]

Behind this goal, there is a bug available with latest version 0.2.2 but also all new stuffs added since then.

Idea behind that is to simplify usage with only the ConsumedSymbolCollector (with one or more strategies), and removed (or deprecated usage of) the DefinedSymbolCollector.

To fix the #136 issue, I'll propose a new PR with the new DefineStrategy.
Its goal is to provide all symbols (classes, interfaces, traits, functions, constants, namespaces) where traits and namespaces were missing when using the DefinedSymbolCollector.

Here is an example how to use the new DefineStrategy

<?php

use ComposerUnused\SymbolParser\Parser\PHP\ConsumedSymbolCollector;
use ComposerUnused\SymbolParser\Parser\PHP\Strategy\DefineStrategy;
use ComposerUnused\SymbolParser\Parser\PHP\SymbolNameParser;
use PhpParser\NodeVisitor\NameResolver;
use PhpParser\ParserFactory;
use Symfony\Component\Finder\Finder;

require_once __DIR__ . '/vendor/autoload.php';


$strategies = [
    new DefineStrategy(),
];

$finder = new Finder();
$finder
    ->files()
    ->in($dataSource)
    ->name('/\\.(php|inc|phtml)$/');

$symbolParser = new SymbolNameParser(
    (new ParserFactory())->createForNewestSupportedVersion(),
    new NameResolver(),
    new ConsumedSymbolCollector($strategies)
);

foreach ($finder as $fileInfo) {
    $taskId = $fileInfo->getRelativePathname();
    $symbols = iterator_to_array(
        $symbolParser->parseSymbolNames($fileInfo->getContents())
    );
    printf('Task %s found %d symbol(s)'. PHP_EOL, $taskId, count($symbols));
    var_export($symbols);
    echo PHP_EOL;
}

[llaville]

Regression tests took me a long time, especially because I wanted to find a way to handle Parser errors correctly (see https://github.com/composer-unused/symbol-parser/blob/0.2.2/src/Parser/PHP/SymbolNameParser.php#L43)

Now all it's ok and PR will come shortly. But it's time for explains about error handler !

PHP-Parser has it's own error handler recovery system.
So I wanted to introduce a compatible version.

<?php

namespace ComposerUnused\SymbolParser\Parser\PHP;

use PhpParser\ErrorHandler;

final class ParserErrorCollector extends ErrorHandler\Collecting implements ParserErrorCollectorInterface
{
}

<?php

namespace ComposerUnused\SymbolParser\Parser\PHP;

use PhpParser\ErrorHandler;

interface ParserErrorCollectorInterface extends ErrorHandler
{
    public function getErrors(): array;

    public function hasErrors() : bool;

    public function clearErrors();
}

As the default error handling strategy is ErrorHandler\Throwing, which will immediately throw when an error is encountered, I think it's not appropriate to the SymbolNameParser component !

By using the default ParserErrorCollector which will collect all errors found during source code parsing, SymbolNameParser will never stop.
You're free later to get those collected errors if needed.

But you've also the alternative to stop symbol name parsing by explicitly specify the ErrorHandler\Throwing of PHP-Parser.

Default behavior (collect errors) without to specify the error handler is not recommanded, because the PHP-Parser NameResolver component used a ErrorHandler\Throwing instance.

For example :

<?php

use ComposerUnused\SymbolParser\Parser\PHP\ConsumedSymbolCollector;
use ComposerUnused\SymbolParser\Parser\PHP\SymbolNameParser;
use PhpParser\NodeVisitor\NameResolver;
use PhpParser\ParserFactory;


$symbolNameParser = new SymbolNameParser(
    (new ParserFactory())->createForNewestSupportedVersion(),
    new NameResolver(),
    new ConsumedSymbolCollector($strategies)
);
$symbols = $symbolNameParser->parseSymbolNames($code);

Recommended way is to use :

<?php

use ComposerUnused\SymbolParser\Parser\PHP\ConsumedSymbolCollector;
use ComposerUnused\SymbolParser\Parser\PHP\ParserErrorCollector;
use ComposerUnused\SymbolParser\Parser\PHP\SymbolNameParser;
use PhpParser\ErrorHandler\Throwing;
use PhpParser\NodeVisitor\NameResolver;
use PhpParser\ParserFactory;


$errorHandler = new ParserErrorCollector();
// or alternative
// $errorHandler = new Throwing();

$symbolNameParser = new SymbolNameParser(
    (new ParserFactory())->createForNewestSupportedVersion(),
    new NameResolver($errorHandler),
    new ConsumedSymbolCollector($strategies),
    $errorHandler
);
$symbols = $symbolNameParser->parseSymbolNames($code);

[llaville]

PR #138 is on way now !

[llaville]

Even, if PR 138 was already merged, I've an enhanced version available with commit ac04199

[llaville]

Will close this discussion because the DefineStrategy is available since official release 0.2.3