Download the PHP package inanepain/stdlib without Composer

= inanepain/stdlib image:./icon.png[title=inanepain/stdlib,25] // tag::tagConfig[] :author: Philip Michael Raab :email: [email protected] :description: Common classes that cover a wide range of cases that are used throughout the inanepain libraries. :keywords: inanepain, inane, library, stdlib, json, xml, array, exception, notice, config :copyright: Unlicense :homepage: https://gitgithub.com/inanepain/stdlib :revnumber: 0.10.0 :revdate: 2026-09-07 :experimental: :hide-uri-scheme: :icons: font :source-highlighter: highlight.js :toc: left :sectanchors: :idprefix: topic- :idseparator: - :pkg-vendor: inanepain :pkg-name: stdlib :pkg-id: {pkg-vendor}/{pkg-name} // end::tagConfig[]

== image:./icon.png[title={pkg-id},25] {pkg-id}

{description}

:sectnums:

<<<

:leveloffset: +1

= Install

.composer [source,shell,subs=attributes+]

composer require {pkg-id}

:leveloffset!:

<<<

:leveloffset: +1

= Enum Bitmask

This section documents the BitmaskEnumTrait used to add bitmask (flags) behaviour to backed enums.

== 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

== 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 << 0, 1 << 1, 1 << 2, …).
• Masks are plain integers (int).

== API

Static helpers on the enum using the trait:

• parseBitmask(mixed $mask): int — Normalises arbitrary input into an int mask (null-safe, defaults to 0).
• combine(self ...$flags): int — ORs cases to a single mask.
• hasAny(int $mask): bool — True if any defined case is present in the mask.
• hasAll(int $mask): bool — True if all defined cases are present in the mask.
• has(int $mask, self $flag): bool — True if the given case is present in the mask.
• add(int $mask, self $flag): int — Returns a mask with the case added.
• remove(int $mask, self $flag): int — Returns a mask with the case removed.
• list(int $mask): array<self> — Returns the enum cases present in the mask.

Instance helpers in an enum case:

• in(int $mask): bool — True if this case is present in the mask.
• addTo(int $mask): int — Returns a mask with this case added.
• removeFrom(int $mask): int — Returns a mask with this case removed.

NOTE: Internally, hasAny and hasAll use array helpers equivalent to “any”/“all” checks over self::cases().

== Example: Permission flags

The following example shows a typical permission enum using the trait.

.Example: Permissions [source,php]

*/

== Extending

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

[source,php]

use Inane\Stdlib\Output\AbstractOutput;

class MyCustomOutput extends AbstractOutput { public function output(mixed $inputData = null): string { // Store input and clear cache if required. $this->setInputData($inputData);

    if (!isset($this->outputData)) {
        // ... custom conversion logic ...
        // Store output in cache.
        $this->outputData = "processed data";
    }
    return $this->outputData;
}

}

== Example

A more complete example, using an Output class as a property.

[source,php]

$opt = new \Inane\Stdlib\Options([ 'one' => $data, 'two' => [ 'two' => 2, 'three' => [ 'four' => 'five', ], ], ]);

final class SomeThing { /**

• Handles the output data and processes it appropriately.
• @param mixed $outputHandler The handler responsible for managing and processing the output.
• @return void

• @throws \RuntimeException If the output handler encounters a processing error. */ private \Inane\Stdlib\Output\OutputInterface $outputHandler;

  /**

• Initializes the class with the given input data.
• @param mixed $inputData The data to be processed by the class.
• @return void

• @throws \InvalidArgumentException If the input data is invalid. */ public function __construct(protected mixed $inputData) {}

  /**

• Sets the output handler to be used.
• @param \Inane\Stdlib\Output\OutputInterface $outputHandler The output handler to set.
• @return void

• @throws \InvalidArgumentException If the provided output handler is invalid. */ public function setOutput(\Inane\Stdlib\Output\OutputInterface $outputHandler): void { $this->outputHandler = $outputHandler; }

  /**

• Processes the input data and returns the output.
• @return mixed The result of processing the input data.
• @throws \Exception If an error occurs during output processing. */ public function output(): mixed { return $this->outputHandler->output($this->inputData); } }

