YouTipFunc Array Shift
## PHP array_shift() Function
The `array_shift()` function is a built-in PHP function used to remove the first element from an array and return its value.
Because this operation modifies the array in place, the array's length is reduced by one. Additionally, all remaining numerical keys will be modified so that they start counting from 0 and increment by 1, while literal (string) keys will remain untouched.
---
## Syntax
```php
array_shift(array &$array): mixed
```
### Parameter Values
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `array` | Array | **Required.** Specifies the input array. This parameter is passed by reference, meaning the original array will be modified directly. |
### Return Value
* Returns the value of the removed element.
* Returns `null` if the array is empty.
---
## Technical Details
* **PHP Version Support:** PHP 4+
* **Changelog:** Prior to PHP 5.3.0, a warning would be thrown if a non-array was passed. In modern PHP versions, passing a non-array will result in a `TypeError`.
---
## Basic Examples
### Example 1: Shifting an Associative Array
When using `array_shift()` with an associative array (where keys are strings), the keys of the remaining elements are preserved.
```php
"red", "b" => "green", "c" => "blue");
// Remove and return the first element
$removed_value = array_shift($a);
echo "Removed Value: " . $removed_value . "\n";
print_r($a);
?>
```
**Output:**
```text
Removed Value: red
Array
(
=> green
=> blue
)
```
---
### Example 2: Shifting an Indexed Array (Numeric Keys)
When using `array_shift()` with numeric keys, all remaining elements will have their keys reset to start from 0 and increment by 1.
```php
"red", 1 => "green", 2 => "blue");
// Remove and return the first element
$removed_value = array_shift($a);
echo "Removed Value: " . $removed_value . "\n";
print_r($a);
?>
```
**Output:**
```text
Removed Value: red
Array
(
=> green
=> blue
)
```
---
## Advanced Usage: Preserving Numeric Keys
If you need to remove the first element of an array but want to **preserve the original numeric keys** of the remaining elements, standard `array_shift()` cannot do this directly.
You can implement a custom helper function using `array_keys()` and `unset()` to achieve this behavior:
```php
1, '2' => 2, '3' => '3');
/**
* Shifts the first element off the array while preserving numeric keys.
*
* @param array $arr The input array passed by reference.
* @return array An associative array containing the removed key and value.
*/
function array_kshift(&$arr)
{
// Get all keys and extract the first key
list($k) = array_keys($arr);
// Store the removed key-value pair
$r = array($k => $arr[$k]);
// Remove the element from the original array
unset($arr[$k]);
return $r;
}
// Execute the custom shift function
$removed = array_kshift($arr);
echo "Removed Element:\n";
print_r($removed);
echo "\nRemaining Array (Keys Preserved):\n";
print_r($arr);
?>
```
**Output:**
```text
Removed Element:
Array
(
=> 1
)
Remaining Array (Keys Preserved):
Array
(
=> 2
=> 3
)
```
---
## Key Considerations
1. **Performance:** `array_shift()` requires re-indexing all numerical keys in the array. For very large arrays, this operation can be relatively slow ($O(n)$ complexity). If you are building a high-performance queue, consider using `SplQueue` or reversing your logic to use `array_pop()` ($O(1)$ complexity) where possible.
2. **Resetting Array Pointer:** Calling `array_shift()` will automatically reset the internal array pointer of the modified array (equivalent to calling `reset()`).