Interfaces mis @throw annotations #6274

New Issue

admin · 2026-01-22T15:30:00+01:00

admin commented

2026-01-22 15:30:00 +01:00

Originally created by @hansbogert on GitHub (Jul 31, 2019).

Bug Report

Q	A
BC Break	no
Version	2.6.3

Summary

Interfaces of, e.g., EntityManagerInterface do not include @throw annotations.

Current behavior

This causes IDEs to not notice that for example calls to EntityManagerInterface::flush may cause exceptions.

How to reproduce

Reference EntityManagerInterface in an IDE like PhpStorm or other, and have the following snippet

function foo(EntityManagerInterface $em) {
  $em->flush();
}

Expected behavior

I expect the IDE to be able to tell, based on docblocks of the Doctrine library, that we should catch, (or re-throw) the exceptions which can occur.

Originally created by @hansbogert on GitHub (Jul 31, 2019). ### Bug Report  | Q | A |------------ | ------ | BC Break | no | Version | 2.6.3 #### Summary Interfaces of, e.g., `EntityManagerInterface` do not include `@throw` annotations. #### Current behavior This causes IDEs to not notice that for example calls to `EntityManagerInterface::flush` may cause exceptions. #### How to reproduce Reference `EntityManagerInterface` in an IDE like PhpStorm or other, and have the following snippet ```php function foo(EntityManagerInterface $em) { $em->flush(); } ``` #### Expected behavior I expect the IDE to be able to tell, based on docblocks of the Doctrine library, that we should catch, (or re-throw) the exceptions which can occur.

admin added the Documentation label 2026-01-22 15:30:00 +01:00

admin commented

2026-01-22 15:30:00 +01:00

@Ocramius commented on GitHub (Jul 31, 2019):

Documenting all @throws is not possible here, since there are multiple un-checked exception types upstream from that interface (in implementations).

You can gladly suggest those that are directly thrown in the EntityManager (implementation).

Related: https://github.com/doctrine/orm/issues/7780

@Ocramius commented on GitHub (Jul 31, 2019): Documenting all `@throws` is not possible here, since there are multiple un-checked exception types upstream from that interface (in implementations). You can gladly suggest those that are directly thrown in the `EntityManager` (implementation). Related: https://github.com/doctrine/orm/issues/7780

admin commented

2026-01-22 15:30:00 +01:00

@hansbogert commented on GitHub (Jul 31, 2019):

Well if you mean by unchecked exceptions, runtime exceptions, then I totally agree.

So basically we'd want to add

    /**
     * @throws \Doctrine\ORM\OptimisticLockException If a version check on an entity that
     *         makes use of optimistic locking fails.
     * @throws ORMException
     * @throws UniqueConstraintViolationException
     */

right?

@hansbogert commented on GitHub (Jul 31, 2019): Well if you mean by unchecked exceptions, runtime exceptions, then I totally agree. So basically we'd want to add ```php /** * @throws \Doctrine\ORM\OptimisticLockException If a version check on an entity that * makes use of optimistic locking fails. * @throws ORMException * @throws UniqueConstraintViolationException */ ``` right?

admin commented

2026-01-22 15:30:01 +01:00

@Ocramius commented on GitHub (Jul 31, 2019):

Something like that, but please look at the current 3.x work.

@Ocramius commented on GitHub (Jul 31, 2019): Something like that, but please look at the current 3.x work.

admin commented

2026-01-22 15:30:01 +01:00

@Ocramius commented on GitHub (Jul 31, 2019):

See https://github.com/doctrine/orm/pull/6743

@Ocramius commented on GitHub (Jul 31, 2019): See https://github.com/doctrine/orm/pull/6743

admin commented

2026-01-22 15:30:02 +01:00

@derrabus commented on GitHub (May 11, 2022):

We're doing some housekeeping on the 3.0.0 milestone. Since nobody seems to be actively working on this topic I'm removing this PR from the 3.0.0 milestone.

That being said, the issue does not really look actionable at the moment. I'd be happy to discuss and merge any PR adding reasonable @throws annotations though. Also, if we take this topic seriously, we should think about some kind of tooling that tells us about correctness and completenes of such annotations.

@derrabus commented on GitHub (May 11, 2022): We're doing some housekeeping on the 3.0.0 milestone. Since nobody seems to be actively working on this topic I'm removing this PR from the 3.0.0 milestone. That being said, the issue does not really look actionable at the moment. I'd be happy to discuss and merge any PR adding reasonable `@throws` annotations though. Also, if we take this topic seriously, we should think about some kind of tooling that tells us about correctness and completenes of such annotations.

admin commented

2026-01-22 15:30:02 +01:00

@greg0ire commented on GitHub (Nov 16, 2022):

@morozov mentioned https://phpstan.org/blog/bring-your-exceptions-under-control in https://github.com/doctrine/dbal/pull/5777, we might want to look into it.

@greg0ire commented on GitHub (Nov 16, 2022): @morozov mentioned https://phpstan.org/blog/bring-your-exceptions-under-control in https://github.com/doctrine/dbal/pull/5777, we might want to look into it.

admin referenced this issue

2026-01-22 16:05:53 +01:00

[PR #6274] Fixing #5887 - lazy loading of one-to-one relationship with custom id object #9930

Sign in to join this conversation.