README

A lightweight and modular core library for modern PHP development. Designed for clarity, extensibility, and performance, with a consistent, functional-style API.

Table of Contents

• ✨ Core Packages
• 📚 Documentation
• 📦️ Installation
• 💡 Features
• 🚀 Quick Start
• 🧪 Examples
• ✅ Running Unit Tests
• 🤝 Contributing
• 🧾 License
• 👤 About the author

Core Packages

The library provides a suite of pure, side-effect-free utility functions organized into logical namespaces. Here’s a summary of what each package offers:

Documentation

Full project documentation is available at: 👉 https://bcommebois.github.io/oihana-php-core

• Changelog: CHANGELOG.md
• License: MPL-2.0

Installation

Requires PHP 8.4+

Install via Composer:

composer require oihana/php-core

Features

The oihana/php-core library provides pure utility functions (no side effects), organized into logical, reusable packages:

🧾 Accessors (oihana\core\accessors)

Unified access for both arrays and objects:

• Read: getKeyValue()
• Write: setKeyValue()
• Delete: deleteKeyValue() (supports wildcards: *, foo.bar.*)
• Exists: hasKeyValue()
• Validation and traversal: assertDocumentKeyValid(), resolveReferencePath()

🔢 Arrays (oihana\core\arrays)

Advanced array utilities:

• Access and mutation: get(), set(), delete(), exists()
• Transformations: flatten(), tail(), unique(), shuffle(), swap(), toArray(), stub()
• Structure detection: isIndexed(), hasIntKeys(), hasStringKeys()
• Merging: deepMerge() (lists appended), overlay() (tables merged key by key, lists replaced whole — the way a configuration file overrides its defaults)

⏰ Cron (oihana\core\cron)

Reading cron expressions:

• cronFieldValues() — the values one field matches (*, 3, 1-5, 0,30, steps), or null rather than a guess
• cronScheduleGap() — the longest time a schedule can leave between two runs (30 2 * * 1-5 → 72 hours, across the weekend), or null for a schedule it will not guess at

📅 Date (oihana\core\date)

Date manipulation and validation:

• formatDateTime()
• isDate(), isValidTimezone()
• now()
• nextTimeOfDay() — the next moment it is HH:MM, strictly after a given one

📄 Documents (oihana\core\documents)

Template and placeholder resolution:

• formatDocument()
• resolvePlaceholders()

💻 Env (oihana\core\env)

Environment detection helpers:

• OS detection: isLinux(), isMac(), isWindows()
• Environment type: isCli(), isWeb(), isDocker()
• PHP info: phpVersion(), isExtensionLoaded()
• PATH: completePath() — adds the standard directories a PATH lacks, at its end ; programLocations() — where a PATH finds each program

🧬 JSON (oihana\core\json)

Advanced JSON utilities:

• deepJsonSerialize()
• isValidJsonEncodeFlags(), isValidJsonDecodeFlags()

➗ Maths (oihana\core\maths)

Smart numeric rounding helpers:

• ceilValue(), floorValue(), roundValue()
• Float noise: shedFloatNoise() — sheds the binary noise of a computed figure by significant digits, never a business rounding ; scale: reckons them on the largest term of a sum whose terms cancel
• Geolocation: haversine(), bearing()

🔢 Numbers (oihana\core\numbers)

• Range clamping: clip()

🧱 Objects (oihana\core\objects)

Lightweight object manipulation:

• compress() — remove null/empty values
• set() — deep set a value in a nested structure
• toAssociativeArray()

⚙️ Reflections (oihana\core\reflections)

• Function analysis: getFunctionInfo()

✍️ Strings (oihana\core\strings)

String formatting, case conversions, and utilities:

• Case & slug: camel(), snake(), kebab(), hyphenate(), lower(), latinize()
• Format & identifiers: fastFormat(), formatRequestArgs(), urlencode(), toString()
• Validation: isRegexp(), luhn()
• Random generation: randomKey() — and, in oihana\core\encoding, randomHex(), randomBase64Url() and randomPassword() (letters and digits, without the five that are misread)
• Comparison: differingLines() — how many lines two texts differ by, order aside

🛠️ Utils (oihana\core)

General-purpose helpers:

• ifNull() — return a fallback if a value is null
• isLiteral() — check if a value is a literal

Quick Start

Most helpers are loaded via Composer autoload. You can import functions directly using use function and call them.

<?php
require __DIR__ . '/vendor/autoload.php';

