JsArray - JavaScript Arrays in PHP

Write JavaScript Array code in PHP. Familiar, powerful, and intuitive API for working with arrays.

If you know JavaScript arrays, you already know JsArray.

---

What is JsArray?

JsArray brings the beloved JavaScript Array methods to PHP with:

• ✅ Familiar API - Same methods, same behavior as JavaScript
• ✅ Full Type Safety - PHP 8+ with complete type hints
• ✅ Flexible - Choose immutable (safe) or mutable (fast) mode
• ✅ Pure PHP - Zero dependencies, lightweight
• ✅ Native PHP Interoperability - Behaves like a first-class PHP collection

---

Installation

composer require jsarray/jsarray

Requirements: PHP 8.0+

---

Quick Start

The Basics

use JsArray\JsArray;

$numbers = JsArray::from([1, 2, 3, 4, 5]);

// Transform data
$doubled = $numbers->map(fn($number) => $number * 2);

// Keep only matching items
$evenNumbers = $numbers->filter(fn($number) => $number % 2 === 0);

// Combine operations (method chaining)
$result = $numbers
    ->filter(fn($number) => $number > 2)
    ->map(fn($number) => $number * 10)
    ->toArray();

// Result: [30, 40, 50]

Working with Objects

$users = JsArray::from([
    ['name' => 'Alice', 'age' => 25],
    ['name' => 'Bob', 'age' => 17],
    ['name' => 'Charlie', 'age' => 30],
]);

// Get names of adults
$adultNames = $users
    ->filter(fn($user) => $user['age'] >= 18)
    ->map(fn($user) => $user['name'])
    ->toArray();

// Result: ['Alice', 'Charlie']

Flexible Callback Signatures

Use only the parameters you need:

// Just the item value
$numbers->map(fn($number) => $number * 2);

// Item and its index
$items->filter(fn($item, $index) => $index > 0);
$numbers->forEach(fn($number, $index) => echo "$index: $number");

// Full context (item, index, and array reference)
$array->map(fn($item, $index, $array) =>
    $item > ($array->length / 2) ? 'big' : 'small'
);

JsArray automatically detects which parameters your callback uses. No configuration needed!

---

Native PHP Interoperability

JsArray behaves like a first‑class PHP collection and integrates naturally with core language features.

Iteration (Iterator)

Use JsArray directly in foreach loops:

$items = JsArray::from([1, 2, 3]);

foreach ($items as $value) {
    echo $value;
}

No conversion needed.

ArrayAccess

Use JsArray as an array:

$items = JsArray::from([1, 2, 3]);

echo $items[0]; // 1
$items[0] = 10;
echo $items[0]; // 10
$items->toArray(); // [10, 2, 3]

Counting (Countable)

Use PHP’s native count() function:

$items = JsArray::from([1, 2, 3]);

echo count($items); // 3

Equivalent to:

$items->length;

JSON Serialization (JsonSerializable)

Serialize JsArray cleanly using json_encode():

$items = JsArray::from([1, 2, 3]);

echo json_encode($items);

Output:

[1, 2, 3]

Create a JsArray from a JSON string:

$json = '[1, 2, 3]';
$items = JsArray::fromJson($json);

// Now you can use JsArray methods
$doubled = $items->map(fn($n) => $n * 2);

This makes JsArray ideal for APIs, responses, and data transport without extra mapping.

---

Core Features

Transformation

$array->map(fn($item) => $item * 2);           // Transform each item
$array->filter(fn($item) => $item > 10);       // Keep matching items
$array->reduce(fn($total, $item) => $total + $item, 0);  // Combine to single value
$array->flat();                                 // Flatten nested arrays
$array->flatMap(fn($item) => [$item, $item * 2]); // Map then flatten

Search

$array->find(fn($item) => $item > 100);        // Get first match
$array->findIndex(fn($item) => $item > 100);   // Get index of first match
$array->includes(50);                          // Check if value exists
$array->indexOf(50);                           // Get index of value
$array->some(fn($item) => $item > 100);        // Check if ANY match
$array->every(fn($item) => $item > 0);         // Check if ALL match

