Download the PHP package componenta/class-finder without Composer

Componenta ClassFinder

Lazy PHP declaration discovery with composable predicates and listener notification.

ClassFinder scans PHP files, extracts named class/interface/trait/enum declarations through componenta/tokenizer, applies predicates, and returns a replayable iterator of ClassInfo metadata.

Installation

Requirements

• PHP 8.4+
• symfony/finder
• componenta/tokenizer
• componenta/filter 2.x
• componenta/arrayable
• componenta/iterator
• psr/container
• psr/log

Related Packages

Quick Start

Predicates

ClassFinder and ClassIterator accept Componenta\Filter\PredicateInterface. A predicate does not need iterable/filter behavior:

The built-in ClassFinder filters still extend Componenta\Filter\AbstractFilter, so they also implement FilterInterface and remain usable as both predicates and iterable filters. Collection-only operators such as PercentageFilter and MergingFilter are intentionally not valid ClassFinder predicates.

Search Modes

find() accepts the tokenizer search bitmask directly:

Search mode is a per-call argument. It is not a DI configuration key.

ClassIterator

ClassFinder::find() returns ClassIteratorInterface: lazy, replayable, countable, arrayable, and predicate-filterable.

withFilter() and withoutFilter() accept PredicateInterface. The iterator caches traversed declarations so it can be iterated more than once. Each count() evaluates its current predicates again; changing a predicate or creating a filtered clone does not reuse a count computed for another predicate state. Interleaved iterations use independent cursors over the shared source cache. Nested traversal, filtered clones, and count() do not interrupt an active traversal. If the source throws, later reads rethrow the original exception, so partial discovery cannot be mistaken for a complete result.

Restoring a prepared map

ClassIterator::fromMap() creates an iterator from an ordered list of declaration records:

Every record requires non-empty file and name strings, a type of class, interface, trait or enum, and boolean abstract, final and readonly flags. The entire map is validated before the iterator is returned; invalid records throw RuntimeException. An empty list is valid.

The factory preserves declaration order and repeated filenames. It does not read files or scan directories. Iteration, filtering and replay use the same ClassIterator behavior as discovery. Loading and storing the map belong to the caller.

Pattern Filters

PatternFilter matches ClassInfo metadata without reflection.

Use exactNamespace() when the input is a namespace without wildcard. A bare string containing \ is treated as a fully-qualified class name or FQN pattern.

Reflection Filters

Some predicates require the declaration to be loaded because they use ClassInfo::$reflector:

• AttributeSearchFilter
• AttributePatternFilter
• AnyAttributeFilter
• HasAnyAttributesFilter
• ImplementsFilter
• ImplementsAnyFilter
• SubclassFilter

These predicates are appropriate when scanned classes are autoloadable. For pure source inspection of unloaded files, prefer metadata-only predicates such as PatternFilter, InstantiableFilter, IsAbstractFilter, and IsFinalFilter.

Attribute Filters

deepSearch: true also checks methods, properties, and constants.

Listeners

Listeners are notified for each accepted declaration. Finalizable listeners are finalized after scanning, even when no declarations were found.

ClassListenerNotifier snapshots the provider's listeners once per notify() call, so the same listener instances receive handle() and finalize().

A listener can expose its completion state through FinalizationStateInterface. The finalized property becomes true only after a successful finalize() call. Repeated finalization may be rejected by the listener; the package provides FinalizationExceptionInterface and ListenerAlreadyFinalizedException for that case.

Application build integration

Applications and integration packages register independent builders through Componenta\App\ConfigKey::BUILDERS. Each builder implements ApplicationBuilderInterface::build(): void and receives the shared source iterator or a prepared listener through its constructor. The builder owns its artifact format and writes. Class discovery and listener notification remain available independently of application builds.

Container Integration

Register the package provider in a PSR-11 compatible container:

Runtime configuration keys are defined in Componenta\ClassFinder\ConfigKey:

The FILTERS key keeps its existing name, but entries are predicates in 2.x. Listener config remains fail-fast: every listener entry must be an instance or a service id string resolving to ClassListenerInterface.

Breaking Changes for filter 2.x

• ClassFinder and ClassIterator accept PredicateInterface instead of FilterInterface.
• Pure predicates no longer need IteratorAggregate, withIterable(), or toArray().
• Collection-only filter operators cannot be passed as discovery predicates.
• Existing ClassFinder filter classes remain source-compatible because FilterInterface extends PredicateInterface in componenta/filter 2.x.

License

MIT