Problem/Motivation

If you define an entity reference field as a base field in code, and the entity type that the field references doesn't exist, you get an exception about the missing entity type. But the exception message doesn't tell you anything about the field.

This means that a developer who has messed up their field definitions, or who hasn't enabled all the right modules in a Kernel test, doesn't know where to look for the problem.

Steps to reproduce

Either:
- Define an entity reference base field on an entity type with a made-up referenced entity type
- Create a kernel test, enable a module that provides and entity type with an entity reference base field, but don't enable the module that provides the referenced entity type

You get this exception:

> Drupal\Component\Plugin\Exception\PluginNotFoundException: The "taxonomy_term" entity type does not exist.

Proposed resolution

EntityReferenceItem should catch this exception and throw a FieldException instead, stating the location of the problem, e.g.:

> Drupal\Core\Field\FieldException: Field 'foo' on entity type 'my_entity' references a target entity type 'taxonomy_term' which does not exist.

Remaining tasks

Do it.

Update any tests that expect the exception.

User interface changes

None.

API changes

A different type of exception is now thrown.

Data model changes

None.

Release notes snippet

Issue fork drupal-3174924

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

Comments

joachim created an issue. See original summary.

joachim’s picture

Something like this would do the job.

kiwimind’s picture

+++ b/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php
@@ -4,12 +4,14 @@
+use Drupal\Component\Plugin\Exception\PluginNotFoundException;

While I realise that this hasn't made it into official coding standards yet, isn't it good practice to alphabetise the use statements?

https://www.drupal.org/project/coding_standards/issues/1624564

Otherwise, good job. 👍

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

joachim’s picture

kiwimind’s picture

Status: Needs review » Reviewed & tested by the community

Nice quality of life fix, considerably more useful than existing. Thanks.

catch’s picture

