array_splice()

A manipulação de arrays é uma parte essencial da programação, e o PHP oferece várias funções integradas para trabalhar com arrays. Uma das mais flexíveis é array_splice — uma única função capaz de remover, substituir e inserir elementos em qualquer posição. Ao contrário de array_slice(), que copia uma parte do array sem alterar o original, array_splice modifica o array no próprio lugar e retorna os elementos removidos.

Esta página explica a assinatura da função, como cada parâmetro se comporta (incluindo os offsets negativos, frequentemente confusos, e a forma como as chaves são renumeradas), e apresenta exemplos executáveis para as três situações em que você realmente a utilizará: remoção, substituição e inserção.

O que é a função array_splice?

A função array_splice é uma função integrada do PHP que permite remover ou substituir elementos de um array e adicionar novos elementos no lugar deles. A função modifica o array original e retorna os elementos removidos, caso existam. Ela recebe três parâmetros obrigatórios e dois opcionais:

Sintaxe da função PHP array_splice

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

• $input: O array de entrada que será modificado
• $offset: O índice a partir do qual a operação será iniciada
• $length (opcional): O número de elementos a remover. Se não for especificado, todos os elementos desde $offset até o final do array serão removidos
• $replacement (opcional): Os elementos a serem inseridos no lugar dos elementos removidos. Se não for especificado, nenhum elemento será inserido

Como funciona a função array_splice?

A função array_splice opera no array de entrada, começando no offset especificado, e remove o número especificado de elementos. Se nenhum comprimento for especificado, todos os elementos a partir do offset até o final do array serão removidos. Os elementos removidos são retornados como um array.

Se o parâmetro $replacement for especificado, a função insere os elementos de substituição no lugar dos elementos removidos. Os elementos de substituição podem ser de qualquer tipo de dado, incluindo arrays. Se o parâmetro $replacement não for especificado, nenhum elemento é inserido e a função simplesmente remove os elementos indicados.

A função modifica o array de entrada no próprio lugar, o que significa que o array original é alterado pela operação. Como o primeiro parâmetro é passado por referência (&$input), é necessário passar uma variável real — não é possível aplicar splice diretamente em um array literal ou no resultado de outra chamada de função.

Offset e length negativos

Tanto $offset quanto $length aceitam valores negativos, que são contados a partir do final do array:

• Um $offset negativo inicia a operação aquela quantidade de elementos antes do final. array_splice($arr, -2) remove os dois últimos elementos.
• Um $length negativo encerra a remoção aquela quantidade de elementos antes do final do array, de modo que os elementos finais são mantidos. array_splice($arr, 1, -1) remove tudo exceto o primeiro e o último elemento.

Como as chaves são afetadas

array_splice foi concebida para arrays sequenciais (do tipo lista). Após a operação, as chaves numéricas são sempre renumeradas a partir de 0, enquanto as chaves string são preservadas. Se você precisar manter as chaves numéricas intactas, array_splice não é a ferramenta adequada — prefira array_slice() com o sinalizador preserve_keys.

Exemplos

Removendo elementos de um array

Suponha que temos um array de números e queremos remover os três primeiros elementos. Podemos usar a função array_splice da seguinte forma:

PHP Removendo elementos de um array com array_splice

Neste exemplo, o array $numbers será modificado e os três primeiros elementos serão removidos. Os elementos removidos serão retornados na variável $removed. O valor de $numbers após a chamada da função será [4, 5, 6], e o valor de $removed será [1, 2, 3].

Substituindo elementos em um array

Suponha que temos um array de nomes e queremos substituir o terceiro e o quarto nomes por novos nomes. Podemos usar a função array_splice da seguinte forma:

PHP Substituindo elementos em um array com array_splice

Neste exemplo, o array $names será modificado e o terceiro e o quarto nomes serão substituídos pelos nomes 'Alex' e 'Olivia'. O valor de $names após a chamada da função será ['John', 'Mary', 'Alex', 'Olivia', 'Sarah']. Observe que o número de substituições não precisa corresponder ao número de elementos removidos — você pode substituir dois elementos por cinco, ou por nenhum.

Inserindo elementos em um array

Suponha que temos um array de letras e queremos inserir as letras 'B' e 'C' no início do array. Podemos usar a função array_splice da seguinte forma:

PHP Inserindo elementos em um array com array_splice

Neste exemplo, o array $letters será modificado e as letras 'B' e 'C' serão inseridas no início do array. O valor de $letters após a chamada da função será ['B', 'C', 'D', 'E', 'F'].

Usando offset e length negativos

Este exemplo remove tudo entre o primeiro e o último elemento combinando um offset positivo com um length negativo:

PHP array_splice com length negativo

<?php

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

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

Aqui $offset é 1 (começar após 'first') e $length é -1 (parar um elemento antes do final, mantendo 'last'), portanto os três elementos do meio são removidos e retornados.

Funções relacionadas

array_splice se sobrepõe a várias funções de array mais específicas. Escolha a mais adequada para cada situação — isso torna sua intenção mais clara:

• array_slice() — extrai uma parte sem modificar o array original.
• array_merge() — combina arrays fim a fim, em vez de em uma posição específica.
• array_push() / array_unshift() — adiciona elementos ao final ou ao início.
• array_pop() / array_shift() — remove um único elemento do final ou do início.

Conclusão

array_splice é o canivete suíço da edição de arrays em PHP: uma única chamada pode remover, substituir ou inserir elementos em qualquer offset. Lembre-se destes pontos:

• Ela muta o array de entrada e retorna os elementos removidos.
• A quantidade de substituições é independente da quantidade de remoções.
• As chaves numéricas são renumeradas; as chaves string são mantidas.
• $offset e $length negativos são contados a partir do final do array.

Quando você precisar apenas ler uma fatia sem alterar a fonte, prefira array_slice().

Prática