Oihana PHP

clean.php

Table of Contents

Functions

clean()  : array<int|string, mixed>|null
Cleans an array by removing unwanted values based on bitwise flags from the `CleanFlag` enum.

Functions

clean()

Cleans an array by removing unwanted values based on bitwise flags from the `CleanFlag` enum.

clean([array<int|string, mixed> $array = [] ][, int $flags = CleanFlag::DEFAULT ]) : array<int|string, mixed>|null

This function allows flexible and recursive filtering of arrays. Cleaning behavior is fully customizable via bitwise flags.

Supported flags from CleanFlag:

  • CleanFlag::NULLS : Removes null values.
  • CleanFlag::EMPTY : Removes empty strings ('').
  • CleanFlag::TRIM : Modifier of EMPTY : whitespace-only strings count as empty. Has no effect on its own, and never alters the values it keeps.
  • CleanFlag::EMPTY_ARR : Removes empty arrays (after recursive cleaning).
  • CleanFlag::RECURSIVE : Cleans nested arrays recursively.
  • CleanFlag::FALSY : Removes every falsy scalar (null, '', 0, 0.0, '0', false). Short-circuits NULLS / EMPTY / TRIM, and never applies to arrays — combine it with EMPTY_ARR to also discard [].
  • CleanFlag::MAIN : Shortcut for enabling all the main flags: NULLS | EMPTY | EMPTY_ARR | TRIM.
  • CleanFlag::RETURN_NULL : Returns null whenever nothing is left, including when the input was already empty. Applies to the outermost call only : a nested array that cleans to empty stays [].

Default behavior

Using CleanFlag::DEFAULT is equivalent to enabling:

CleanFlag::NULLS | CleanFlag::EMPTY | CleanFlag::TRIM | CleanFlag::EMPTY_ARR | CleanFlag::RECURSIVE

That means by default, clean() removes:

  • null
  • empty strings
  • strings containing only spaces/tabs/newlines
  • empty arrays
  • and also cleans nested arrays recursively.
Parameters
$array : array<int|string, mixed> = []

The input array to clean. Nested arrays are processed only if CleanFlag::RECURSIVE is set.

$flags : int = CleanFlag::DEFAULT

A bitmask of CleanFlag values. Defaults to CleanFlag::DEFAULT.

Tags
throws
InvalidArgumentException

If $flags is not a valid combination of CleanFlag constants.

example

1. Basic cleaning: remove nulls and empty strings

use oihana\core\arrays\{clean, CleanFlag};

$data   = ['foo', '', null, 'bar'];
$result = clean($data, CleanFlag::NULLS | CleanFlag::EMPTY);
// ['foo', 'bar']

2. Remove whitespace-only strings as well

$data   = ['foo', '   ', '', null, 'bar'];
$result = clean($data, CleanFlag::NULLS | CleanFlag::EMPTY | CleanFlag::TRIM);
// ['foo', 'bar']

3. Recursive cleaning of nested arrays

$data = [
    'users' => [
        ['name' => '', 'email' => 'bob@example.com'],
        ['name' => 'Alice', 'email' => '']
    ]
];

$result = clean($data, CleanFlag::RECURSIVE | CleanFlag::EMPTY);
// [
//     'users' => [
//         ['email' => 'bob@example.com'],
//         ['name' => 'Alice']
//     ]
// ]

4. Remove empty arrays after recursive cleaning

$data = [
    'group1' => [],
    'group2' => [['name' => 'Alice'], []]
];

$result = clean($data, CleanFlag::RECURSIVE | CleanFlag::EMPTY_ARR);
// [
//     'group2' => [['name' => 'Alice']]
// ]

5. Remove all falsy scalars at once

$data   = [0, '', null, false, 'ok', [], '0'];
$result = clean($data, CleanFlag::FALSY);
// ['ok', []]  -- FALSY never applies to arrays

$result = clean($data, CleanFlag::FALSY | CleanFlag::EMPTY_ARR);
// ['ok']

6. Full cleaning using default flags

$result = clean($data);
// Equivalent to CleanFlag::DEFAULT

7. Return null if nothing is left*

$data = ['', null, '   '];
$result = clean($data, CleanFlag::DEFAULT | CleanFlag::RETURN_NULL);
// null (instead of [])

$result = clean([], CleanFlag::DEFAULT | CleanFlag::RETURN_NULL);
// null too : an already empty input is a "nothing left" case like any other

// Useful for validation
$cleaned = clean($userInput, CleanFlag::DEFAULT | CleanFlag::RETURN_NULL);
if ($cleaned === null) {
    throw new Exception('No valid data provided');
}
see
CleanFlag

For available cleaning flags and default behavior.

isIndexed()

To determine if an array is numerically indexed.

author

Marc Alcaraz

since
1.0.6
Return values
array<int|string, mixed>|null —

The filtered array:

  • Associative arrays: keys are preserved.
  • Indexed arrays: automatically reindex to remove numeric gaps.
  • null if the final array is empty and the CleanFlag::RETURN_NULL option is used.
On this page

Search results