Status: Reviewed & tested by the community » Needs review
+++ b/core/lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php
@@ -114,7 +116,17 @@ public static function mainPropertyName() {
-    $target_type_info = \Drupal::entityTypeManager()->getDefinition($target_type);
+    try {
+      $target_type_info = \Drupal::entityTypeManager()->getDefinition($target_type);
+    }
+    catch (PluginNotFoundException $e) {
+      throw new FieldException(sprintf("Field '%s' on entity type '%s' references a target entity type '%s' which does not exist.",
+        $field_definition->getName(),

Minor but it would be good to add a @throws to the phpdoc. However, it's currently doing @inheritdoc and I'm not sure it's worth breaking that to add the one line... what do you think?

joachim’s picture

The Drupal documentation standards aren't clear about whether @throws documents that the *actual* function's code throws an exception, or whether it should also document that an exception could be thrown by something else that the function calls.

I'd argue for the latter, because as a consumer of a function, you don't care what it does internally: you just want to know that calling foo() could cause an exception to be thrown.

In which case, the interface definition of schema() should document that it can throws exceptions, and it's an existing documentation bug that should be fixed as a separate issue.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

catch’s picture

#8 is reasonable - let's open a follow-up to improve the ::schema() docs.

Looks like it ought to be possible to add some test coverage here.

joachim’s picture

> In which case, the interface definition of schema() should document that it can throws exceptions, and it's an existing documentation bug that should be fixed as a separate issue.

Filed #3268120: FieldItemInterface::schema() should document that it can throw multiple exceptions for that.

Rerolled the patch for 9.4.

ranjith_kumar_k_u’s picture

StatusFileSize
new1.54 KB
new1.24 KB

Fixed CS errors.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

joachim’s picture

Status: Needs review » Reviewed & tested by the community

Looks good!

catch’s picture

Category: Feature request » Task
Status: Reviewed & tested by the community » Needs work
Issue tags: +Needs tests

Could still use some test coverage.

rakhi soni’s picture

Kindly review patch for version 9.5x,,

joachim’s picture

Status: Needs review » Needs work

Still needs work.

And also, latest patch has added some indentation errors.

sourabhjain’s picture

Assigned: Unassigned » sourabhjain

I will work on this.

sourabhjain’s picture

Assigned: sourabhjain » Unassigned
StatusFileSize
new1.64 KB
new911 bytes

I have resolved the patch #17 indentation issues.
Please review.

sourabhjain’s picture

Status: Needs work » Needs review
joachim’s picture

bnjmnm’s picture

Patch #13 applies fine to 9.5.x, there was no reason for the reroll in #17. The only difference is changed indentations that fail PHP coding standards. Removing credit.

kiwimind’s picture

Can I please clarify: you're removing credit from everyone that hasn't submitted what you deem a relevant patch?

I understand that we need to be careful of people gaming the system, however all too often I see reviewers and commenters on issues that don't receive credit (yes, myself included on this issue).

Arguably a patch that does nothing but introduce errors without moving the code forwards should be considered, but have the contributions that Catch and I made not been valuable to the conversation?

I believe that this can only harm the community as there is a chance that people may not continue reviewing if they're not recognised for it.

bnjmnm’s picture

Can I please clarify: you're removing credit from everyone that hasn't submitted what you deem a relevant patch?

I will remove credit for patches that claim to be rerolls when a reroll wasn't actually needed. I suppose that means I don't "deem it relevant", but that phrasing makes it seem like a more subjective decision than it is. #17 claims to be a reroll of #13, despite that patch not needing a reroll. The testbot proves that the patch in #13 applies to 9.5 with all tests passing, so the reroll that followed it was clearly not needed.

I understand that we need to be careful of people gaming the system, however all too often I see reviewers and commenters on issues that don't receive credit (yes, myself included on this issue).

Credit isn't actually granted until an issue is committed, and committers will make sure to add anyone who left useful comments. The state of the credit checkboxes before a commit is not indicative of anyone being denied credit.

Committers rarely miss adding people who added productive comments before the commit. Because providing an attachment automatically switches the credit checkbox "on" for that user, and the uploads can look similar to legitimate contributions, it's easier for a committer to miss the not-legitimate contributions. I preemptively remove credit so ensure it's not missed during the commit process, and so the user is aware they're not properly contributing to the issue so they can change their behavior moving forward.

Arguably a patch that does nothing but introduce errors without moving the code forwards should be considered, but have the contributions that Catch and I made not been valuable to the conversation?

I didn't deny you or Catch credit. Is there a wording in #23 that would have made it clearer that this was specific to just the user that uploaded an unnecessary reroll?

kiwimind’s picture

Thank you for the clarification, appreciate your response.

Credit isn't actually granted until an issue is committed, and committers will make sure to add anyone who left useful comments.

Committers rarely miss adding people who added productive comments before the commit.

This has not been my experience, which is why I raised the question about the comments and reviews that have been left so far. In my experience people that don't add patches are more often than not omitted from being credited. I realise that without a patch people are not automatically added to the credit list, however I (incorrectly it seems) assumed that if you were doing a tidy up in the credits that the list might have changed. I apologise if I've misconstrued.

For those of us that aren't able to spend as much time in the issue queues as we'd like, the odd credit here and there does have meaning and I've missed out on a good amount of credits when not adding patches.

Thanks for your time, appreciate it.

bnjmnm’s picture

@kiwimind If you (or anyone reading this, TBH) see a completed issue you believe you should have received credit on, you can contact the committer on Drupal Slack. There's a chance it was a mistake, and even if it wasn't they can provide additional explanation. As careful as I try to be when committing, I can sometimes miss someone, so I appreciate when someone alerts me to that.

kiwimind’s picture

Thank you for your gracious reply. Realised I've hijacked this issue now, apologies.

I'll bear that in mind for future reference.

All the best.

joachim’s picture

Yes, a bit ;) Could either of you take a couple of minutes to review this please?

sourabhjain’s picture

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

joachim’s picture

Rebased on 10.1.x.

shubham chandra’s picture

StatusFileSize
new3.4 KB

Added patch against #22 in Drupal 10.1.x

joachim’s picture

@Shubham Chandra we're using an MR on this issue, not patches. And at a glance, the patch you've uploaded looks identical to the current state of the MR?

smustgrave’s picture

Status: Needs review » Reviewed & tested by the community

Can confirm that #34 is a copy of the MR minus the index numbers.

But tested the MR.
The tests fail without the fix and pass with the fix.
Looks like a great update to have and will be useful!

Status: Reviewed & tested by the community » Needs work

The last submitted patch, 34: 3174924-34.patch, failed testing. View results

smustgrave’s picture

Status: Needs work » Reviewed & tested by the community

Putting back as the MR was reviewed not the patch

xjm’s picture

Removing credit for the unnecessary patch in #34.

Looking back, we haven't had a clean test-only run proving the test coverage. I'm opening a separate MR branch for that.

xjm’s picture

Title: throw a better exception when a reference field can't find the target entity type » Throw a better exception when a reference field can't find the target entity type

xjm’s picture

Saving issue credits as follows according to the core issue credit guidelines:

  • @joachim, for a useful original issue report and work on the patch
  • @sourabhjain, for a necessary coding standards fix
  • @ranjith_kumar_k_u, also for a necessary coding standards fix
  • @kiwimind for a useful suggestion to alphabetize the use statements, which is indeed a sort-of-coding-standard for core and a point of feedback I would have given myself
  • @catch, for code review
  • @bnjmnm, for mentoring
xjm’s picture

Status: Reviewed & tested by the community » Needs work

This looks pretty good, except we also need to update the @throws documentation for the method. Thanks everyone!

joachim’s picture

Status: Needs work » Needs review

Done, but bear in mind that the @throw docs for schema() need more detail anyway: #3268120: FieldItemInterface::schema() should document that it can throw multiple exceptions.

smustgrave’s picture

StatusFileSize
new4.09 KB

Removing credit from myself as I just rebased to see if the tests passed, will let the committer decide to add credit back :)

The changes look good to me. The changes requested by @xjm to be addressed.

Unfortunately this seems to have been bitten by the random composer error so the tests won't run.

Uploading a patch for the tests to run

For any failures please do not reroll this issue is being worked on in the MR this is just for tests.

smustgrave’s picture

Status: Needs review » Reviewed & tested by the community
Issue tags: +Needs Review Queue Initiative

Seeing green.

Not sure this is blocked until the composer issue is resolved.

xjm’s picture

Issue tags: +Needs change record

I wonder if we should have a change record for this? Someone could have code handling the old plugin exception.

smustgrave’s picture

Issue tags: -Needs change record

Took a crack at the CR.

xjm’s picture

Status: Reviewed & tested by the community » Fixed

Make a few small edits to the CR.

This looks good to me now, thanks! Committed to 10.1.x and published the CR. Since a change to a thrown exception is a disruptive change, I did not backport it to the production branches.

papagrande’s picture

@smustgrave @xjm Sorry to be nitpicky and pedantic, but don’t you need a comma before “which” in the error message?
https://www.thepunctuationguide.com/comma.html#settingoffnonrestrictivei...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.