PHPackages                             tcds-io/php-better-generics - 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. tcds-io/php-better-generics

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

tcds-io/php-better-generics
===========================

PHP library to better work with generics

1.0.0(2mo ago)03.2k—5.6%2MITPHPPHP ^8.4CI passing

Since Jan 13Pushed 2mo agoCompare

[ Source](https://github.com/tcds-io/php-better-generics)[ Packagist](https://packagist.org/packages/tcds-io/php-better-generics)[ RSS](/packages/tcds-io-php-better-generics/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (3)Dependencies (9)Versions (10)Used By (2)

php-better-generics
===================

[](#php-better-generics)

PHP 8.4+ library for working with generics at runtime: typed collections, lazy object proxies, and a reflection layer that understands `@template`, `@extends`, `@implements`, generic types, and array shapes from PHPDoc.

Why
---

[](#why)

PHP doesn't have native generics — only static analyzers (PHPStan, Psalm) do. This library bridges that gap at runtime by:

- Reading the PHPDoc you already write for static analysis (`@template T`, `@param list $items`, `@extends Collection`) and exposing it through a `ReflectionClass` API that resolves real FQNs.
- Providing thin, well-typed `ArrayList` / `Map` collections so `@template`-style code is also nice to write.
- Offering `lazyOf()` proxies on top of PHP 8.4's native lazy objects.

Install
-------

[](#install)

```
composer require tcds-io/php-better-generics
```

Single runtime dependency: [`phpstan/phpdoc-parser`](https://github.com/phpstan/phpdoc-parser) (zero deps of its own).

Typed collections
-----------------

[](#typed-collections)

```
use function Tcds\Io\Generic\listOf;
use function Tcds\Io\Generic\mapOf;

$users = listOf($alice, $bob, $carol);

$names = $users
    ->filter(fn (User $u) => $u->isActive())
    ->map(fn (User $u) => $u->name);

$byEmail = $users->indexedBy(fn (User $u) => $u->email);
// Map

$first = $users->first(fn (User $u) => $u->isAdmin());
$count = $users->count(fn (User $u) => $u->isActive());
```

`MutableArrayList` adds `push`, `pop`, `set`, `removeAt`, `clear`. `Map` implements `ArrayAccess` and `Countable`; `MutableMap` adds `put`, `putAll`, `remove`, `clear`.

Lazy proxies
------------

[](#lazy-proxies)

```
use function lazyOf;
use function lazyBufferOf;

// Single proxy: $user is fully typed as User; constructor only runs on first access.
$user = lazyOf(User::class, fn () => $userRepository->find($id));

// Buffered loader: collects keys, then loads in one batch when the buffer fills.
$loader = lazyBufferOf(
    User::class,
    fn (array $ids) => $userRepository->findMany($ids),
    maxBufferSize: 50,
);

$users = $orderIds->map(fn (string $orderId) => $loader->lazyOf($orderId));
// Each access fetches up to 50 users at once instead of N+1.
```

Generic-aware reflection
------------------------

[](#generic-aware-reflection)

Read the PHPDoc, get back resolved types.

```
use Tcds\Io\Generic\Reflection\ReflectionClass;

/** @template T */
class Collection {
    /** @return list */
    public function items(): array { /* ... */ }
}

/** @extends Collection */
class UserCollection extends Collection {}

$reflection = new ReflectionClass(UserCollection::class);

$type = $reflection->getMethod('items')->getReturnType();
// GenericReflectionType('list', [User::class])
// — `T` resolved through `@extends Collection`.
```

Supported out of the box:

- `@template T` and `@template T of Foo` (bounds parsed but not yet enforced)
- `@param`, `@return`, `@var`
- `@extends Foo`, `@implements Foo` — including transitive inheritance through PHP `extends`
- `@phpstan-type` aliases
- Generics, array shapes (`array{name: string}`), unions, intersections, nullables, `Foo[]`
- Short-name resolution through `use` statements (including `use A as B`, `use A\{B, C}`, grouped imports)
- `self`, `static`, `parent` resolution against the declaring class

Requirements
------------

[](#requirements)

- PHP 8.4+

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

[](#development)

```
composer install
composer tests   # cs:check + test:stan + test:unit
```

License
-------

[](#license)

MIT — see `composer.json`.

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance88

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Every ~55 days

Total

3

Last Release

61d ago

Major Versions

0.1.1 → 1.0.02026-05-03

### Community

Maintainers

![](https://www.gravatar.com/avatar/c8ac1821d71c0ddddcc3494a165dc40cfa3e759a467d8a00956ceeae4b833bb3?d=identicon)[thiagocordeiro](/maintainers/thiagocordeiro)

---

Top Contributors

[![thiagocordeiro](https://avatars.githubusercontent.com/u/1073649?v=4)](https://github.com/thiagocordeiro "thiagocordeiro (58 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tcds-io-php-better-generics/health.svg)

```
[![Health](https://phpackages.com/badges/tcds-io-php-better-generics/health.svg)](https://phpackages.com/packages/tcds-io-php-better-generics)
```

###  Alternatives

[phpdocumentor/reflection-docblock

With this component, a library can provide support for annotations via DocBlocks or otherwise retrieve information that is embedded in a DocBlock.

9.4k751.3M1.6k](/packages/phpdocumentor-reflection-docblock)[deptrac/deptrac

Deptrac is a static code analysis tool that helps to enforce rules for dependencies between software layers.

3.0k8.8M118](/packages/deptrac-deptrac)[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k11.2M100](/packages/dedoc-scramble)[phalcon/zephir

Zephir is a compiled high level language aimed to the creation of C-extensions for PHP

3.4k450.6k20](/packages/phalcon-zephir)[spatie/typescript-transformer

This is my package typescript-transformer

3957.8M26](/packages/spatie-typescript-transformer)[symfony/ai-platform

PHP library for interacting with AI platform provider.

521.4M289](/packages/symfony-ai-platform)

PHPackages © 2026

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