Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
Looking at the code in MigrateExecutable, it looks like MigrateDestinationInterface::import() can throw a MigrateException.
Furthermore, while simply throwing a MigrateException causes the row to be considered to have failed, MigrateException's constructor allows a MigrateIdMapInterface status constant to be passed, so a destination plugin can do this to skip a row:
throw new MigrateException("My message.", 0, NULL, MigrationInterface::MESSAGE_ERROR, MigrateIdMapInterface::STATUS_IGNORED);
This should be documented in MigrateDestinationInterface::import().
Steps to reproduce
Proposed resolution
Remaining tasks
User interface changes
API changes
Data model changes
Release notes snippet
Issue fork drupal-3247039
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:
changes
Comments
Comment #3
joachim CreditAttribution: joachim at Factorial GmbH commentedComment #4
quietone CreditAttribution: quietone as a volunteer commented@joachim, thanks for the MR.
Looking at the documentation for other @throws in core I find that many (or most?) begin with 'Thrown when ...'. I'd like to change to that form, it also reads better to me. Maybe this "Thrown when there is a problem importing the row." And instead of using the possessive form in the third sentence would this work? "However, any \Drupal\migrate\Plugin\MigrateIdMapInterface status constant can be set using the $status parameter of \Drupal\migrate\MigrateException." Or something like that?
Comment #5
quietone CreditAttribution: quietone as a volunteer commentedAdding tag for migrate maintainers
Comment #6
joachim CreditAttribution: joachim at Factorial GmbH commentedThanks for the review.
The documentation standards at https://www.drupal.org/docs/develop/standards/api-documentation-and-comm... say to use a complete sentence, so I don't think starting the sentence with 'Thrown when...' is right.
I've updated the bit about the parameter as suggested.
Comment #7
quietone CreditAttribution: quietone as a volunteer commented@joachim, thank you. I didn't know that it was supposed to be a complete sentence. And thanks for removing the possessive form.
I have reread the changed documentation and think it is good to go now.
Thanks!
Comment #9
alexpottCommitted and pushed 5592a5a5467 to 10.0.x and 5b9b5be27c3 to 9.4.x and 03d919b09d6 to 9.3.x. Thanks!