Open-Source Testing · phpstan

phpstan-doctrine

phpstan-doctrine is a PHPStan extension that adds static type analysis for Doctrine ORM/ODM projects. It validates DQL queries, recognizes magic repository methods, infers query result types, and detects entity mapping errors without requiring a database.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/phpstan/phpstan-doctrine

672

GitHub stars

119

Forks

PHP

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	phpstan/phpstan-doctrine
Owner	phpstan
Primary language	PHP
License	MIT — OSI-approved
Stars	672
Forks	119
Open issues	96
Latest release	2.0.27 (2026-06-10)
Last updated	2026-07-08
Source	https://github.com/phpstan/phpstan-doctrine

What phpstan-doctrine is

Integrates with PHPStan to provide Doctrine-specific rule sets: DQL/QueryBuilder parsing and validation, magic method recognition on EntityRepository, entity field type checking against column definitions, query result type inference via DQL AST analysis, and integration with Doctrine proxy and metadata systems.

Quickstart

Get the phpstan-doctrine source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/phpstan/phpstan-doctrine.git2cd phpstan-doctrine3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Large Doctrine-heavy applications

Catch mapping errors, DQL syntax problems, and type mismatches between entities and queries at analysis time before runtime. Particularly valuable in codebases with many custom repositories and complex queries.

Type-safe repository patterns

Enforces correct usage of findBy*, findOneBy*, and countBy* magic methods with accurate entity field validation. Supports custom repository base classes with PHPStan type inference.

Query result type safety

Automatically infers result types from DQL queries and QueryBuilder expressions, enabling IDE autocomplete and catching type errors in downstream code that consumes query results.

Implementation considerations

Requires PHPStan as a dev dependency; configure via extension.neon or auto-register via phpstan/extension-installer.
DQL/QueryBuilder validation requires an objectManagerLoader (a PHP file that bootstraps and returns your Doctrine ObjectManager) to enable query parsing and type inference.
Custom Doctrine types must be registered via DoctrineTypeDescriptor implementations if your codebase uses non-standard type mappings.
Dead code detection integrates with PHPStan's core; requires entity properties to be correctly declared and mapped to avoid false positives.
Gedmo doctrine-extensions support is automatic for recognized annotations/attributes (Timestampable, Blameable, Slug, etc.); others may need custom configuration.

When to avoid it — and what to weigh

Non-Doctrine projects — This extension is solely for Doctrine ORM/ODM. Projects using other ORMs (Eloquent, Propel, custom mappers) will gain no benefit.
Query builders passed as method arguments — Dynamic QueryBuilder construction patterns (building queries in helper methods, loop-based assembly) cannot be statically analyzed. Complex dynamic queries will report as `mixed` unless rewritten.
Minimal static analysis needs — If your team relies primarily on runtime testing or does not use PHPStan, the overhead of configuration and rule maintenance will not justify the value.
Doctrine proxy incompatibility concerns — If native lazy objects are not enabled and your entity classes cannot use `final` keyword (architectural constraint), the proxy warnings from this extension may be noise rather than actionable.

License & commercial use

MIT License (MIT) permits commercial use, modification, and distribution with attribution. Standard open-source permissive license.

MIT license explicitly permits commercial use. No proprietary restrictions; however, verify your PHPStan and Doctrine dependencies also allow commercial use in your context. Requires review of your full dependency chain if deploying to regulated environments.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

This is a static analysis tool; it does not execute code and has no direct security-sensitive surface. Ensure objectManagerLoader file is trusted and only loaded during development (not in production). DQL parsing occurs statically and does not require database access. No known CVEs; review GitHub security advisories for any past disclosures.

Alternatives to consider

Psalm with Doctrine support

Another static analyzer with Doctrine plugins. Offers similar DQL validation and type inference but different rule ecosystem. Consider if already using Psalm in your codebase.

IDE plugins (PhpStorm Doctrine inspections)

Provides inline IDE-level Doctrine checks without explicit CLI setup. Lighter weight for small teams but less customizable and CI/CD integration requires separate tooling.

Runtime query logging and validation

Doctrine Debug Bar, query profilers, or custom middleware catch errors at runtime rather than statically. Complementary to static analysis but slower feedback loop and requires test coverage.

Software development agency

Build on phpstan-doctrine with DEV.co software developers

Integrate phpstan-doctrine into your static analysis pipeline to catch entity mapping errors, validate DQL queries, and enforce type safety across repositories and queries. Contact our team to plan your implementation.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

phpstan phpstan-symfony dbal

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing Application Development API Development Enterprise Software Talk to DEV.co

phpstan-doctrine FAQ

Do I need to run my database or configure a database connection for this extension to work?

No. DQL queries are parsed and analyzed statically using Doctrine's metadata system. However, an objectManagerLoader (a bootstrapped ObjectManager instance) must be provided for DQL validation to work; this does not require a live database connection.

Will this catch all Doctrine mapping errors?

It catches annotation/attribute parsing errors, field type mismatches, proxy-related issues, and invalid DQL. However, it is a static analysis tool and cannot validate runtime constraints (e.g., unique constraint logic), cascading behavior edge cases, or dynamic query patterns. Use in conjunction with integration tests.

Can I use this with a custom repository base class?

Yes. Configure `parameters.doctrine.ormRepositoryClass` or `odmRepositoryClass` in phpstan.neon to point to your base repository class. PHPStan will then recognize custom methods and properties defined in that class.

What versions of Doctrine and PHPStan are supported?

Not explicitly stated in the README. Check the project's composer.json, GitHub releases, or CHANGELOG for supported version ranges. Generally, recent versions of both are assumed.

Software developers & web developers for hire

From first prototype to production, DEV.co delivers software development services around tools like phpstan-doctrine. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source testing and beyond.

Ready to strengthen your Doctrine codebase?

Talk to DEV.co Schedule a Consultation