README

Enterprise LINQ-Style Collection Framework for PHP 8.4+
A fluent, expressive, and type-safe collection manipulation engine bringing the elegance of .NET Language Integrated Query (LINQ) to PHP. Powered by PHP 8.4 native array primitives (array_any, array_all, array_find, array_find_key), generator-based streaming pipelines (ALinqLazyCollection), advanced set theory, dynamic predicate query builders, dot-notation deep property resolution, and seamless bidirectional synergy with Antevemus.ASpecification.

🇺🇸 English • 🇧🇷 Português (Brasil)

The documentation lives in docs/en (English) and docs/pt-BR (Portuguese, Brazil), one page per topic, in the Docs Kit format (a docs-nav.json per language). The API Reference keeps the section numbers it had in this README (§9 is still ### 9., now on its own page), and every PHP block of the pages is checked by the test suite.

🚀 Quick Start

The same block opens Getting Started, and the test suite runs it with the answers written in its comments:

<?php

declare(strict_types=1);

use Antevemus\ALinq\ALinqCollection;

$users = ALinqCollection::from([
    ['id' => 1, 'name' => 'Alice', 'role' => 'admin', 'score' => 95, 'active' => true],
    ['id' => 2, 'name' => 'Bob', 'role' => 'editor', 'score' => 82, 'active' => true],
    ['id' => 3, 'name' => 'Charlie', 'role' => 'viewer', 'score' => 60, 'active' => false],
    ['id' => 4, 'name' => 'Diana', 'role' => 'admin', 'score' => 91, 'active' => true],
    ['id' => 5, 'name' => 'Evan', 'role' => 'editor', 'score' => 74, 'active' => true],
]);

// 1. Fluent Query Pipeline
$topActiveAdmins = $users
    ->where(fn($u) => $u['active'] && $u['role'] === 'admin')
    ->orderByDescending(fn($u) => $u['score'])
    ->select(fn($u) => sprintf('%s (%d pts)', $u['name'], $u['score']))
    ->toArray();

// Result: ['Alice (95 pts)', 'Diana (91 pts)']

// 2. High-Performance Aggregations (Native PHP 8.4)
$hasSuperUser = $users->any(fn($u) => $u['score'] > 90);      // true (via array_any)
$allActive    = $users->all(fn($u) => $u['active']);          // false (via array_all)
$avgScore     = $users->average(fn($u) => $u['score']);       // 80.4
$bestUser     = $users->maxBy(fn($u) => $u['score']);         // ['id' => 1, 'name' => 'Alice'...]

// 3. Grouping & Sub-Collection Aggregations
$roleStats = $users
    ->groupBy(fn($u) => $u['role'])
    ->select(fn(ALinqCollection $group, string $role) => [
        'role'        => $role,
        'count'       => $group->count(),
        'avg_score'   => $group->average(fn($u) => $u['score']),
        'top_performer' => $group->maxBy(fn($u) => $u['score'])['name'],
    ])
    ->toArray();

📦 Installation

Install via Composer: composer require antevemus/alinq-collection. Requirements: PHP 8.4 or later, and one dependency, installed with it: antevemus/adeep-property-access (from the same author, with no dependencies of its own), the property accessor shared with Antevemus.ASpecification. Upgrading from 1.x: see UPGRADE-2.0.md. Installing from the Git VCS repository: Getting Started.

📚 Documentation

One line per page, grouped as in the navigation; §N is the section of the API Reference that the page hosts, numbered as in the former README.

Getting started

Installation and quick start · pt-BR: Composer, the Git VCS repository and the Quick Start.

Concepts

Origins and philosophy · pt-BR: Why LINQ in PHP, and the six design principles of the library.
Core features · pt-BR: Every operator of the library in one table, by domain.
Architecture · pt-BR: The source tree: the main classes, the 11 interfaces and the 8 traits.
Synergy with ASpecification · pt-BR: ASpecification rules evaluated over ALinq collections through ALinqBridge.

API reference

Factories (§1) · pt-BR: from(), range(), repeat(), empty(), toArray() and toObject().
Filtering and slicing (§2) · pt-BR: where(), take()/skip(), distinct(), first(), chunk() and the field filters whereIn(), whereNotIn(), whereBetween().
Joining and set theory (§3) · pt-BR: Inner and outer joins, groupJoin(), the set operations and exceptByKeys()/intersectByKeys(), with an equality comparer since 2.4.0.
Aggregations and metrics (§4) · pt-BR: any(), all(), sum(), average(), min()/max(), single() and the *OrDefault() aggregates.
Projections and transformations (§5) · pt-BR: select(), selectMany(), column(), toDictionary(onDuplicate:) and toLookup().
Grouping and partitioning (§6) · pt-BR: groupBy() into sub-collections, and ALinqLookup, a materialized groupBy().
Sorting and ordering (§7) · pt-BR: Stable orderBy()/thenBy(), natural and custom orderings, and StringComparer.
Dynamic query builder (§8) · pt-BR: ALinqQueryBuilder: conditions in and/or mode, its operators and toPredicate().
Deep property access (§9) · pt-BR: Dot-notation paths, the resolution order and the #[Specifiable] opt-in for non-public properties.
Streaming and big data (§10) · pt-BR: ALinqLazyCollection: files, CSV, database cursors, paginated HTTP, remember() and the stages that accumulate data.
The contract (§11) · pt-BR: The rules both collections obey: keys, equality, group keys, empty collections, ordering, comparers, arguments and more.

Quality

Tests · pt-BR: The PHPUnit report, the measured coverage and the mutation testing.

Project

Roadmap · pt-BR: Every release shipped and what comes next; the milestone view is in ROADMAP.md.
License and authors · pt-BR: The MIT license, the author and the organization.

🧪 Quality

Tests: 836 PHPUnit tests (vendor/bin/phpunit) over the 8 traits, the streaming engine, the eager × lazy contract and the code blocks of the documentation, 100% passing on PHP 8.4.
Assertions: 4631 without ext-intl (the 17 tests of StringComparer::culture() skipped) and 4772 with it (1 skipped, the test of the missing extension); the CI runs both legs.
Coverage (pcov, 2.2.0, with ext-intl): 289 of 299 methods and 1619 of 1637 lines of src/; the 18 uncovered lines are defensive guards or depend on the environment.
Mutation testing: Infection on the lines changed since 2.1.0, MSI 97.59% (10 escaped mutants, all equivalent).
Contract parity: every shared operation runs over the same inputs on the eager and the lazy collection, with zero divergences allowed (tests/Contract/ParityTest.php; the rules: The contract).
The report, the coverage details and the mutation run: Tests.

🗺️ Roadmap & Ecosystem

Every release shipped and what comes next: Roadmap. The milestone view, with target releases: 👉 ROADMAP.md.

📄 License & Authors

This software is open-source, licensed under the MIT License.

Author: Heliton Junior (CTO) — contato@antevemus.com.br
Organization: Antevemus Soluções Inovadoras em TI Ltda.

antevemus / alinq-collection

Package info

Security

Statistics