echo "\nREUSABLE:\n"; $thing = new SomeThing($opt); $thing->setOutputHandler(new \Inane\Stdlib\Output\XmlStringOutput()); echo "\nXMLString:\n"; var_dump($thing->output());

$thing->setOutputHandler(new \Inane\Stdlib\Output\XmlOutput()); echo "\nXML:\n"; var_dump($thing->output());

$thing->setOutputHandler(new \Inane\Stdlib\Output\ArrayOutput()); echo "\nARRAY:\n"; var_dump($thing->output());

$thing->setOutputHandler(new \Inane\Stdlib\Output\JsonStringOutput()); echo "\nJSON:\n"; var_dump($thing->output());

:leveloffset!:

<<<

:leveloffset: +1

= 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

== 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.

== Strategies (MergeMethod)

MergeMethod controls how keys are handled during a merge:

• AddOnly — only add keys that don’t 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.

== API overview

Namespace: Inane\Stdlib\Merge

Core static method:

[source,php]

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):

[source,php]

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

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

== Usage

=== Static helpers

[source,php]

use Inane\Stdlib\Merge\MergeTrait; // used via Merge facade below use Inane\Stdlib\Merge\Merge;

$defaults = [ 'host' => 'localhost', 'port' => 3306, 'flags' => [ 'compress' => false, 'strict' => true ], ];

$env = [ 'port' => 3307, 'flags' => [ 'compress' => true ], 'extra' => 'ignored in UpdateOnly', ];

// Update existing keys only (default semantics) $merged = Merge::mergeOptionsUpdateOnly($defaults, $env); / Result: [ 'host' => 'localhost', 'port' => 3307, 'flags' => [ 'compress' => true, 'strict' => true ], ] /

// Add missing keys only $added = Merge::mergeOptionsAddOnly($defaults, ['timeout' => 5]); // 'timeout' is appended, existing values untouched

// Add and update (full overlay) $overlay = Merge::mergeOptionsAddAndUpdate($defaults, $env); // Includes 'extra' and applies nested updates php

// Exact hour Clock::fuzzyClock(new DateTime('2026-07-04 13:00:00')); // one o'clock

// Minutes rounded to the nearest five, phrased as past Clock::fuzzyClock(new DateTime('2026-07-04 09:13:00')); // quarter past nine

// After half past, phrased as to the next hour Clock::fuzzyClock(new DateTime('2026-07-04 09:34:00')); // twenty-five to ten

// Rounding up to sixty minutes rolls the hour over Clock::fuzzyClock(new DateTime('2026-07-04 23:58:00')); // twelve o'clock

// Current time Clock::fuzzyClock();

== Tips

• Set the timezone on the supplied DateTime; the wording follows whatever local time the object reports.
• Because the phrasing is rounded, it suits summaries and labels rather than anything needing exact times.

:leveloffset!:

<<<

:leveloffset: +1

= ClassUtility

This section documents ClassUtility, a small helper for working out class information without loading the class.

== Overview

ClassUtility inspects PHP source with the tokeniser, so a file can be examined without being included. It provides:

• Extraction of the fully qualified class name declared in a file
• A class id helper, courtesy of ClassIdTrait

Class location:

• Namespace: Inane\Stdlib\Utility
• File: lib/inanepain/stdlib/src/Utility/ClassUtility.php

== Requirements and conventions

• The API is static; there’s no need to create an instance.
• A file may be given as a path string or an Inane\File\File instance.
• Only the first class declared in a file is reported, which suits PSR-4 style one-class-per-file layouts.
• An invalid or missing file raises Inane\Stdlib\Exception\Exception.

== API

• getClassFromFile(string|File $file): ?string — Returns the fully qualified class name declared in the file, or null when the file declares no class.
• classId(int $size = 0, string $separator = '/', bool $lower = true, ?string $className = null): string — From ClassIdTrait, builds an id from the class name.

== Example: Class name from a file

[source,php]

<?php declare(strict_types=1);

use Inane\File\File; use Inane\Stdlib\Utility\ClassUtility;

