정의 및 사용 방법

PHP 버전
4+

array_splice() 함수는 인덱스 기반 배열의 원하는 위치에서
요소를 제거하거나, 다른 요소로 교체하거나, 새 요소를 추가할 수 있습니다.

인덱스 배열에서 인덱스는 0부터 시작합니다.
첫 번째 요소의 인덱스는 0이고, 두 번째 요소의 인덱스는 1입니다.

특징

  • 원본 배열을 직접 수정합니다.
  • 매개변수를 사용해서 요소를 제거, 교체, 추가할 수 있습니다.
  • 제거한 요소를 담은 배열을 반환합니다. 제거한 요소가 없을 경우 빈 배열을 반환합니다.
  • 연관 배열에서는 적절하지 않으며, 인덱스 배열에서만 안전하게 사용 가능합니다.

이 함수는 인덱스 배열에서 특정 위치부터 범위를 정해 요소를 한 번에 제거하거나 교체, 추가할 수 있다는 특징이 있습니다.

기본 예제

array_splice() 함수의 기본 동작을 이해하기 위해,
인덱스 배열에서 요소를 제거, 교체, 추가하는 예제를 각각 살펴보겠습니다.

배열의 요소 제거

PHP 
// 장바구니에서 구매 완료된 아이템 제거
$cart = ['티셔츠', '바지', '모자', '신발'];

/*
 * <바지를 장바구니에서 제거>
 * array_splice(array &$array, int $offset, ?int $length = null, mixed $replacement = [])
 * $array: 수정할 원본 배열 (참조로 전달됨)
 * $offset: 제거를 시작할 인덱스 (0부터 시작)
 * $length (옵션): 제거할 요소의 개수
 */
$purchased = array_splice($cart, 1, 1);

// 원본 배열
print_r($cart); // ['티셔츠', '모자', '신발']

// 반환 값
print_r($purchased); // ['바지']

배열의 요소 교체

PHP 
// 제품 목록에서 단종된 상품 교체
$products = ['노트북', '태블릿', '스마트폰', '모니터'];

/*
 * <태블릿을 최신 모델로 교체>
 * array_splice(array &$array, int $offset, ?int $length = null, mixed $replacement = [])
 * $array: 수정할 원본 배열 (참조로 전달됨)
 * $offset: 배열을 변경하기 시작할 인덱스 (0부터 시작)
 * $length (옵션): 제거할 요소의 개수
 * $replacement (옵션): 배열에 새로 추가할 요소 또는 배열
 *  => $length와 함께 사용하면 교체가 가능
 */
$replacedProduct = array_splice($products, 1, 1, '신형 태블릿');

// 원본 배열
print_r($products); // ['노트북', '신형 태블릿', '스마트폰', '모니터']

// 반환 값
print_r($replacedProduct); // ['태블릿']

배열의 요소 추가

PHP 
// 장바구니에 새 아이템 추가
$cart = ['티셔츠', '바지', '모자'];

/*
 * <모자 뒤에 신발을 추가>
 * array_splice(array &$array, int $offset, ?int $length = null, mixed $replacement = [])
 * $array: 수정할 원본 배열 (참조로 전달됨)
 * $offset: 배열을 변경하기 시작할 인덱스 (0부터 시작)
 * $length (옵션): 제거할 요소의 개수
 * $replacement (옵션): 배열에 새로 추가할 요소 또는 배열
 *  => $length가 0이면 삭제 없이 요소 추가
 */
$addedItem = array_splice($cart, 3, 0, '신발');

// 원본 배열
print_r($cart); // ['티셔츠', '바지', '모자', '신발']

// 반환 값
print_r($addedItem); // []

구문

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

매개변수

array_splice() 함수의 매개변수 설명
@$array 조작할 대상 배열(참조 변수)입니다. 함수 호출 후 원본 배열이 직접 수정됩니다.
$offset 제거 또는 교체를 시작할 인덱스 위치입니다.
  • 양수 값: 배열의 시작(0)으로부터 지정한 인덱스에서 제거를 시작합니다.
  • 음수 값: 배열의 끝에서부터 거꾸로 계산된 인덱스에서 제거를 시작합니다. (예: -1은 마지막 요소, -2는 끝에서 두 번째 요소)
