PHPackages amiut/phpstan-type-utilities - 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. amiut/phpstan-type-utilities ActivePhpstan-extension[Utility & Helpers](/categories/utility) amiut/phpstan-type-utilities ============================ PHPStan type utilities for inferring and reusing static array shapes from PHPDoc. 0.1.2(1mo ago)05MITPHPPHP ^7.4 || ^8.0CI passing Since May 2Pushed 1mo agoCompare [ Source](https://github.com/amiut/phpstan-type-utilities)[ Packagist](https://packagist.org/packages/amiut/phpstan-type-utilities)[ RSS](/packages/amiut-phpstan-type-utilities/feed)WikiDiscussions main Synced 1w ago READMEChangelog (3)Dependencies (2)Versions (4)Used By (0) PHPStan Type Utilities ====================== [](#phpstan-type-utilities) Warning This project is experimental and not stable. APIs may change without notice. [ ![package version](https://camo.githubusercontent.com/3b5d79f663f3ef7f1d3f2fe8e3dabccbb2092efb8ffab3ed5b0cd72d66b8d80f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616d6975742f7068707374616e2d747970652d7574696c69746965732e7376673f6c6162656c3d76657273696f6e) ](https://github.com/amiut/phpstan-type-utilities/releases) [![php version](https://camo.githubusercontent.com/02d675e7d17c3550fe3947f49707693f9ac8d21d0732ae4adbaa1186cf5f6e0a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f616d6975742f7068707374616e2d747970652d7574696c69746965732e7376673f636f6c6f723d62726f776e)](https://camo.githubusercontent.com/02d675e7d17c3550fe3947f49707693f9ac8d21d0732ae4adbaa1186cf5f6e0a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f616d6975742f7068707374616e2d747970652d7574696c69746965732e7376673f636f6c6f723d62726f776e) [![Packagist](https://camo.githubusercontent.com/31cd6bdc1287ff9840d200b46f80c54be6ea2c7490b9d6041d7d4c6129cffd70/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f616d6975742f7068707374616e2d747970652d7574696c6974696573)](https://camo.githubusercontent.com/31cd6bdc1287ff9840d200b46f80c54be6ea2c7490b9d6041d7d4c6129cffd70/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f616d6975742f7068707374616e2d747970652d7574696c6974696573) PHPStan Type Utilities is a set of opt-in PHPStan/PHPDoc type utilities for PHP projects. The package currently includes utilities for detecting callable return types and inferring static PHP array shapes. The goal is to bring a small, explicit, TypeScript-utility-types style workflow to PHPStan without turning the extension into a general type solver. The implementation is intentionally conservative. It infers PHP array literals as PHP array shapes only; it does not interpret arrays semantically or treat domain-specific array structures differently. Installation ------------ [](#installation) Install the package as a development dependency: ``` composer require --dev amiut/phpstan-type-utilities ``` The extension is registered automatically through Composer's PHPStan extension discovery. If your project does not use extension discovery, include it manually: ``` includes: - %currentWorkingDirectory%/vendor/amiut/phpstan-type-utilities/extension.neon ``` Use `%currentWorkingDirectory%` for manual includes. A plain relative include can break when another tool wraps your PHPStan config from a generated temporary config file, which can make PHPStan behave as if the extension is not installed. Features -------- [](#features) ### `@phpstan-infer-return` [](#phpstan-infer-return) Infer the exact static array shape of a function or method from its return expression. ``` /** @phpstan-return array @phpstan-infer-return */ public function options(): array { return [ 'enabled' => true, 'limit' => 100, 'label' => 'default', ]; } ``` PHPStan receives the inferred return type: ``` array{enabled: bool, limit: int, label: string} ``` This suppresses PHPStan's generic missing iterable value type error when the shape can be inferred. If inference fails, the extension reports a focused `arrayTypeInference.missingType` diagnostic. [Read the `@phpstan-infer-return` docs](docs/infer-return.md) ### `ReturnType` [](#returntypecallable) Detect and reuse the return type of a function or method as a PHPDoc type. `ReturnType` works with any callable return type PHPStan can resolve — from a native declaration, PHPDoc, another PHPStan extension, or `@phpstan-infer-return`. The main benefit is avoiding duplicated array shape annotations. Instead of copying an `array{...}` PHPDoc in every place that consumes it, point `ReturnType` at the single method that defines it: ``` final class PluginConfig { /** @return array{enabled: bool, limit: int, label: string} */ public function defaults(): array { return ['enabled' => true, 'limit' => 100, 'label' => 'default']; } } /** * @phpstan-type PluginDefaults \ReturnType */ final class PluginService { /** * @param array $config * @phpstan-param PluginDefaults $config */ public function boot(array $config): void { // PHPStan knows $config['enabled'] is bool, $config['limit'] is int, etc. } } ``` `PluginDefaults` resolves to: ``` array{enabled: bool, limit: int, label: string} ``` When the `defaults()` signature changes, all consumers pick up the updated type automatically — without touching their own annotations. #### Combined with `@phpstan-infer-return` [](#combined-with-phpstan-infer-return) When a method uses `@phpstan-infer-return`, its return type becomes a precise static array shape, and `ReturnType` can reference it like any other documented type. This is the most common pattern: define the shape once via inference, reuse it everywhere: ``` /** * @phpstan-type Options \ReturnType */ final class Config { /** @phpstan-return array @phpstan-infer-return */ public function defaults(): array { return [ 'enabled' => true, 'limit' => 100, ]; } /** * @param array $options * @phpstan-param Options $options */ public function apply(array $options): void { // PHPStan catches type errors on $options['enabled'] and $options['limit'] } } ``` `Options` resolves to the same inferred type as `defaults()`: ``` array{enabled: bool, limit: int} ``` #### Referencing a function [](#referencing-a-function) ``` /** * @phpstan-return array @phpstan-infer-return */ function defaultHeaders(): array { return [ 'Content-Type' => 'application/json', 'Accept' => 'application/json', ]; } /** * @phpstan-type Headers \ReturnType */ final class HttpClient { /** * @param array $headers * @phpstan-param Headers $headers */ public function withHeaders(array $headers): void {} } ``` #### Supported syntax [](#supported-syntax) - `\ReturnType` - `\ReturnType` - `\ReturnType` - `\ReturnType` Nested inferred calls are supported when the target is statically resolvable. `ReturnType` always reuses the callable's literal PHP return type. If a method returns a JSON-schema definition array, `\ReturnType` resolves to the PHP shape of that schema-definition array. It does not convert the JSON schema into a separate data shape. PHPStan-powered IDE hovers should show the same resolved types PHPStan sees on the command line when the extension is active. The optional IDE stubs only reduce editor noise in tools like Intelephense or PHPStorm; those tools do not execute PHPStan's custom type resolver by themselves. [Read the `ReturnType` docs](docs/return-type.md) License ------- [](#license) MIT ### Health Score 34 — LowBetter than 75% of packages Maintenance92 Actively maintained with recent releases Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity30 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. ### Release Activity Cadence Every ~0 days Total 3 Last Release 38d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/03022726ba58e44dde19fcf63cc0a50f8e4ec513950bb87e3a4f2fd40655d40b?d=identicon)[amiut7](/maintainers/amiut7) --- Top Contributors [![amiut](https://avatars.githubusercontent.com/u/25235298?v=4)](https://github.com/amiut "amiut (10 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/amiut-phpstan-type-utilities/health.svg) ``` [![Health](https://phpackages.com/badges/amiut-phpstan-type-utilities/health.svg)](https://phpackages.com/packages/amiut-phpstan-type-utilities) ``` ### Alternatives [ticketswap/phpstan-error-formatter A minimalistic error formatter for PHPStan 87670.5k52](/packages/ticketswap-phpstan-error-formatter)[slam/phpstan-extensions Slam extension of phpstan 712.5M77](/packages/slam-phpstan-extensions)[tomasvotruba/ctor Prefer constructor over always called setters 1524.9k19](/packages/tomasvotruba-ctor)[ergebnis/rector-rules Provides rules for rector/rector. 10226.6k48](/packages/ergebnis-rector-rules)[shopsys/coding-standards Coding standards definition compatible with PSR-2 20276.8k20](/packages/shopsys-coding-standards)[johnbillion/wp-compat PHPStan extension to help verify that your PHP code is compatible with a given version of WordPress 25152.4k15](/packages/johnbillion-wp-compat) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)