// A namespaced class returns the fully qualified name ClassUtility::getClassFromFile('src/Utility/ClassUtility.php'); // Inane\Stdlib\Utility\ClassUtility

// A File instance works just as well ClassUtility::getClassFromFile(new File('src/Utility/ClassUtility.php')); // Inane\Stdlib\Utility\ClassUtility

// Without a namespace, only the class name comes back ClassUtility::getClassFromFile('legacy/Gamma.php'); // Gamma

// A file with no class declaration ClassUtility::getClassFromFile('config/settings.php'); // null

== Example: Class id

[source,php]

<?php declare(strict_types=1);

use Inane\Stdlib\Utility\ClassUtility;

ClassUtility::classId(1); // classutility ClassUtility::classId(2, '/', false); // Utility/ClassUtility

== Tips

• Handy when scanning a directory to map files to classes, for example, when building a plugin or module registry.
• Because it reads a source rather than reflecting, it’s safe to use on files you don’t wish to execute.
• Wrap calls in a try/catch when scanning paths that may not exist.

:leveloffset!:

<<<

:leveloffset: +1

= Website: github

++++

github

  ██████████████    ██████████      ██  ████    ████  ██  ██  ██████████████
  ██          ██      ██  ████          ██████████        ██  ██          ██
  ██  ██████  ██  ████  ████  ████████  ██████████████████    ██  ██████  ██
  ██  ██████  ██  ████        ██      ████    ████████  ████  ██  ██████  ██
  ██  ██████  ██    ██      ██  ████    ██  ██                ██  ██████  ██
  ██          ██    ██        ██████    ██    ██  ██          ██          ██
  ██████████████  ██  ██  ██  ██  ██  ██  ██  ██  ██  ██  ██  ██████████████
                      ██    ██████      ██  ██████████  ████
        ████  ████  ██  ████    ██  ██  ██    ██  ████    ██        ████
  ██    ████      ████      ████  ██  ██        ██  ██      ████  ██
  ████    ██████████            ██      ██    ██  ████      ████████      ██
        ████      ████████    ██    ████      ██      ████  ████    ████  ██
  ██  ████  ████  ████  ██  ████    ██    ██              ██  ████  ██  ████
  ██      ████      ████  ██████  ██        ██    ██  ████  ██    ██  ██
            ████      ██████████████    ██████  ██    ████████  ██  ████████
        ██  ██        ██  ██████  ██      ██  ████      ██        ██████  ██
      ████    ██████  ██  ██  ██    ████    ██  ██████        ██      ██  ██
  ██  ██████          ██        ██████  ████████  ██    ██  ██          ██
  ████  ████████  ████████████    ████████    ██████  ████  ██████  ████  ██
    ██  ██      ██  ████    ████  ████  ██  ████  ████  ██████████████  ██
    ██    ████████                  ██  ██      ██    ██  ██████  ██      ██
  ██  ████████    ██    ██  ██████  ████  ██████  ████  ████    ██████
    ██      ████  ██      ██          ██        ██  ██  ██        ██████  ██
  ██    ██  ██      ████    ██  ██    ████  ██      ██  ██████  ██  ████████
    ██  ██████████    ████  ████  ██████    ██████████          ██████
  ██  ██    ██    ██        ██  ██  ██  ██  ████    ████      ██
  ████  ██  ██████    ████  ██████  ████        ████  ████    ████████  ████
  ██  ██████    ████  ██████    ██████████    ████        ████  ██    ██
  ██  ██████  ████  ██    ████  ██████████████    ████  ██████████████
                  ██████  ████████  ██    ██  ██    ██    ██      ██████
  ██████████████  ██      ██████  ██████  ████  ████████  ██  ██  ██████  ██
  ██          ██    ██████    ████    ██            ██  ████      ████  ████
  ██  ██████  ██  ████  ██  ████  ████  ██    ██      ██████████████
  ██  ██████  ██  ██    ██████    ████  ██        ██  ██████  ████  ████
  ██  ██████  ██    ██      ██████████    ██  ████      ████    ████    ████
  ██          ██          ██    ██  ██  ██      ████        ██████  ████████
  ██████████████      ██    ██    ████      ██  ████      ██      ████    ██

++++

:leveloffset!: