core/lib/Drupal/Core/Config/Action/Plugin/ConfigAction/Deriver/SimpleConfigArrayDeriver.php

+<?php
+
+declare(strict_types=1);
+
+namespace Drupal\Core\Config\Action\Plugin\ConfigAction\Deriver;
+
+use Drupal\Component\Plugin\Derivative\DeriverBase;
+use Drupal\Core\StringTranslation\StringTranslationTrait;
+
+/**
+ * Generates derivatives for simpleConfigArray config action.
+ *
+ * @internal
+ *   This API is experimental.
+ */
+final class SimpleConfigArrayDeriver extends DeriverBase {
+
+  use StringTranslationTrait;
+
+  /**
+   * {@inheritdoc}
+   */
+  public function getDerivativeDefinitions($base_plugin_definition): array {
+    $this->derivatives['append'] = [
+      'admin_label' => $this->t('Append values to an array in simple config'),
+      'function' => 'array_push',
+    ] + $base_plugin_definition;
+
+    $this->derivatives['prepend'] = [
+      'admin_label' => $this->t('Prepend values to an array in simple config'),
+      'function' => 'array_unshift',
+    ] + $base_plugin_definition;
+
+    $this->derivatives['splice'] = [
+      'admin_label' => $this->t('Splice values into an array in simple config'),
+      'function' => 'array_splice',
+    ] + $base_plugin_definition;
+
+    return parent::getDerivativeDefinitions($base_plugin_definition);
+  }
+
+}

core/lib/Drupal/Core/Config/Action/Plugin/ConfigAction/SimpleConfigArray.php

+<?php
+
+declare(strict_types=1);
+
+namespace Drupal\Core\Config\Action\Plugin\ConfigAction;
+
+use Drupal\Core\Config\Action\Attribute\ConfigAction;
+use Drupal\Core\Config\Action\ConfigActionException;
+use Drupal\Core\Config\Action\ConfigActionPluginInterface;
+use Drupal\Core\Config\Action\Plugin\ConfigAction\Deriver\SimpleConfigArrayDeriver;
+use Drupal\Core\Config\Config;
+use Drupal\Core\Config\ConfigFactoryInterface;
+use Drupal\Core\Config\ConfigManagerInterface;
+use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
+use Symfony\Component\DependencyInjection\ContainerInterface;
+
+/**
+ * @internal
+ *   This API is experimental.
+ */
+#[ConfigAction(
+  id: 'simpleConfigArray',
+  deriver: SimpleConfigArrayDeriver::class,
+)]
+final class SimpleConfigArray implements ConfigActionPluginInterface, ContainerFactoryPluginInterface {
+
+  public function __construct(
+    private readonly ConfigFactoryInterface $configFactory,
+    private readonly ConfigManagerInterface $configManager,
+    private readonly string $function,
+    private readonly string $pluginId,
+  ) {}
+
+  /**
+   * {@inheritdoc}
+   */
+  public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition): static {
+    return new static(
+      $container->get(ConfigFactoryInterface::class),
+      $container->get(ConfigManagerInterface::class),
+      $plugin_definition['function'],
+      $plugin_id,
+    );
+  }
+
+  /**
+   * {@inheritdoc}
+   */
+  public function apply(string $configName, mixed $value): void {
+    if ($this->configManager->getEntityTypeIdByName($configName)) {
+      throw new ConfigActionException('The ' . $this->pluginId . ' config action cannot be used on configuration entities.');
+    }
+
+    $config = $this->configFactory->getEditable($configName);
+    if ($config->isNew()) {
+      throw new ConfigActionException("Config $configName cannot be updated because it does not exist.");
+    }
+
+    assert(is_array($value));
+    $values = array_is_list($value) ? $value : [$value];
+    foreach ($values as $value) {
+      $this->applySingle($config, $value);
+    }
+    $config->save();
+  }
+
+  /**
+   * Updates a single array property in a config object.
+   *
+   * @param \Drupal\Core\Config\Config $config
+   *   The config object being updated.
+   * @param array $value
+   *   An associative array containing:
+   *   - `property`: The property path to update in the config object.
+   *   - `values`: An array of values to append or prepend to the property, if
+   *     this action is appending or prepending.
+   *   - ... Named arguments to pass to `array_splice()`, if this action is
+   *    splicing into the property's value.
+   */
+  private function applySingle(Config $config, array $value): void {
+    if (empty($value['property'])) {
+      throw new ConfigActionException('A property path must be passed to the ' . $this->pluginId . ' config action.');
+    }
+    $property_name = $value['property'];
+    unset($value['property']);
+
+    // The `array_push()` and `array_unshift()` functions have a similar
+    // signature, and need to be given an array of values.
+    if (in_array($this->function, ['array_push', 'array_unshift'], TRUE)) {
+      if (isset($value['values']) && is_array($value['values'])) {
+        $arguments = array_values($value['values']);
+      }
+      else {
+        throw new ConfigActionException('The ' . $this->pluginId . ' config action requires an array of values.');
+      }
+    }
+    else {
+      // Pass everything in $value directly to the function as named arguments.
+      // PHP will validate them on its own.
+      $arguments = $value;
+    }
+
+    $property_value = $config->get($property_name);
+    if (!is_array($property_value)) {
+      throw new ConfigActionException("Config " . $config->getName() . " cannot be updated because the property '$property_name' is not an array.");
+    }
+    ($this->function)($property_value, ...$arguments);
+    $config->set($property_name, $property_value);
+  }
+
+}