use function oihana\core\strings\camel;
use function oihana\core\strings\fastFormat;
use function oihana\core\arrays\get;
use function oihana\core\accessors\getKeyValue;
use function oihana\core\accessors\setKeyValue;

// Strings
echo camel('hello_world');                 // helloWorld
echo fastFormat('Hello {0}', 'World');     // Hello World

// Arrays (dot-notation path)
$profile = ['user' => ['name' => 'Alice', 'city' => 'Paris']];
echo get($profile, 'user.name');           // Alice

// Accessors work with arrays and objects
$doc = (object)['user' => (object)['email' => 'a@b.c']];
echo getKeyValue($doc, 'user.email');      // a@b.c
$doc = setKeyValue($doc, 'user.age', 30);  // adds nested property safely

Examples

Accessors: work with arrays and objects

use function oihana\core\accessors\getKeyValue;
use function oihana\core\accessors\setKeyValue;

$doc = ['user' => ['name' => 'Alice']];
echo getKeyValue($doc, 'user.name');            // Alice
$doc = setKeyValue($doc, 'user.age', 30);       // ['user' => ['name' => 'Alice', 'age' => 30]]

$obj = (object)['user' => (object)['email' => 'a@b.c']];
echo getKeyValue($obj, 'user.email');           // a@b.c
$obj = setKeyValue($obj, 'user.active', true);  // adds nested object structure

Arrays: reading and transforming

use function oihana\core\arrays\get;
use function oihana\core\arrays\flatten;
use function oihana\core\arrays\unique;

$data = ['a' => 1, 'b' => ['c' => 2, 'd' => [3, 4]]];
echo get($data, 'b.c');               // 2
print_r(flatten($data));              // ['a' => 1, 'b.c' => 2, 'b.d.0' => 3, 'b.d.1' => 4]
print_r(unique([1,1,2,3,3]));         // [1,2,3]

Strings: formatting and cases

use function oihana\core\strings\camel;
use function oihana\core\strings\fastFormat;

echo camel('foo-bar_baz');                        // fooBarBaz
echo fastFormat('User {0} has {1} points', 'Alice', 1500);
// User Alice has 1500 points

Objects: cleaning data

use function oihana\core\objects\compress;

$user = (object)[
    'name' => 'John',
    'email' => 'john@example.com',
    'phone' => null,
    'address' => ''
];

// Removes all null and empty string values
print_r(compress($user));
/*
stdClass Object
(
    [name] => John
    [email] => john@example.com
)
*/

Date: formatting

use function oihana\core\date\formatDateTime;

echo formatDateTime('2023-10-27 10:00:00', 'Europe/Paris', 'd/m/Y H:i'); // 27/10/2023 10:00

// The default format ends on a literal Z, the ISO-8601 designator for UTC,
// so the moment is converted before being labelled.
echo formatDateTime('2023-10-27T10:00:00+02:00'); // 2023-10-27T08:00:00.000Z

Numbers: clamping a value

use function oihana\core\numbers\clip;

echo clip(15, 0, 10); // 10
echo clip(-5, 0, 10); // 0
echo clip(5, 0, 10);  // 5

Running Unit Tests

To run all tests:

$ composer test

To run a specific test file:

$ composer test tests/oihana/core/arrays/FlattenTest.php

Static Analysis (PHPStan)

The library is analysed with PHPStan at the strictest level (max). The configuration lives in phpstan.neon.

$ composer phpstan

Findings that pre-date the introduction of static analysis are frozen in phpstan-baseline.neon, so the command is green and only reports new issues — keeping every future change held to the max bar. The goal is to shrink the baseline over time: once you legitimately fix some of its entries, regenerate it with

$ composer phpstan:baseline

PHPStan does not need Xdebug and is independent from the test suite.

Contributing

Contributions are welcome! Whether you're fixing a bug, improving an existing feature, or proposing a new one, your help is appreciated.

Please feel free to:

• Report a bug: If you find a bug, please open an issue and provide as much detail as possible.
• Suggest an enhancement: Have an idea to make this library better? Open an issue to discuss it.
• Submit a pull request: Fork the repository, make your changes, and open a pull request. Please ensure all tests are passing before submitting.

You can find the issues page here: https://github.com/BcommeBois/oihana-php-core/issues

License

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

About the author

• Author : Marc ALCARAZ (aka eKameleon)
• Mail : marc@ooop.fr
• Website : http://www.ooop.fr