Access

$array->first();                               // Get first item
$array->last();                                // Get last item
$array->at(0);                                 // Get item at index
$array->at(-1);                                // Get last item (negative index)
$array->length;                                // Get array length

Manipulation

$array->push($item1, $item2);                  // Add items to end
$array->pop();                                 // Remove and return last item
$array->unshift($item1, $item2);               // Add items to start
$array->shift();                               // Remove and return first item
$array->slice(1, 3);                           // Extract portion
$array->reverse();                             // Reverse order
$array->sort();                                // Sort items
$array->concat($otherArray);                   // Combine arrays
$array->join(', ');                            // Join into string

Other

$array->keys();                                // Get all keys
$array->values();                              // Get all values
$array->toArray();                              // to native php array
$array->forEach(fn($item) => echo $item);     // Execute for each item
$array->toImmutable(fn($item) => echo $item);     // Convert array to immutable
$array->toMutable(fn($item) => echo $item);     // Convert array to mutable
$array->getMutableCopy(fn($item) => echo $item);     // Create new mutable copy of array
$array->getImmutableCopy(fn($item) => echo $item);     // Create new immutable copy of array

---

Two Modes: Immutable & Mutable

Immutable Mode (Default)

Creates a new array for each operation. Original is never changed.

$original = JsArray::from([1, 2, 3]);
$doubled = $original->map(fn ($n) => $n * 2);

$original->toArray(); // [1, 2, 3]
$doubled->toArray();  // [2, 4, 6]

Use immutable when:

• Processing user input
• Data safety matters
• Building complex logic
• Working with small to medium arrays (< 10,000 items)

Mutable Mode (Fast)

Modifies the array in-place. Much faster for large datasets.

$array = JsArray::mutable([1, 2, 3, 4, 5]);

$array
    ->map(fn ($n) => $n * 2)
    ->filter(fn ($n) => $n > 2);

$array->toArray(); // [4, 6, 8, 10]

Use mutable when:

• Processing large datasets (> 50,000 items)
• Performance is critical
• Building or accumulating data
• Bulk operations (imports, migrations)

Converting Between Modes

Start with immutable, convert if needed

$array = JsArray::from([1, 2, 3]);

if ($arraySize > 50000) {
    $array->toMutable();  // Switch to mutable mode
}

Create mutable copy without affecting original

$copy = $array->getMutableCopy();
$copy->map(...)->filter(...);
echo $array->toArray();  // Original unchanged

Convert back to immutable

$safeArray = $copy->toImmutable();

Check the mode:

$array->isMutable;    // bool
$array->isImmutable;  // bool

---

Testing

Run tests:

composer test

Tests include:

• 190+ test cases
• All methods covered
• Edge cases tested
• Immutable/mutable modes tested

---

Contributing

We welcome contributions!

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure tests pass
5. Submit a pull request

---

Documentation Files

• API.md - Complete API reference
• PATTERNS.md - Common patterns and recipes
• EXAMPLES.md - Real-world usage examples
• PERFORMANCE.md - Performance analysis and tips
• MUTABILITY.md - Deep dive into mutable/immutable modes

---

License

MIT License - See LICENSE for details.

---

Support

• 🐛 Report Issues

---

Changelog

v2.1.0

✨ Enhanced native PHP interoperability:

• Iteration (Iterator): Seamless foreach loop support
• ArrayAccess: Access elements using array syntax (e.g., $array[0])
• Counting (Countable): Native count() function integration
• JSON Serialization (JsonSerializable): Direct json_encode() support
• JSON Deserialization: Create JsArray from JSON strings with fromJson()

v2.0.0

• ✨ Added mutable mode for performance
• ✨ 5 new methods (shift, unshift, indexOf, lastIndexOf, reverse)
• ✨ Flexible callback signatures (use only params you need!)
• ✨ Depth parameter for flat()
• 🐛 Fixed filter re-indexing for numeric arrays
• 📚 Comprehensive documentation files

v1.0.0

• Initial release

---

JsArray - JavaScript Arrays in PHP