array_splice()

La manipulación de arrays es una parte esencial de la programación, y PHP ofrece varias funciones integradas para trabajar con arrays. Una de las más flexibles es array_splice — una sola función que puede eliminar, reemplazar e insertar elementos en cualquier posición. A diferencia de array_slice(), que copia una porción de un array y deja el original intacto, array_splice modifica el array en su lugar y devuelve los elementos que eliminó.

Esta página explica la firma de la función, cómo se comporta cada parámetro (incluidos los desplazamientos negativos, que suelen causar confusión, y la forma en que se renumeran las claves), y muestra ejemplos ejecutables para las tres operaciones que realmente usarás: eliminar, reemplazar e insertar.

¿Qué es la función array_splice?

La función array_splice es una función integrada de PHP que permite eliminar o reemplazar elementos de un array y agregar nuevos elementos en su lugar. La función modifica el array original y devuelve los elementos eliminados, si los hay. La función acepta tres parámetros obligatorios y dos opcionales:

Sintaxis de la función array_splice de PHP

array_splice(array &$input, int $offset, ?int $length = null, mixed $replacement = [])

• $input: El array de entrada que será modificado
• $offset: El índice en el que comenzará la operación
• $length (opcional): El número de elementos a eliminar. Si no se especifica, se eliminarán todos los elementos desde $offset hasta el final del array
• $replacement (opcional): Los elementos que se insertarán en lugar de los eliminados. Si no se especifica, no se insertará ningún elemento

¿Cómo funciona la función array_splice?

La función array_splice opera sobre el array de entrada comenzando en el desplazamiento especificado y elimina el número indicado de elementos. Si no se especifica una longitud, se eliminarán todos los elementos desde el desplazamiento hasta el final del array. Los elementos eliminados se devuelven como un array.

Si se especifica el parámetro $replacement, la función inserta los elementos de reemplazo en lugar de los eliminados. Los elementos de reemplazo pueden ser de cualquier tipo de dato, incluidos arrays. Si no se especifica el parámetro $replacement, no se inserta ningún elemento y la función simplemente elimina los elementos indicados.

La función modifica el array de entrada en su lugar, lo que significa que el array original cambia con la operación. Dado que el primer parámetro se pasa por referencia (&$input), debes pasar una variable real — no es posible aplicar splice directamente sobre un array literal o el resultado de otra llamada a función.

Desplazamiento y longitud negativos

Tanto $offset como $length aceptan valores negativos, que se cuentan desde el final del array:

• Un $offset negativo inicia la operación ese número de elementos desde el final. array_splice($arr, -2) elimina los dos últimos elementos.
• Un $length negativo detiene la eliminación ese número de elementos antes del final del array, de modo que esos elementos finales se conservan. array_splice($arr, 1, -1) elimina todo excepto el primer y el último elemento.

Cómo se ven afectadas las claves

array_splice está diseñada para arrays secuenciales (similares a listas). Tras la operación, las claves numéricas siempre se renumeran desde 0, mientras que las claves de string se conservan. Si necesitas mantener las claves numéricas intactas, array_splice no es la herramienta adecuada — utiliza array_slice() con su opción preserve_keys.

Ejemplos

Eliminar elementos de un array

Supongamos que tenemos un array de números y queremos eliminar los tres primeros elementos. Podemos usar la función array_splice de la siguiente manera:

PHP: Eliminación de elementos de un array con array_splice

En este ejemplo, el array $numbers será modificado y los tres primeros elementos serán eliminados. Los elementos eliminados se devolverán en la variable $removed. El valor de $numbers tras la llamada a la función será [4, 5, 6], y el valor de $removed será [1, 2, 3].

Reemplazar elementos en un array

Supongamos que tenemos un array de nombres y queremos reemplazar el tercero y el cuarto con nuevos nombres. Podemos usar la función array_splice de la siguiente manera:

PHP: Reemplazo de elementos en un array con array_splice

En este ejemplo, el array $names será modificado y el tercer y cuarto nombre serán reemplazados por los nombres 'Alex' y 'Olivia'. El valor de $names tras la llamada a la función será ['John', 'Mary', 'Alex', 'Olivia', 'Sarah']. Ten en cuenta que el número de reemplazos no tiene que coincidir con el número de elementos eliminados — puedes reemplazar dos elementos con cinco, o con ninguno.

Insertar elementos en un array

Supongamos que tenemos un array de letras y queremos insertar las letras 'B' y 'C' al inicio del array. Podemos usar la función array_splice de la siguiente manera:

PHP: Inserción de elementos en un array con array_splice

En este ejemplo, el array $letters será modificado y las letras 'B' y 'C' serán insertadas al inicio del array. El valor de $letters tras la llamada a la función será ['B', 'C', 'D', 'E', 'F'].

Uso de desplazamiento y longitud negativos

Este ejemplo elimina todo lo que hay entre el primer y el último elemento combinando un desplazamiento positivo con una longitud negativa:

PHP: array_splice con longitud negativa

<?php

$items = ['first', 'a', 'b', 'c', 'last'];
$removed = array_splice($items, 1, -1);

print_r($items);   // ['first', 'last']
print_r($removed); // ['a', 'b', 'c']
?>

Aquí $offset es 1 (comienza después de 'first') y $length es -1 (se detiene un elemento antes del final, conservando 'last'), por lo que los tres elementos del medio son eliminados y devueltos.

Funciones relacionadas

array_splice se solapa con varias funciones de array más específicas. Elige la más adecuada para cada tarea — hace que tu intención sea más clara:

• array_slice() — extrae una porción sin modificar el array original.
• array_merge() — combina arrays de extremo a extremo en lugar de hacerlo en una posición específica.
• array_push() / array_unshift() — agrega elementos al final o al inicio.
• array_pop() / array_shift() — elimina un único elemento del final o del inicio.

Conclusión

array_splice es la navaja suiza de la edición de arrays en PHP: una sola llamada puede eliminar, reemplazar o insertar elementos en cualquier desplazamiento. Ten en cuenta estos puntos:

• Muta el array de entrada y devuelve los elementos eliminados.
• El número de reemplazos es independiente del número de eliminaciones.
• Las claves numéricas se renumeran; las claves de string se conservan.
• $offset y $length negativos se cuentan desde el final del array.

Cuando solo necesitas leer una porción sin modificar la fuente, prefiere array_slice().

Práctica