$length 옵션. 제거할 요소의 개수를 지정합니다. 생략되면 offset부터 배열의 끝까지 모든 요소가 제거됩니다.
  • 양수 값: 지정한 개수만큼 요소를 제거합니다.
  • 음수 값: 배열의 끝에서 지정한 개수만큼 남겨두고 제거가 수행됩니다.
  • 0 값: 아무 요소도 제거되지 않습니다. (순수한 삽입 기능으로 사용됩니다.)
  • $replacement과 함께 사용하면서 끝까지 제거하려면: count($array)를 사용할 수 있습니다.
$replacement 옵션. 제거된 부분을 대체할 요소들이 담긴 배열입니다.
  • 제거된 요소가 있을 경우: 그 자리에 replacement 배열의 요소가 삽입됩니다.
  • 제거된 요소가 없을 경우(예: length가 0 또는 제거 범위가 없음): offset 위치에 replacement 배열의 요소가 삽입됩니다. 즉, length가 0이면 삭제 없이 요소를 추가합니다.
  • replacement가 단일 값인 경우: 해당 값을 직접 지정할 수 있으며, 단 그 값이 배열, 객체, null일 경우에는 반드시 배열로 감싸야 합니다.
  • 주의: replacement 배열 내부의 연관 키는 유지되지 않고, 새로운 순차적 인덱스(0, 1, 2, ...)가 할당됩니다.

반환 값

삭제된 요소를 담은 배열을 반환합니다.

  • 하나의 요소를 삭제하면, 길이가 1인 배열을 반환합니다.
  • 삭제된 요소가 없으면, 빈 배열 ([])을 반환합니다.

주의하세요!
반환된 배열은 0부터 다시 인덱스가 매겨집니다. 즉, 원래 배열의 키는 유지되지 않습니다.

매개변수와 반환 값 예시

PHP 
$arr = ['A', 'B', 'C', 'D'];

// 1. 요소 제거
$removed1 = array_splice($arr, 1, 2);
print_r($removed1); // ['B', 'C']

// 2. 요소 추가만 (길이 0)
$removed2 = array_splice($arr, 1, 0, ['X']);
print_r($removed2); // []

// 3. 음수 인덱스
$removed3 = array_splice($arr, -2, 1);
print_r($removed3); // ['X']

변경 이력

array_splice() 함수의 변경 이력
버전설명
8.0.0 $length는 이제 null 값을 가질 수 있습니다.

활용 예제

array_splice() 함수는 배열의 원하는 위치에서 요소를 제거, 교체, 추가할 수 있습니다. 활용 예제에서는 실제 상황에서 자주 사용하는 세 가지 예제를 통해 array_splice() 함수의 매개변수와 반환 값의 관계를 쉽게 확인해 보겠습니다.

배열 중간에 요소 추가

PHP 
$fruits = ['사과', '배', '바나나'];

// '배' 뒤에 '오렌지' 추가
$added = array_splice($fruits, 2, 0, ['오렌지']);

print_r($fruits); // ['사과', '배', '오렌지', '바나나']
print_r($added);  // []

특정 요소 교체

PHP 
$fruits = ['사과', '배', '오렌지', '바나나'];

// '배'를 '키위'로 교체
$replaced = array_splice($fruits, 1, 1, ['키위']);

print_r($fruits);   // ['사과', '키위', '오렌지', '바나나']
print_r($replaced); // ['배']

마지막 요소 제거 및 새 요소 추가

PHP 
$fruits = ['사과', '키위', '오렌지', '바나나'];

// 마지막 요소를 제거하고 '망고' 추가
$removed = array_splice($fruits, count($fruits) - 1, 1, ['망고']);

print_r($fruits);  // ['사과', '키위', '오렌지', '망고']
print_r($removed); // ['바나나']

참고문헌

같이 보기