PHPackages                             inanepain/stdlib - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. inanepain/stdlib

ActiveLibrary[Utility & Helpers](/categories/utility)

inanepain/stdlib
================

Common classes that cover a wide range of cases that are used throughout the inanepain libraries.

0.9.0(1mo ago)111218UnlicensePHPPHP >=8.4

Since Apr 22Pushed 1w ago1 watchersCompare

[ Source](https://github.com/inanepain/stdlib)[ Packagist](https://packagist.org/packages/inanepain/stdlib)[ Docs](https://git.cathedral.co.za:3000/inanepain/stdlib)[ RSS](/packages/inanepain-stdlib/feed)WikiDiscussions develop Synced 3w ago

READMEChangelog (2)Dependencies (2)Versions (24)Used By (18)

inanepain/stdlib [![icon](./icon.png "inanepain/stdlib")](./icon.png)
=====================================================================

[](#inanepainstdlib-)

Table of Contents

- [![icon](./icon.png "inanepain/stdlib") inanepain/stdlib](#inanepainstdlib)
- [1. Install](#install)
- [2. Enum Bitmask](#enum-bitmask)
    - [2.1. Overview](#overview)
    - [2.2. Requirements and conventions](#requirements-and-conventions)
    - [2.3. API](#api)
    - [2.4. Example: Permission flags](#example-permission-flags)
    - [2.5. Tips](#tips)
- [3. Output Strategy](#output-strategy)
    - [3.1. Components](#components)
    - [3.2. API Overview](#api-overview)
    - [3.3. Usage](#usage)
    - [3.4. Extending](#extending)
- [4. Merge](#merge)
    - [4.1. When to use](#when-to-use)
    - [4.2. Strategies (MergeMethod)](#strategies-mergemethod)
    - [4.3. API overview](#api-overview-1)
    - [4.4. Usage](#usage-1)
    - [4.5. Behavior details](#behavior-details)
    - [4.6. Working with iterators and ArrayAccess](#working-with-iterators-and-arrayaccess)
    - [4.7. Selecting a strategy dynamically](#selecting-a-strategy-dynamically)
    - [4.8. JavaScript counterpart](#javascript-counterpart)
    - [4.9. Tips](#tips-1)
- [5. VerifyValue](#verifyvalue)
    - [5.1. Methods](#methods)
- [6. Website: github](#website-github)

[![icon](./icon.png "inanepain/stdlib")](./icon.png) inanepain/stdlib
---------------------------------------------------------------------

[](#-inanepainstdlib)

Common classes that cover a wide range of cases that are used throughout the inanepain libraries.

1. Install
----------

[](#1-install)

composer

```
composer require inanepain/stdlib
```

2. Enum Bitmask
---------------

[](#2-enum-bitmask)

This section documents the `BitmaskEnumTrait` used to add bitmask (flags) behaviour to backed `enum`s.

### 2.1. Overview

[](#21-overview)

`BitmaskEnumTrait` provides a concise API for working with integer bitmasks on PHP 8.5+ backed enums. It enables:

- Combining multiple enum cases into a single integer mask
- Checking if any or all cases are set in a mask
- Testing for and modifying individual flags (both statically and via instance helpers)
- Listing the set enum cases from a mask

Trait location:

- Namespace: `Inane\Stdlib\Bitmask`
- File: `lib/inanepain/stdlib/src/Bitmask/EnumBitmaskTrait.php`

### 2.2. Requirements and conventions

[](#22-requirements-and-conventions)

- Use on backed enums with `int` values only.
- Each enum case should represent a single bit: use powers of two (e.g. `1
value
*/
```

### 3.4. Extending

[](#34-extending)

To create a new output format, extend `AbstractOutput` and implement the `output()` method:

```
use Inane\Stdlib\Output\AbstractOutput;

class MyCustomOutput extends AbstractOutput {
    public function output(): string {
        if (!isset($this->outputData)) {
            // ... custom conversion logic ...
            $this->outputData = "processed data";
        }
        return $this->outputData;
    }
}
```

4. Merge
--------

[](#4-merge)

Helper utilities for merging configuration/options arrays and iterators with explicit control over how keys are added and/or updated. The Merge tool lives under `Inane\Stdlib\Merge` and consists of:

- `MergeTrait` — core implementation and convenience helpers
- `Merge` — small class that exposes the trait as a ready‑to‑use type
- `MergeInterface` — contract for merge behaviour
- `MergeMethod` — enum that selects the merge strategy

### 4.1. When to use

[](#41-when-to-use)

Use Merge to combine option sets coming from defaults, environment, per‑user overrides, feature flags, etc. It supports nested structures and works with both PHP arrays and `ArrayAccess`/`Iterator` implementations.

### 4.2. Strategies (MergeMethod)

[](#42-strategies-mergemethod)

`MergeMethod` controls how keys are handled during a merge:

- `AddOnly` — only add keys that do not exist on the target; existing keys are left unchanged.
- `UpdateOnly` (default) — only update keys that already exist on the target; new keys are ignored.
- `AddAndUpdate` — add missing keys and update existing keys (full overlay/recursive replace).

Merging is recursive for nested arrays/objects that are arrays or implement `ArrayAccess`/`Iterator` on both source and target sides.

### 4.3. API overview

[](#43-api-overview)

Namespace: `Inane\Stdlib\Merge`

Core static method:

```
Iterator|array MergeTrait::mergeOptionsWithMethod(
    MergeMethod $mergeMethod,
    Iterator|array $target,
    Iterator|array ...$sources
): Iterator|array
```

Convenience helpers (static):

- `mergeOptionsWithAddOnly($target, …​$sources)`
- `mergeOptionsWithUpdateOnly($target, …​$sources)`
- `mergeOptionsWithAddAndUpdate($target, …​$sources)`

Instance method (via `Merge` or any class using the trait):

```
public MergeMethod $mergeMethod = MergeMethod::UpdateOnly; // default

public function mergeOptions(Iterator|array $target, Iterator|array ...$sources): Iterator|array
```

### 4.4. Usage

[](#44-usage)

#### 4.4.1. Static helpers

[](#441-static-helpers)

```