Provide insertItem ItemList method

Problem/Motivation

There is no method provided to insert an element into the middle of an ItemList.

Steps to reproduce

Add a Paragraphs field to a content type.
Create a node with several paragraphs added.
Programmatically insert a Paragraph into the middle of the EntityReferenceRevisionsFieldItemList.

Proposed resolution

Provide an insertItem method to ItemList .

It might go something like:

  /**
   * Inserts a new item to the list.
   *
   * @param integer $position
   *   The desired position of the new element to be added.
   * @param mixed $value
   *   The value of the new item.
   * @return \Drupal\Core\TypedData\TypedDataInterface 
   *   The item that was inserted.
   */
  public function insertItem(int $position, $value) {
    // Make a temporary sub-list.
    $definition = $this->getFieldDefinition();
    $name = $this->getName();
    $parent = $this->getParent();
    $tmp = new EntityReferenceRevisionsFieldItemList($definition, $name, $parent);

    // Append our items to the sub-list and insert our new element where needed.
    foreach ($this as $k => $v) {
      if ($k == $position) {
        $tmp->appendItem($value);
      }
      $tmp->appendItem($v->getValue());
    }

    $this->list = $tmp;
    return $this;
  }

This first pass is missing fault tree capture (e.g. position validation, etc).

Remaining tasks

• Add new method
• Write Test coverage
• Write Documentation
• Write Release note

API changes

Release notes snippet