BC BREAK: removed Scanner component, removed FileReflection, remo…

…ved `NameInformation` and made `DocBlockScanner` `@internal`

The scanners were full of incomplete, untested and generally experimental code that would simply
crash when presented with something like PHP 8 code.

In addition to that, they were extremely unmaintainable due to the code being written for PHP 5,
and never being touched afterwards (too complex).

In order to slim down things and keep maintenance cost low, the complete `Laminas\Code\Scanner`
component has been trashed, with the exception of `Laminas\Code\Scanner\DocBlockScanner`, which
is still used in in some reflection internals.

It is advised for end-users to move to more modern tooling, such as [`roave/better-reflection`](https://github.com/Roave/BetterReflection)
which provides a safer (and well tested) API to scan source directories and extract reflection
information without loading any potentially dangerous PHP files.

The following components have been removed from the public API:

 * `Laminas\Code\Scanner\*`
 * `Laminas\Code\NameInformation` (unused in this package)
 * `Laminas\Code\Reflection\FileReflection` (use `roave/better-reflection` instead)
 * `Laminas\Code\Generic\Prototype\*`, which contains utilities to define custom docblock types:
   please consider using something like https://github.com/phpDocumentor/ReflectionDocBlock instead.

docs/book/generator/examples.md

@@ -322,17 +322,6 @@ define('APPLICATION_ENV', 'testing');
 
 ## Add code to existing PHP files and classes
 
-### Seeding PHP file code generation via reflection
-
-You can add *PHP* code to an existing *PHP* file using the code generator. To do so, you need to
-first do reflection on it. The static method `fromReflectedFileName()` allows you to do this.
-
-```php
-$generator = Laminas\Code\Generator\FileGenerator::fromReflectedFileName($path);
-$generator->setBody("\$foo->bar();");
-file_put_contents($path, $generator->generate());
-```
-
 ### Seeding PHP class generation via reflection
 
 You may add code to an existing class. To do so, first use the static `fromReflection()` method to

docs/book/generator/reference.md

@@ -268,7 +268,6 @@ class Laminas\Code\Generator\FileGenerator extends Laminas\Code\Generator\Abstra
         $filePath,
         $usePreviousCodeGeneratorIfItExists = true,
         $includeIfNotAlreadyIncluded = true)
-    public static function fromReflection(Laminas\Code\Reflection\FileReflection $reflectionFile)
     public function setDocblock(Laminas\Code\Generator\DocBlockGenerator $docblock)
     public function getDocblock()
     public function setRequiredFiles($requiredFiles)

src/Generator/FileGenerator.php

@@ -11,8 +11,6 @@
 use Laminas\Code\DeclareStatement;
 use Laminas\Code\Exception\InvalidArgumentException;
 use Laminas\Code\Generator\Exception\ClassNotFoundException;
-use Laminas\Code\Reflection\Exception as ReflectionException;
-use Laminas\Code\Reflection\FileReflection;
 
 use function array_key_exists;
 use function array_merge;
@@ -91,66 +89,6 @@ public function __construct($options = null)
         }
     }
 
-    /**
-     * Use this if you intend on generating code generation objects based on the same file.
-     * This will keep previous changes to the file in tact during the same PHP process
-     *
-     * @param  string $filePath
-     * @param  bool $includeIfNotAlreadyIncluded
-     * @throws ReflectionException\InvalidArgumentException If file does not exists
-     * @throws ReflectionException\RuntimeException If file exists but is not included or required
-     * @return FileGenerator
-     */
-    public static function fromReflectedFileName($filePath, $includeIfNotAlreadyIncluded = true)
-    {
-        $fileReflector = new FileReflection($filePath, $includeIfNotAlreadyIncluded);
-        $codeGenerator = static::fromReflection($fileReflector);
-
-        return $codeGenerator;
-    }
-
-    /**
-     * @param  FileReflection $fileReflection
-     * @return FileGenerator
-     */
-    public static function fromReflection(FileReflection $fileReflection)
-    {
-        $file = new static();
-
-        $file->setSourceContent($fileReflection->getContents());
-        $file->setSourceDirty(false);
-
-        $uses = $fileReflection->getUses();
-
-        foreach ($fileReflection->getClasses() as $class) {
-            $phpClass = ClassGenerator::fromReflection($class);
-            $phpClass->setContainingFileGenerator($file);
-
-            foreach ($uses as $fileUse) {
-                $phpClass->addUse($fileUse['use'], $fileUse['as']);
-            }
-
-            $file->setClass($phpClass);
-        }
-
-        $namespace = $fileReflection->getNamespace();
-
-        if ($namespace != '') {
-            $file->setNamespace($namespace);
-        }
-
-        if ($uses) {
-            $file->setUses($uses);
-        }
-
-        if ($fileReflection->getDocComment() != '') {
-            $docBlock = $fileReflection->getDocBlock();
-            $file->setDocBlock(DocBlockGenerator::fromReflection($docBlock));
-        }
-
-        return $file;
-    }
-
     /**
      * @param  array $values
      * @return FileGenerator

src/Generic/Prototype/PrototypeClassFactory.php

@@ -22,6 +22,8 @@
  * If the factory can not supply the class someone is asking for
  * it tries to fallback on a generic default prototype, which would
  * have need to be set before.
+ *
+ * @internal this class is not part of the public API of this package
  */
 class PrototypeClassFactory
 {

src/Generic/Prototype/PrototypeGenericInterface.php

@@ -8,6 +8,7 @@
 
 namespace Laminas\Code\Generic\Prototype;
 
+/** @internal this class is not part of the public API of this package */
 interface PrototypeGenericInterface extends PrototypeInterface
 {
     /**

src/Generic/Prototype/PrototypeInterface.php

@@ -8,6 +8,7 @@
 
 namespace Laminas\Code\Generic\Prototype;
 
+/** @internal this class is not part of the public API of this package */
 interface PrototypeInterface
 {
     /**

src/Reflection/ClassReflection.php

@@ -27,18 +27,6 @@ class ClassReflection extends ReflectionClass implements ReflectionInterface
      */
     protected $docBlock;
 
-    /**
-     * Return the reflection file of the declaring file.
-     *
-     * @return FileReflection
-     */
-    public function getDeclaringFile()
-    {
-        $instance = new FileReflection($this->getFileName());
-
-        return $instance;
-    }
-
     /**
      * Return the classes DocBlock reflection object
      *