entities – How to handle appendItem() when a list is full?

I’m creating a custom JSON:API Resource to store push notifications tokens.

The user account field where the tokens are stored has a limit of 5 items.

I am using appendItem() to add the value to field.

However, if the field already has 5 values, then appendItem() does nothing. In this case, instead of doing nothing, I want to bump the first item (the value saved first) from the array and then move all the other values up a place (last in last out).

I can code this myself but it occurred to me that this may be something Drupal already provides but I just don’t know enough about the API to figure out where to look for it. Does Drupal provide some way to handle multi-value field values when the limit on the number of values has been reached?

Here’s my code so far:

// Make sure we have a real token.
if (strlen($push_token) >= 100) {

  // Generate an array of the existing token values.
  $existing_tokens = $current_user->get('field_text_token_push')->getValue();
  $token_values = ();
  foreach($existing_tokens as $existing_token) {
    $token_values() = $existing_token('value');

  // Check whether the token already exists.
  if (in_array($push_token, $token_values)) {
    $this->loggerFactory->notice("Push token: Did not add token for UID @uid because it already exists.", (
      '@uid' => $uid,
    $return_bool = TRUE;
  } else {
    // Add the token.
    // Todo: If we have reached the field limit, automatically remove the earliest value and replace with the new value.
    $this->loggerFactory->notice("Push token: Added token for UID @uid.", (
      '@uid' => $uid,
    $return_bool = TRUE;