Reflection Laravel Package

Getting Started

Treat this as a legacy dependency, not a greenfield choice: the package is archived, its last release was 2017, and the description literally begins with [DISCONTINUED]. It exists because Nette Framework 2.x and a long tail of packages used it for docblock annotations and convenience reflection wrappers.

Minimal steps:

1. Confirm the license before shipping. Composer reports NOASSERTION, which usually means the metadata is missing; Nette packages of that era are BSD-3-Clause, but verify the LICENSE file in the repo/fork you actually install.
2. Pin an exact version so a future constraint change or PHP bump doesn't surprise the build:

   composer require nette/reflection:2.4.*
   

   Composer will print an "abandoned" warning; that's expected and does not block installation.
3. Look first at the three files that matter:
   • src/Reflection/ClassReflection.php — the wrapper, from() factory, getAnnotations() / hasAnnotation() / getAnnotation().
   • src/Reflection/AnnotationsParser.php — the actual docblock parser.
   • src/Reflection/Annotation.php — what you get back (name plus parsed value arguments). The whole package is a handful of files; there is no separate manual.
4. First use case — read an annotation off a class or method in an existing codebase:

   $ref = Nette\Reflection\ClassReflection::from(MyService::class);
   
   if ($ref->hasAnnotation('inject')) {
       // ...
   }
   
   foreach ($ref->getAnnotations() as $annotation) {
       echo $annotation->name;      // 'route'
       var_dump($annotation->value); // ['/home', 'method' => 'GET']
   }
   

5. Decide early whether you need it at all. For new code, use native ReflectionClass plus PHP 8 attributes; for docblock parsing only, use phpdocumentor/reflection-docblock. Reach for nette/reflection when you are maintaining a Nette 2.x-era codebase and want the smallest diff.

Implementation Patterns

Annotation-driven registration (the classic pattern). Scan a directory of classes, reflect each with ClassReflection::from(), and build a map from annotations such as @inject, @service, @route, or @persistent. Always go through from() so you can accept a string, an object, or an existing ReflectionClass interchangeably.

Custom annotation arguments. The parser handles both positional and named arguments:

/**
 * @route("/users", method="GET", priority=10)
 */

Use named arguments in your own annotations. They survive argument reordering and make the parsed value array self-documenting.

Property and method metadata. PropertyReflection::getAnnotation('var') and MethodReflection::getAnnotation('return') / getAnnotation('param') were the standard way to recover types before typed properties and return types. If you're on PHP 7.4+, prefer native types and reserve annotations for things native reflection cannot express (routes, DI hints, serialization rules).

Standalone docblock parsing. AnnotationsParser::parsePhpDoc($docblock) is useful when you have a doc comment string but no reflection object — e.g. parsing annotations out of generated code or a template file.

Cache behind your own layer. Reflection plus docblock parsing is cheap per class but adds up when you scan hundreds of classes on every request. Memoize a [class => metadata] array in-process; for cross-request caching, serialize to APCu or a file cache keyed on filemtime.

Adapter/wrapper pattern — the most important tip. Wrap the package behind your own small MetadataReader interface (getClassAnnotations(string $class): array, etc.). Callers depend on your interface, not on Nette\Reflection\*. This is what makes the eventual migration to attributes or roave/better-reflection a one-file change instead of a codebase-wide grep.

Coexistence with native reflection. ClassReflection extends \ReflectionClass, so instanceof \ReflectionClass still holds and you can pass it anywhere native reflection is accepted. Use ClassReflection only where you need annotations, and native reflection everywhere else.

Gotchas and Tips

• PHP 8 compatibility is the big risk. ReflectionParameter::getClass() was deprecated and internal method signatures changed; overridden reflection methods in an archived package can fatal or silently misbehave. Test on the exact PHP version you deploy before committing to it.
• No security fixes. Archived means no patches for parser bugs. If you need one, vendor-fork the package and point Composer at your fork with a vcs repository.
• Don't trust untrusted docblocks. The parser resolves annotation names and values; if you act on arbitrary @Foo class names from plugin or user-supplied code, you create an instantiation/injection vector. Whitelist the annotation names you accept.
• The parser is not Doctrine. Expect no nested annotation objects, no constant expressions, limited array syntax, and no full use-statement/namespace import resolution. Don't feed it arbitrary PHPDoc and expect parity.
• Silent failures. A typo in an annotation name yields no annotation and no error. Add a dev-mode assertion that required annotations exist on the classes that need them; otherwise you'll debug a "missing service" for an hour.
• Caching staleness. In-process memoization keyed by file and line goes stale in long-running workers (Octane, Swoole) when source files change. Key cross-request caches on filemtime and disable caching in dev.
• Case sensitivity. Be consistent with annotation casing (@Inject vs @inject); matching behavior is not something to rely on across versions.
• License metadata. NOASSERTION will trip automated license scanners. Resolve it explicitly in your dependency review rather than inheriting the ambiguity.
• Migration path. Nette 3 dropped this package in favor of native reflection and configuration; if you're on Nette 3+, it should already be gone from your dependency tree. Otherwise migrate to PHP 8 attributes plus native reflection, phpdocumentor/reflection-docblock for docblock parsing, or symfony/property-info / roave/better-reflection for richer type resolution.
• Extension points are thin. AnnotationsParser is the only meaningful seam — subclassing the reflection wrappers is possible but fragile on an unmaintained base. Prefer composition around the parser over inheritance from the reflection classes.