core/modules/config/tests/config_test/config/install/config_test.system.yml

 foo: bar
 404: herp
+string: ''
+array:
+  - itemA
+  - itemB

core/modules/config/tests/config_test/config/schema/config_test.schema.yml

@@ -210,6 +210,15 @@ config_test.system:
     '404':
       type: string
       label: '404'
+    string:
+      type: string
+      label: 'String'
+    array:
+      type: sequence
+      label: 'Array'
+      sequence:
+        type: string
+        label: 'Item'
 
 config_test.new:
   type: config_object

core/tests/Drupal/KernelTests/Core/Config/Action/ConfigActionTest.php

@@ -265,6 +265,170 @@ public function testSimpleConfigUpdate(): void {
     }
   }
 
+  /**
+   * Tests that the simpleConfigArray actions cannot be used on config entities.
+   *
+   * @testWith ["append"]
+   *   ["prepend"]
+   *   ["splice"]
+   */
+  public function testSimpleConfigArrayFailsOnEntities(string $derivative_id): void {
+    $this->installConfig('config_test');
+
+    $this->expectException(ConfigActionException::class);
+    $this->expectExceptionMessage("The simpleConfigArray:$derivative_id config action cannot be used on configuration entities.");
+    $this->container->get('plugin.manager.config_action')->applyAction(
+      "simpleConfigArray:$derivative_id",
+      'config_test.dynamic.dotted.default',
+      [],
+    );
+  }
+
+  /**
+   * Tests that the simpleConfigArray actions fail on non-existent config.
+   *
+   * @testWith ["append"]
+   *    ["prepend"]
+   *    ["splice"]
+   */
+  public function testSimpleConfigArrayFailsOnNewConfig(string $derivative_id): void {
+    $this->expectException(ConfigActionException::class);
+    $this->expectExceptionMessage("Config block.block.anything cannot be updated because it does not exist.");
+    $this->container->get('plugin.manager.config_action')->applyAction(
+      "simpleConfigArray:$derivative_id",
+      'block.block.anything',
+      [],
+    );
+  }
+
+  /**
+   * Tests that the simpleConfigArray actions require a property path.
+   *
+   * @testWith ["append", null]
+   *   ["append", ""]
+   *   ["prepend", null]
+   *   ["prepend", ""]
+   *   ["splice", null]
+   *   ["splice", ""]
+   */
+  public function testSimpleConfigArrayFailsOnEmptyOrMissingPropertyPath(string $derivative_id, ?string $property_path): void {
+    $this->installConfig('config_test');
+
+    $value = [];
+    if (isset($property_path)) {
+      $value['property'] = $property_path;
+    }
+
+    $this->expectException(ConfigActionException::class);
+    $this->expectExceptionMessage("A property path must be passed to the simpleConfigArray:$derivative_id config action.");
+    $this->container->get('plugin.manager.config_action')->applyAction(
+      "simpleConfigArray:$derivative_id",
+      'config_test.system',
+      [$value],
+    );
+  }
+
+  /**
+   * Tests that simpleConfigArray append and prepend require an array of values.
+   *
+   * @testWith ["append", null]
+   *   ["append", "nope"]
+   *   ["prepend", null]
+   *   ["prepend", "nope"]
+   */
+  public function testSimpleConfigArrayPrependAndAppendRequireArrayOfValues(string $derivative_id, mixed $values): void {
+    $this->installConfig('config_test');
+
+    $this->expectException(ConfigActionException::class);
+    $this->expectExceptionMessage("The simpleConfigArray:$derivative_id config action requires an array of values.");
+    $this->container->get('plugin.manager.config_action')->applyAction(
+      "simpleConfigArray:$derivative_id",
+      'config_test.system',
+      [
+        'property' => 'array',
+        'values' => $values,
+      ],
+    );
+  }
+
+  /**
+   * Tests that the simpleConfigArray actions fail on non-array properties.
+   *
+   * @testWith ["append", {"values": [1, 2, 3]}]
+   *   ["prepend", {"values": [1, 2, 3]}]
+   *   ["splice", {"offset": 0}]
+   */
+  public function testSimpleConfigArrayOnlyWorksOnArrays(string $derivative_id, array $value): void {
+    $this->installConfig('config_test');
+
+    $this->expectException(ConfigActionException::class);
+    $this->expectExceptionMessage("Config config_test.system cannot be updated because the property 'string' is not an array.");
+    $this->container->get('plugin.manager.config_action')->applyAction(
+      "simpleConfigArray:$derivative_id",
+      'config_test.system',
+      ['property' => 'string'] + $value,
+    );
+  }
+
+  /**
+   * @testWith ["append", {"values": ["one", "three"]}, ["itemA", "itemB", "one", "three"]]
+   *   ["prepend", {"values": ["undo", "redo"]}, ["undo", "redo", "itemA", "itemB"]]
+   *    ["splice", {"offset": 1, "replacement": ["c", "d"]}, ["itemA", "c", "d"]]
+   *    ["splice", {"offset": 1, "length": 0, "replacement": ["c", "d"]}, ["itemA", "c", "d", "itemB"]]
+   *    ["splice", {"offset": 1, "length": 0}, ["itemA", "itemB"]]
+   *    ["splice", {"offset": 1}, ["itemA"]]
+   */
+  public function testSimpleConfigArray(string $derivative_id, array $value, array $expected_value): void {
+    $this->installConfig('config_test');
+
+    $this->container->get('plugin.manager.config_action')->applyAction(
+      "simpleConfigArray:$derivative_id",
+      'config_test.system',
+      ['property' => 'array'] + $value,
+    );
+    $this->assertSame($expected_value, $this->config('config_test.system')->get('array'));
+  }
+
+  /**
+   * @testWith ["append", [{"values": ["one", "three"]}, {"values": ["four", "six"]}], ["itemA", "itemB", "one", "three", "four", "six"]]
+   *   ["prepend", [{"values": ["undo", "redo"]}, {"values": ["bold", "italic"]}], ["bold", "italic", "undo", "redo", "itemA", "itemB"]]
+   *   ["splice", [{"offset": 1, "length": 1, "replacement": ["itemC"]}, {"offset": 2, "length": null, "replacement": ["itemD", "itemE"]}], ["itemA", "itemC", "itemD", "itemE"]]
+   */
+  public function testSimpleConfigArrayMultipleInvocations(string $derivative_id, array $values, array $expected_value): void {
+    $this->installConfig('config_test');
+
+    foreach ($values as &$value) {
+      $value['property'] = 'array';
+    }
+
+    $this->container->get('plugin.manager.config_action')->applyAction(
+      "simpleConfigArray:$derivative_id",
+      'config_test.system',
+      $values,
+    );
+    $this->assertSame($expected_value, $this->config('config_test.system')->get('array'));
+  }
+
+  /**
+   * Tests that simpleConfigArray:splice rejects invalid arguments.
+   */
+  public function testSimpleConfigArraySpliceWithInvalidArgument(): void {
+    $this->installConfig('config_test');
+
+    $this->expectException(\Error::class);
+    $this->expectExceptionMessage('Unknown named parameter $yep');
+    $this->container->get('plugin.manager.config_action')->applyAction(
+      "simpleConfigArray:splice",
+      'config_test.system',
+      [
+        'property' => 'array',
+        'offset' => 1,
+        // This parameter isn't defined by `array_splice()`.
+        'yep' => 'nope',
+      ],
+    );
+  }
+
   /**
    * @see \Drupal\Core\Config\Action\ConfigActionManager::getShorthandActionIdsForEntityType()
    */