PHPackages                             northrook/php-class-finder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. northrook/php-class-finder

ActiveLibrary[Utility & Helpers](/categories/utility)

northrook/php-class-finder
==========================

Find fully qualified classes from files

021PHP

Since Aug 7Pushed 3w agoCompare

[ Source](https://codeberg.org/northrook/php-class-finder/)[ Packagist](https://packagist.org/packages/northrook/php-class-finder)[ RSS](/packages/northrook-php-class-finder/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

PHP Class Finder
================

[](#php-class-finder)

Discover autoloadable PHP classes from directories.

- Requires PHP 8.4+
- No runtime dependencies

Installation
------------

[](#installation)

```
composer require northrook/php-class-finder
```

Quick start
-----------

[](#quick-start)

Point the finder at your project root, scan one or more directories, then filter by attribute:

```
use Northrook\ClassFinder;

$finder = new ClassFinder(__DIR__);

$services = $finder
    ->scanDirectories('src/*')
    ->anyAttribute(App\Attribute\Service::class);

foreach ($services as $classInfo) {
    $instance = $classInfo(); // instantiate via __invoke
}
```

`ClassFinder` resolves paths relative to the root directory.

Append `*` for recursive scanning (`src/*`); omit it to scan only the immediate directory (`src`).

How it works
------------

[](#how-it-works)

Walks `.php` files, parses for `class` declaration, only accepting autoloadable classes.

Results are keyed by the absolute file path.

This is lightweight: no full AST parsing, and files are not blindly `require`d. Kept classes are confirmed via the autoloader (`class_exists`), which does load them.

Intended for cold-path operations, like bootstrapping DI containers, route discovery, etc.

### What gets included

[](#what-gets-included)

- `class`, `abstract class`, `final class`, and `readonly` variants
- Classes in the global namespace
- Classes with attributes on preceding lines (including multiline `#[...]`)

### What gets skipped

[](#what-gets-skipped)

- Hidden files, prefixed with `.`
- Non-`.php` files
- Interfaces, enums, and traits
- Files with no class definition
- A second `class` in the same file (only the first is read, as per PSR-4)
- Classes that are not autoloadable
- Code after an early `return`, `exit`, or `die`
- Namespaces listed in `excludeNamespaces()` (defaults to `Composer`)

API
---

[](#api)

### `ClassFinder`

[](#classfinder)

Entry point. Configure the root path and namespace exclusions, then scan.

```
$finder = new ClassFinder('/path/to/project');
$finder->excludeNamespaces('Vendor\\Generated', 'Tests');

$scan = $finder->scanDirectories('src/*', 'config');
```

MemberDescription`$rootDirectory`Normalized absolute path passed to the constructor`$lastScan`Most recent `ClassScan`, or `null``excludeNamespaces(...)`Replace excluded namespaces; no arguments resets to `['Composer']``scanDirectories(...)`Scan directories relative to the root; returns `ClassScan``normalizePath()`Collapse mixed separators into an absolute-style path### `ClassScan`

[](#classscan)

Immutable scan result. Iterable and countable; values are `ClassInfo` instances.

```
$scan = $finder->scanDirectories('src/*');

$scan->count();
$scan->getArray();                              // [filePath => ClassInfo]
$scan->anyAttribute(Foo::class, Bar::class);    // classes with at least one match
$scan->withAttributes(Foo::class, Bar::class);  // classes with every attribute
```

`anyAttribute()` and `withAttributes()` use exact attribute class names.

For inheritance-aware matching, use `ClassInfo::getAttributes()` on individual results.

### `ClassInfo`

[](#classinfo)

Metadata and reflection helpers for a single class.

```
use Northrook\ClassFinder\ClassInfo;

$info = ClassInfo::from(SomeService::class);

$info->className;   // FQCN
$info->basename;    // short name
$info->namespace;   // namespace without short name
$info->file;        // absolute path to the defining file
$info->reflection;  // lazy ReflectionClass

$info->hasAttribute(Service::class);   // exact match
$info->getAttributes(Service::class);  // includes subclasses (IS_INSTANCEOF)
$info->getAttribute(Service::class);   // single instance, or null
$info( ...$args );                     // instantiate the class

ClassInfo::basename($class, 'strtolower');
ClassInfo::exists('Some\\Class');
```

Development
-----------

[](#development)

```
composer test
composer phpstan
```

License
-------

[](#license)

BSD-3-Clause. See [LICENSE.md](LICENSE.md).

###  Health Score

22

—

LowBetter than 21% of packages

Maintenance62

Regular maintenance activity

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/60818044?v=4)[Martin](/maintainers/martinlikescoffee)[@martinlikescoffee](https://github.com/martinlikescoffee)

---

Top Contributors

[![martinlikescoffee](https://avatars.githubusercontent.com/u/60818044?v=4)](https://github.com/martinlikescoffee "martinlikescoffee (11 commits)")

---

Tags

finderphppsr-4wip

### Embed Badge

![Health badge](/badges/northrook-php-class-finder/health.svg)

```
[![Health](https://phpackages.com/badges/northrook-php-class-finder/health.svg)](https://phpackages.com/packages/northrook-php-class-finder)
```

###  Alternatives

[cloudflare/cloudflare-magento

Cloudflare Plugin for Magento2

5272.0k](/packages/cloudflare-cloudflare-magento)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)