diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..8a5f881
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,70 @@
+name: Bug report
+description: Report a reproducible problem
+title: "[Bug]: "
+labels:
+ - bug
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for reporting a bug. Please include enough detail to reproduce it.
+ - type: textarea
+ id: summary
+ attributes:
+ label: Summary
+ description: What is wrong?
+ placeholder: Clear and short description of the bug.
+ validations:
+ required: true
+ - type: textarea
+ id: reproduce
+ attributes:
+ label: Steps to reproduce
+ description: Share exact commands, config, and steps.
+ placeholder: |
+ 1. Run `composer ic:tests`
+ 2. ...
+ 3. Observe ...
+ validations:
+ required: true
+ - type: textarea
+ id: expected
+ attributes:
+ label: Expected behavior
+ placeholder: What did you expect to happen?
+ validations:
+ required: true
+ - type: textarea
+ id: actual
+ attributes:
+ label: Actual behavior
+ placeholder: What happened instead? Include full error output if possible.
+ validations:
+ required: true
+ - type: input
+ id: php_version
+ attributes:
+ label: PHP version
+ placeholder: "e.g. 8.3.8"
+ validations:
+ required: true
+ - type: input
+ id: composer_version
+ attributes:
+ label: Composer version
+ placeholder: "e.g. 2.9.2"
+ validations:
+ required: true
+ - type: textarea
+ id: environment
+ attributes:
+ label: Environment details
+ description: OS, CI provider, shell, and anything else relevant.
+ placeholder: Ubuntu 24.04, GitHub Actions, bash...
+ validations:
+ required: true
+ - type: textarea
+ id: additional
+ attributes:
+ label: Additional context
+ description: Links, screenshots, logs, or related issues.
diff --git a/.github/ISSUE_TEMPLATE/ci_failure.yml b/.github/ISSUE_TEMPLATE/ci_failure.yml
new file mode 100644
index 0000000..3dcbac9
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/ci_failure.yml
@@ -0,0 +1,48 @@
+name: CI failure
+description: Report a reproducible CI or workflow failure
+title: "[CI]: "
+labels:
+ - ci
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Use this form when CI fails unexpectedly and can be reproduced.
+ - type: input
+ id: workflow
+ attributes:
+ label: Workflow/job name
+ placeholder: security-standards / phpforge
+ validations:
+ required: true
+ - type: input
+ id: run_url
+ attributes:
+ label: Failing run URL
+ placeholder: https://github.com/OWNER/REPOSITORY/actions/runs/...
+ validations:
+ required: true
+ - type: textarea
+ id: command
+ attributes:
+ label: Failing command
+ description: Exact command or step that failed.
+ placeholder: composer ic:ci
+ validations:
+ required: true
+ - type: textarea
+ id: logs
+ attributes:
+ label: Error output
+ description: Paste the relevant error section.
+ render: shell
+ validations:
+ required: true
+ - type: textarea
+ id: local_check
+ attributes:
+ label: Local reproduction
+ description: Can you reproduce locally? If yes, include steps.
+ placeholder: Yes/No + details
+ validations:
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..3ba13e0
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1 @@
+blank_issues_enabled: false
diff --git a/.github/ISSUE_TEMPLATE/docs_improvement.yml b/.github/ISSUE_TEMPLATE/docs_improvement.yml
new file mode 100644
index 0000000..80b9607
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/docs_improvement.yml
@@ -0,0 +1,34 @@
+name: Docs improvement
+description: Report missing, unclear, or incorrect documentation
+title: "[Docs]: "
+labels:
+ - documentation
+body:
+ - type: textarea
+ id: location
+ attributes:
+ label: Documentation location
+ description: File path or URL.
+ placeholder: README.md section "Quick Start"
+ validations:
+ required: true
+ - type: textarea
+ id: issue
+ attributes:
+ label: What is unclear or incorrect?
+ placeholder: This section says...
+ validations:
+ required: true
+ - type: textarea
+ id: suggestion
+ attributes:
+ label: Suggested improvement
+ description: Propose revised wording, structure, or examples.
+ placeholder: It would be clearer if...
+ validations:
+ required: true
+ - type: textarea
+ id: additional
+ attributes:
+ label: Additional context
+ description: Related links, screenshots, or prior discussions.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
new file mode 100644
index 0000000..cc29614
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,44 @@
+name: Feature request
+description: Suggest an improvement or new capability
+title: "[Feature]: "
+labels:
+ - enhancement
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for the idea. Please describe the use case first, then the proposed solution.
+ - type: textarea
+ id: problem
+ attributes:
+ label: Problem or use case
+ description: What limitation are you hitting?
+ placeholder: I need to...
+ validations:
+ required: true
+ - type: textarea
+ id: proposal
+ attributes:
+ label: Proposed solution
+ description: What should happen?
+ placeholder: Add a command/config/workflow option that...
+ validations:
+ required: true
+ - type: textarea
+ id: alternatives
+ attributes:
+ label: Alternatives considered
+ description: Any workaround or alternative approach you evaluated.
+ - type: textarea
+ id: impact
+ attributes:
+ label: Expected impact
+ description: Who benefits and what changes for users/CI?
+ placeholder: This would improve...
+ validations:
+ required: true
+ - type: textarea
+ id: additional
+ attributes:
+ label: Additional context
+ description: Related issues, links, examples, or prior art.
diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml
new file mode 100644
index 0000000..2ca776f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/question.yml
@@ -0,0 +1,40 @@
+name: Question
+description: Ask a usage or integration question
+title: "[Question]: "
+labels:
+ - question
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Use this form for usage questions. For confirmed defects, use the bug report form.
+ - type: textarea
+ id: context
+ attributes:
+ label: What are you trying to do?
+ description: Describe your goal and expected outcome.
+ placeholder: I want to...
+ validations:
+ required: true
+ - type: textarea
+ id: attempted
+ attributes:
+ label: What have you tried?
+ description: Include commands, config snippets, or links you already checked.
+ placeholder: I tried...
+ validations:
+ required: true
+ - type: textarea
+ id: output
+ attributes:
+ label: Current output or behavior
+ description: Include relevant command output, logs, or errors.
+ render: shell
+ - type: textarea
+ id: environment
+ attributes:
+ label: Environment details
+ description: PHP version, Composer version, OS, CI provider (if relevant).
+ placeholder: PHP 8.3, Composer 2.9, Ubuntu 24.04...
+ validations:
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/regression_report.yml b/.github/ISSUE_TEMPLATE/regression_report.yml
new file mode 100644
index 0000000..36392bc
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/regression_report.yml
@@ -0,0 +1,51 @@
+name: Regression report
+description: Report behavior that previously worked but now fails
+title: "[Regression]: "
+labels:
+ - regression
+ - bug
+body:
+ - type: textarea
+ id: summary
+ attributes:
+ label: Regression summary
+ placeholder: This worked before, but now...
+ validations:
+ required: true
+ - type: input
+ id: last_known_good
+ attributes:
+ label: Last known working version/commit
+ placeholder: v1.2.3 or abc1234
+ validations:
+ required: true
+ - type: input
+ id: first_bad
+ attributes:
+ label: First broken version/commit
+ placeholder: v1.2.4 or def5678
+ - type: textarea
+ id: reproduce
+ attributes:
+ label: Steps to reproduce
+ placeholder: |
+ 1. ...
+ 2. ...
+ 3. ...
+ validations:
+ required: true
+ - type: textarea
+ id: expected_actual
+ attributes:
+ label: Expected vs actual behavior
+ placeholder: Expected ..., but got ...
+ validations:
+ required: true
+ - type: textarea
+ id: environment
+ attributes:
+ label: Environment details
+ description: PHP version, Composer version, OS, CI provider (if relevant).
+ placeholder: PHP 8.3, Composer 2.9, Ubuntu 24.04...
+ validations:
+ required: true
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..59ae734
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,33 @@
+## Summary
+
+Describe what changed and why.
+
+## Related Issues
+
+Link issues with `Closes #...` or `Relates #...`.
+
+## Type of Change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor
+- [ ] Documentation update
+- [ ] CI or tooling update
+- [ ] Other (describe in summary)
+
+## Validation
+
+List the commands you ran and their result.
+
+```bash
+composer ic:tests
+```
+
+If full suite was not run, explain why and list focused checks.
+
+## Checklist
+
+- [ ] I followed `CONTRIBUTING.md`.
+- [ ] I added or updated tests for behavior changes.
+- [ ] I updated docs/config/examples when needed.
+- [ ] I confirmed no security-sensitive data is exposed.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..9c2638f
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,50 @@
+# Code of Conduct
+
+## Our Commitment
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of age, body size, disability, ethnicity,
+gender identity and expression, level of experience, nationality, personal
+appearance, race, religion or sexual identity and orientation.
+
+## Expected Behavior
+
+Examples of behavior that contributes to a positive environment:
+
+- Be respectful and constructive.
+- Assume good intent and ask clarifying questions.
+- Give and receive feedback professionally.
+- Focus on what is best for the community and project.
+
+## Unacceptable Behavior
+
+Examples of unacceptable behavior include:
+
+- Harassment, discrimination or personal attacks.
+- Trolling, insulting or derogatory comments.
+- Publishing private information without consent.
+- Any conduct that is inappropriate in a professional setting.
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing this code of
+conduct. They may remove, edit or reject comments, commits, code, issues, and
+other contributions that violate this policy.
+
+## Scope
+
+This code of conduct applies in all project spaces, including:
+
+- Issue trackers
+- Pull requests
+- Discussions and chat related to the project
+- Any public or private communication where someone represents the project
+
+## Reporting
+
+To report unacceptable behavior, contact project maintainers privately.
+
+## Enforcement
+
+Maintainers may take any action they deem appropriate, including warnings,
+temporary bans or permanent bans from community participation.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9950065
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,68 @@
+# Contributing
+
+Thanks for contributing.
+
+## Before You Start
+
+- Review the project code of conduct.
+- For security issues, use private reporting and avoid opening a public issue.
+- Check existing issues and pull requests first to avoid duplicates.
+
+## Local Setup
+
+Requirements:
+
+- See `README.md` for current PHP and Composer requirements.
+
+Install dependencies:
+
+```bash
+composer install
+```
+
+## Development Workflow
+
+Typical contributor workflow:
+
+1. Create a branch from `main`.
+2. Make focused changes.
+3. Run quality checks locally.
+4. Open a pull request with context and verification notes.
+
+Recommended checks:
+
+```bash
+composer ic:tests
+```
+
+Useful targeted commands:
+
+```bash
+composer ic:test:syntax
+composer ic:test:code
+composer ic:test:lint
+composer ic:test:sniff
+composer ic:test:static
+composer ic:test:security
+composer ic:test:architecture
+```
+
+Auto-fix and processing helpers:
+
+```bash
+composer ic:process
+```
+
+## Pull Request Guidelines
+
+- Keep pull requests scoped to one logical change.
+- Include why the change is needed and what behavior changed.
+- Add or update tests when behavior changes.
+- Update docs when command behavior, config, or workflow behavior changes.
+- Ensure CI is green before requesting review.
+
+## Reporting Bugs and Requesting Features
+
+- Use issue templates for bugs, regressions, CI failures, documentation updates, questions, and feature requests.
+- Include reproducible steps, expected behavior, and actual behavior.
+- Share environment details (PHP version, OS, Composer version).
diff --git a/README.md b/README.md
index 6eca2b4..3bf189d 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
# ArrayKit
-[](https://github.com/infocyph/arraykit/actions/workflows/security-standards.yml)
-
+[](https://github.com/infocyph/ArrayKit/actions/workflows/security-standards.yml)
+
[](https://opensource.org/licenses/MIT)
-
-
-
+
+
+
[](https://docs.infocyph.com/projects/arraykit/)
**ArrayKit** is a modern **PHP 8.4+** library for elegant, high-performance **array manipulation**, **dot notation
@@ -13,7 +13,7 @@ utilities**, **dynamic configuration**, **hookable collections**, and more.
From shallow single arrays to deeply nested data structures — **ArrayKit** provides a fluent, reliable toolkit for
real-world PHP projects.
-## 📦 Features at a Glance
+## Features at a Glance
- **Single-Dimensional Helpers**
- **Multi-Dimensional Helpers**
@@ -25,9 +25,9 @@ real-world PHP projects.
- **Pipeline for Collection Ops**
- **Global Helpers (`functions.php`)**
-## 📚 Modules
+## Modules
-### ➤ Array Helpers
+### Array Helpers
| Helper | Description |
|---------------------|----------------------------------------------------------------------------------------------------|
@@ -37,7 +37,7 @@ real-world PHP projects.
| **BaseArrayHelper** | Internal shared base for consistent API across helpers. |
| **ArraySharedOps** | Internal shared operations used by `ArraySingle` and `ArrayMulti` (`each/every/partition/skip*`). |
-### ➤ Config System
+### Config System
| Class | Description |
|---------------------|---------------------------------------------------------------------------------------------------------------------|
@@ -46,7 +46,7 @@ real-world PHP projects.
| **BaseConfigTrait** | Shared config logic. |
-### ➤ Collections
+### Collections
| Class | Description |
|-------------------------|--------------------------------------------------------------------------------------------|
@@ -56,7 +56,7 @@ real-world PHP projects.
| **BaseCollectionTrait** | Shared collection behavior. |
-### ➤ Traits
+### Traits
| Trait | Description |
|---------------|------------------------------------------------------------------------------------------------|
@@ -64,7 +64,7 @@ real-world PHP projects.
| **DTOTrait** | Utility trait for DTO-like behavior: populate, extract, cast arrays/objects easily. |
-### ➤ Global Helpers
+### Global Helpers
| File | Description |
|-------------------|------------------------------------------------------------|
@@ -76,20 +76,20 @@ real-world PHP projects.
|-------------------|-----------------------------------------------------------------------------------------------|
| **ArrayKit** | Single entry point for arrays, dot tools, config, and collections (`single()`, `multi()`, etc.). |
-## ✅ Requirements
+## Requirements
* **PHP 8.4** or higher
-## ⚡ Installation
+## Installation
```bash
composer require infocyph/arraykit
```
-## 🚀 Quick Examples
+## Quick Examples
-### 🔹 One Facade Entry Point
+### One Facade Entry Point
```php
use Infocyph\ArrayKit\ArrayKit;
@@ -102,7 +102,7 @@ $config = ArrayKit::config(['app' => ['env' => 'local']]);
$env = $config->get('app.env'); // local
```
-### 🔹 Single-Dimensional Helpers
+### Single-Dimensional Helpers
```php
use Infocyph\ArrayKit\Array\ArraySingle;
@@ -119,7 +119,7 @@ $dupes = ArraySingle::duplicates($list); // [2]
$page = ArraySingle::paginate($list, page:1, perPage:2); // [1, 2]
```
-### 🔹 Multi-Dimensional Helpers
+### Multi-Dimensional Helpers
```php
use Infocyph\ArrayKit\Array\ArrayMulti;
@@ -139,7 +139,7 @@ $depth = ArrayMulti::depth($data); // 3
$sorted = ArrayMulti::sortRecursive($data);
```
-### 🔹 Dot Notation
+### Dot Notation
```php
use Infocyph\ArrayKit\Array\DotNotation;
@@ -163,7 +163,7 @@ DotNotation::set($user, 'users.*.active', true);
// [ 'profile.name' => 'Alice', 'profile.email' => 'alice@example.com' ]
```
-### 🔹 Config Hooks (Explicit)
+### Config Hooks (Explicit)
```php
use Infocyph\ArrayKit\Config\Config;
@@ -184,7 +184,7 @@ $config->setWithHooks('auth.password', 'secret123');
$hashed = $config->getWithHooks('auth.password');
```
-### 🔹 Hooked Collection
+### Hooked Collection
```php
use Infocyph\ArrayKit\Collection\HookedCollection;
@@ -220,11 +220,19 @@ $user->fromArray(['name' => 'Alice', 'email' => 'alice@example.com']);
$array = $user->toArray();
```
-## 🤝 Support
+## Security
-Have a bug or feature idea? Please [open an issue](https://github.com/infocyph/arraykit/issues).
+Protected by [PHPForge](https://github.com/infocyph/PHPForge) — an automated quality and security gate for PHP projects.
-## 📄 License
+---
-Licensed under the **MIT License** — use it freely for personal or commercial projects. See [LICENSE](LICENSE) for
-details.
+
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..37a355e
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,49 @@
+# Security Policy
+
+## Supported Versions
+
+The project currently supports security updates for the latest release.
+
+## Reporting a Vulnerability
+
+Please report vulnerabilities privately.
+
+1. Use GitHub private vulnerability reporting for this repository (`Security` -> `Advisories` -> `Report a vulnerability`).
+2. If private reporting is unavailable, contact maintainers through a private channel.
+3. Do not open a public issue for security vulnerabilities.
+
+Please include:
+
+- Affected package version(s)
+- PHP version and runtime environment
+- Reproduction steps or proof of concept
+- Impact assessment (confidentiality/integrity/availability)
+- Any known workaround
+
+## Response Process
+
+- Initial acknowledgment: best effort, typically within a few days
+- Triage: best effort, based on maintainer availability
+- Fix and release timeline depends on severity and exploitability
+
+If a report is accepted, a patched release will be prepared and published. Credit will be provided unless you request otherwise.
+
+## Protected by PHPForge
+
+This project is protected by [PHPForge](https://github.com/infocyph/PHPForge), an automated quality and security tooling layer for Infocyph PHP projects.
+
+PHPForge helps keep the project reliable by running checks for:
+
+- Code style and standards
+- Tests and syntax validation
+- Static analysis and type safety
+- Security and taint analysis
+- Dependency vulnerability audit
+- Architecture boundary validation
+- Duplicate-code detection
+- API snapshot and comment-policy checks
+- Refactor safety checks
+- Benchmark and release-readiness checks
+- Git hooks and CI workflow protection
+
+These automated gates strengthen code quality, reduce security risk and help prevent regressions before merge or release.
diff --git a/src/Array/Concerns/ArrayMultiQuerySortTrait.php b/src/Array/Concerns/ArrayMultiQuerySortTrait.php
index 74bf937..34bd904 100644
--- a/src/Array/Concerns/ArrayMultiQuerySortTrait.php
+++ b/src/Array/Concerns/ArrayMultiQuerySortTrait.php
@@ -188,13 +188,9 @@ public static function mapWithKeys(array $array, callable $callback): array
*/
public static function max(array $array, string|callable $keyOrCallback): float|int|null
{
- $max = self::selectExtremeValue($array, $keyOrCallback, pickMax: true);
-
- if ($max === null) {
- return null;
- }
-
- return fmod($max, 1.0) === 0.0 ? (int) $max : $max;
+ return self::formatNumericResult(
+ self::selectExtremeValue($array, $keyOrCallback, pickMax: true),
+ );
}
/**
@@ -214,13 +210,9 @@ public static function maxBy(array $array, string|callable $keyOrCallback): mixe
*/
public static function min(array $array, string|callable $keyOrCallback): float|int|null
{
- $min = self::selectExtremeValue($array, $keyOrCallback, pickMax: false);
-
- if ($min === null) {
- return null;
- }
-
- return fmod($min, 1.0) === 0.0 ? (int) $min : $min;
+ return self::formatNumericResult(
+ self::selectExtremeValue($array, $keyOrCallback, pickMax: false),
+ );
}
/**
@@ -534,6 +526,15 @@ private static function extractSummableValue(mixed $row, string|callable|null $k
return 0.0;
}
+ private static function formatNumericResult(?float $value): float|int|null
+ {
+ if ($value === null) {
+ return null;
+ }
+
+ return fmod($value, 1.0) === 0.0 ? (int) $value : $value;
+ }
+
private static function normalizeArrayKey(mixed $value): int|string
{
return ArraySharedOps::normalizeArrayKey($value);
diff --git a/src/Collection/Pipeline.php b/src/Collection/Pipeline.php
index 492bcd2..3a0a694 100644
--- a/src/Collection/Pipeline.php
+++ b/src/Collection/Pipeline.php
@@ -297,9 +297,9 @@ public function median(): float|int
*/
public function mergeRecursiveDistinct(array $overlay): Collection
{
- $this->working = ArrayMulti::mergeRecursiveDistinct($this->working, $overlay);
-
- return $this->collection;
+ return $this->mutateWorking(
+ fn(array $working): array => ArrayMulti::mergeRecursiveDistinct($working, $overlay),
+ );
}
/**
@@ -708,6 +708,18 @@ public function wrap(): Collection
return $this->collection;
}
+ /**
+ * Apply a transform to the current working set and keep the chain alive.
+ *
+ * @param callable(array): array $transform
+ */
+ private function mutateWorking(callable $transform): Collection
+ {
+ $this->working = $transform($this->working);
+
+ return $this->collection;
+ }
+
private function numericAggregate(string|callable|null $keyOrCallback, bool $pickMax): float|int|null
{
if ($keyOrCallback === null) {