DDC-473: Inadequate description for @MappedSuperclass in Annotations Reference #589

New Issue

admin · 2026-01-22T12:43:32+01:00

admin commented

2026-01-22 12:43:32 +01:00

Originally created by @doctrinebot on GitHub (Mar 25, 2010).

Originally assigned to: @jwage on GitHub.

Jira issue originally created by user @hobodave:

See: http://www.doctrine-project.org/documentation/manual/20/en/annotations-reference#annmappedsuperclass

{quote}
@MappedSuperclass

An mapped superclass is an abstract or concrete class that provides persistent entity state and mapping information for its subclasses, but which is not itself an entity. This annotation is specified on the Class docblock and has no additional attributes.
{quote}

This doesn't adequately communicate how to use it. It took me several minutes of failing before I downloaded the PDF and did a search for @MappedSuperclass to find an example of how it's used.

Specifically the following were unclear:

Is this defined on the superclass or on the children classes?
If it's defined on the child classes, does it take parameters? The name of the super class?
It was not at all apparent to me that it was mutually exclusive with the @Entity tag

Originally created by @doctrinebot on GitHub (Mar 25, 2010). Originally assigned to: @jwage on GitHub. Jira issue originally created by user @hobodave: See: http://www.doctrine-project.org/documentation/manual/2*0/en/annotations-reference#ann*mappedsuperclass {quote} @MappedSuperclass An mapped superclass is an abstract or concrete class that provides persistent entity state and mapping information for its subclasses, but which is not itself an entity. This annotation is specified on the Class docblock and has no additional attributes. {quote} This doesn't adequately communicate how to use it. It took me several minutes of failing before I downloaded the PDF and did a search for @MappedSuperclass to find an example of how it's used. Specifically the following were unclear: - Is this defined on the superclass or on the children classes? - If it's defined on the child classes, does it take parameters? The name of the super class? - It was not at all apparent to me that it was mutually exclusive with the @Entity tag

admin added the Improvement label 2026-01-22 12:43:32 +01:00

admin closed this issue

2026-01-22 12:43:33 +01:00

admin commented

2026-01-22 12:43:34 +01:00

@doctrinebot commented on GitHub (Mar 25, 2010):

Comment created by @hobodave:

Apparently it's also incompatible with several other tag as well.

I thought it made sense to try the following and see if the @InheritanceType and @Discriminator___ tags would apply to the children classes:

/****
 * @MappedSuperclass
 * @InheritanceType("SINGLE_TABLE")
 * @DiscriminatorColumn(name="type", type="string")
 * @DiscriminatorMap({"User" = "User", "Group" = "Group"})
 */
abstract class Principal

But apparently this flags D2 to treat it as an Entity anyway, resulting in the following error:

PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'sentact5.principal'

@doctrinebot commented on GitHub (Mar 25, 2010): Comment created by @hobodave: Apparently it's also incompatible with several other tag as well. I thought it made sense to try the following and see if the @InheritanceType and @Discriminator___ tags would apply to the children classes: ``` /**** * @MappedSuperclass * @InheritanceType("SINGLE_TABLE") * @DiscriminatorColumn(name="type", type="string") * @DiscriminatorMap({"User" = "User", "Group" = "Group"}) */ abstract class Principal ``` But apparently this flags D2 to treat it as an Entity anyway, resulting in the following error: ``` PDOException: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'sentact5.principal' ```

admin commented

2026-01-22 12:43:35 +01:00

@doctrinebot commented on GitHub (Mar 28, 2010):

Comment created by @beberlei:

I updated the documentation, the question is if we should check for the mapped superclass attribute and throw exceptions if other entity level annotations are specified.

@doctrinebot commented on GitHub (Mar 28, 2010): Comment created by @beberlei: I updated the documentation, the question is if we should check for the mapped superclass attribute and throw exceptions if other entity level annotations are specified.

admin commented

2026-01-22 12:43:35 +01:00

@doctrinebot commented on GitHub (Apr 15, 2010):

Comment created by romanb:

A mapped superclass has not many restrictions and these are mentioned in the docs (i.e. only unidirectional associations), what David mentions above should work, if it doesnt its a bug, I think DDC-511 looks like that same issue.

@doctrinebot commented on GitHub (Apr 15, 2010): Comment created by romanb: A mapped superclass has not many restrictions and these are mentioned in the docs (i.e. only unidirectional associations), what David mentions above should work, if it doesnt its a bug, I think [DDC-511](http://www.doctrine-project.org/jira/browse/DDC-511) looks like that same issue.

admin commented

2026-01-22 12:43:37 +01:00

@doctrinebot commented on GitHub (Apr 15, 2010):

Comment created by romanb:

David,

@"Is this defined on the superclass or on the children classes?"

It doesnt matter. A @MappedSuperclass can be anywhere in an inheritance hierarchy and it always does the same thing, inherit its mapping information to subclasses (but its not itself an entity). The docs say:

Mapped superclasses, just as regular, non-mapped classes, can appear in the middle of an otherwise mapped inheritance hierarchy (through Single Table Inheritance or Class Table Inheritance).

as well as

Entities support inheritance, polymorphic associations, and polymorphic queries. Both abstract and concrete classes can be entities. Entities may extend non-entity classes as well as entity classes, and non-entity classes may extend entity classes.

So entities, mapped superclasses and plain non-mapped classes can appear mixed in an inheritance hierarchy. Nevertheless all the classes in a hierarchy that are entities must use 1 inheritance strategy, you can not mix inheritance mapping strategies in a single class hierarchy.

@"If it's defined on the child classes, does it take parameters? The name of the super class?"

No, it doesnt. The docs dont mention any parameters either which is correct.

@"It was not at all apparent to me that it was mutually exclusive with the @Entity tag"

OK, that needs to be made clearer in the docs then.

@doctrinebot commented on GitHub (Apr 15, 2010): Comment created by romanb: David, @"Is this defined on the superclass or on the children classes?" It doesnt matter. A @MappedSuperclass can be anywhere in an inheritance hierarchy and it always does the same thing, inherit its mapping information to subclasses (but its not itself an entity). The docs say: ``` Mapped superclasses, just as regular, non-mapped classes, can appear in the middle of an otherwise mapped inheritance hierarchy (through Single Table Inheritance or Class Table Inheritance). ``` as well as ``` Entities support inheritance, polymorphic associations, and polymorphic queries. Both abstract and concrete classes can be entities. Entities may extend non-entity classes as well as entity classes, and non-entity classes may extend entity classes. ``` So entities, mapped superclasses and plain non-mapped classes can appear mixed in an inheritance hierarchy. Nevertheless all the classes in a hierarchy that are entities must use 1 inheritance strategy, you can not mix inheritance mapping strategies in a single class hierarchy. @"If it's defined on the child classes, does it take parameters? The name of the super class?" No, it doesnt. The docs dont mention any parameters either which is correct. @"It was not at all apparent to me that it was mutually exclusive with the @Entity tag" OK, that needs to be made clearer in the docs then.

admin commented

2026-01-22 12:43:37 +01:00

@mpdude commented on GitHub (Jan 16, 2023):

I think the documentation as of today addresses all the items raised here, so we should close this.

(cc @greg0ire )

@mpdude commented on GitHub (Jan 16, 2023): I think the documentation as of today addresses all the items raised here, so we should close this. (cc @greg0ire )

admin referenced this issue

2026-01-22 15:59:50 +01:00

[PR #589] [MERGED] Hotfix for DDC-2230 #8414

admin referenced this issue

2026-01-22 15:59:51 +01:00

[PR #589] Hotfix for DDC-2230 #8418

Sign in to join this conversation.