PHPackages                             neiaozora/memory-manager - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. neiaozora/memory-manager

ActiveLibrary[Utility & Helpers](/categories/utility)

neiaozora/memory-manager
========================

2.0(1y ago)04MITPHPPHP >=8.0

Since Jan 20Pushed 1y ago1 watchersCompare

[ Source](https://github.com/NeiAozora/Memory-Manager)[ Packagist](https://packagist.org/packages/neiaozora/memory-manager)[ RSS](/packages/neiaozora-memory-manager/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependenciesVersions (3)Used By (0)

MemoryManager
=============

[](#memorymanager)

**A Lightweight PHP Library for Byte Manipulation and Memory Management**

Overview
--------

[](#overview)

The **MemoryManager** library provides an efficient and intuitive way to manipulate byte data and manage memory streams in PHP. It is designed for handling data-heavy use cases, such as working with binary files like `.png`, `.wad`, or other formats. The library supports two memory management systems:

- **Hard Reference System**: Traditional PHP object references with manual memory management.
- **Weak Reference System**: Uses PHP's `WeakReference` to allow automatic garbage collection when objects are no longer referenced.

The library is built around a base class (`Memory`) that abstracts core functionality. Two implementations are provided out of the box:

- **`MemoryStream`**: Allocates memory in RAM for byte manipulation.
- **`TempMemory`**: Starts with memory storage but switches to temporary files for large data.

Features
--------

[](#features)

- **Byte Manipulation**: Easily write and read byte arrays or binary data.
- **Dynamic Storage**: Use in-memory storage for small data or transition to temporary files for larger datasets.
- **Dual Memory Management**:
    - **Hard Reference System**: Traditional PHP references with explicit memory management.
    - **Weak Reference System**: Automatic garbage collection using `WeakReference`.
- **Extensible**: Extend the `Memory` base class to create custom storage solutions.
- **Simple API**: Perform operations with minimal code: ```
    $streamMem->writeBytes($arrayOfBytes);
    $data = $streamMem->readBytes();
    ```

Installation
------------

[](#installation)

### Via Composer

[](#via-composer)

Install the library using Composer:

```
composer require neiaozora/memory-manager
```

### Manual Installation

[](#manual-installation)

Clone the repository or download it directly from GitHub:

```
git clone https://github.com/NeiAozora/MemoryManager.git
```

Include the library in your project:

```
require_once 'vendor/autoload.php';
```

Usage
-----

[](#usage)

### Example: Demonstrating Hard Reference and Weak Reference Systems

[](#example-demonstrating-hard-reference-and-weak-reference-systems)

The following example demonstrates the hard reference and weak reference systems using the `MemoryStream` class. It also includes a `printMemoryUsage()` function to debug memory usage.

```
use NeiAozora\MemoryManager\MemoryStream;

require_once "vendor/autoload.php";

// Function to debug memory usage
function printMemoryUsage() {
    $bytes = memory_get_usage();
    $kilobytes = $bytes / 1024;
    $megabytes = $kilobytes / 1024;

    printf(
        "Memory Usage: %d Bytes | %.2f KB | %.2f MB\n",
        $bytes,
        $kilobytes,
        $megabytes
    );
}

// File size is 512KB
$file = "random.bin";

// Print initial memory usage
printMemoryUsage();

// 1. Hard Reference System
$mem = new MemoryStream(); // Creates a hard-referenced object
$mem->write(file_get_contents($file)); // Writes 512KB of data to memory

// Print memory usage after writing data
printMemoryUsage();

// Free memory by unsetting the hard reference
unset($mem);

// Print memory usage after freeing memory
printMemoryUsage();

// 2. Weak Reference System
$weakRefMemory = MemoryStream::new(); // Creates a weak-referenced object
$weakRefMemory->get()->write(file_get_contents($file)); // Writes 512KB of data to memory

// Print memory usage after writing data
printMemoryUsage();

// Free memory by destroying the weak reference
$weakRefMemory->get()->destroy();

// Print memory usage after freeing memory
printMemoryUsage();
```

Another usage examples
----------------------

[](#another-usage-examples)

```
require_once 'vendor/autoload.php';

use NeiAozora\MemoryManager\MemoryStream;
use NeiAozora\MemoryManager\TempMemory;

// Usage
// 1. Writing and Reading Bytes
// Example: Using MemoryStream

use NeiAozora\MemoryManager\MemoryStream;

$memory = new MemoryStream(); // uses Hard reference mode

// Write an array of bytes (8-bit values between 0 and 255) to memory
$bytes = [1, 2, 3, 4, 255];
$memory->writeBytes($bytes);

// Write binary data as a string to memory (don't ask me why it's a string, ask PHP due to its quirks)
// $data = 'Hello, World!';
// or
// $data = file_get_contents("example.png");
// $memory->write($data);

// Read back the data
$data = $memory->readBytes();
print_r($data); // Outputs: [1, 2, 3, 4, 255]

// Read data from the stream
$data = $memory->read();
echo $data;

// The memory will be released once it's no longer needed
unset($memory);

// Example: Using TempMemory

use NeiAozora\MemoryManager\TempMemory;

$tempMemory = new TempMemory();

// Write binary data to the temp stream
$tempMemory->writeBytes([10, 20, 30]);

// Read data from the stream
$data = $tempMemory->read();
echo $data;

// Release memory
unset($tempMemory);
```

Using with Custom File Formats
------------------------------

[](#using-with-custom-file-formats)

Easily handle file data like .png or .wad by reading their raw bytes into memory, manipulating the byte data, and writing it back.

```
$file = fopen('example.png', 'rb');
$memory = new MemoryStream();

while (!feof($file)) {
    $chunk = fread($file, 1024);
    $memory->write($chunk);
}

fclose($file);

// Perform operations on the byte data in $memory
$data = $memory->read();

// Save it back to a new file
$newFile = fopen('modified.png', 'wb');
fwrite($newFile, $data);
fclose($newFile);

// Cleanup
unset($memory);
```

Extensibility
-------------

[](#extensibility)

To create your own custom memory management solution, extend the Memory base class and define the openStream method.

```
use NeiAozora\MemoryManager\Memory;
use NeiAozora\MemoryManager\IOException;

class CustomMemory extends Memory
{
    protected function openStream()
    {
        $this->stream = fopen('php://custom', 'wb+');
        if (!$this->stream) {
            throw new IOException("Failed to open custom stream.");
        }
    }
}
```

Memory Management Systems Explained
-----------------------------------

[](#memory-management-systems-explained)

### 1. Hard Reference System

[](#1-hard-reference-system)

**How It Works**: Objects are created using traditional PHP references. Memory is managed manually by calling `unset()`.

**Behavior**:

- When `$mem` is created, it holds a strong reference to the `MemoryStream` object.
- Calling `unset($mem)` explicitly frees the memory, reducing memory usage.

**Use Case**: Ideal for scenarios where you need full control over memory management.

### 2. Weak Reference System

[](#2-weak-reference-system)

**How It Works**: Objects are wrapped in PHP's `WeakReference`, allowing them to be garbage-collected when no longer referenced. You can still explicitly free memory using `destroy()`.

**Behavior**:

- When `$weakRefMemory` is created, it holds a weak reference to the `MemoryStream` object.
- Calling `$weakRefMemory->get()->destroy()` explicitly frees the memory, reducing memory usage.

**Use Case**: Ideal for scenarios where you want to avoid memory leaks and rely on automatic garbage collection.

Detailed Explanation of Weak Reference Usage Rules
--------------------------------------------------

[](#detailed-explanation-of-weak-reference-usage-rules)

### Important Weak Reference Usage Rules

[](#important-weak-reference-usage-rules)

When using the weak reference system with `::new()`, observe the following rules to ensure proper memory management:

### 1. Do Not Assign the Weakly Referenced Object to a Strong Reference

[](#1-do-not-assign-the-weakly-referenced-object-to-a-strong-reference)

When calling `$weakRefMemory->get()`, it returns a strong reference to the object. If you assign this strong reference to another variable, it increments the reference count, preventing the object from being freed as expected by the garbage collector.

**Example of Incorrect Usage**:

```
$weakRefMemory = MemoryStream::new(); // The object of Memory class now has a reference count of 1 (held inside the Class $memory attribute).
$mem = $weakRefMemory->get();  // This creates a strong reference to the object, increasing the reference count to 2.
$mem->destroy();                // This only frees the reference from within the Class $memory attribute, reducing the reference count to 1.
unset($mem);                    // Now the object may be freed because $mem was the strong reference holding the last reference to the object.
```

**Why This Breaks the Intended Lifecycle**:

- The object remains alive as long as `$mem` holds the strong reference, preventing it from being freed until `unset($mem)` is called.

### 2. Only Use `WeakReference::get()` Directly

[](#2-only-use-weakreferenceget-directly)

Manipulate the object directly using the weak reference wrapper without creating a strong reference. This ensures the object can be freed as soon as it is no longer in use.

**Example of Correct Usage**:

```
$weakRefMemory = MemoryStream::new();
$weakRefMemory->get()->write(file_get_contents($file)); // Write data
$weakRefMemory->get()[0] = 0;  // Assign byte value 0 to offset 0
$weakRefMemory->get()->destroy();  // Frees memory when done
```

**Why This Works**:

- The object is only weakly referenced, and it will be freed when no other strong references remain.

### Key Rule:

[](#key-rule)

Do not assign the object referenced by a weak reference to any new variable or hold a strong reference to it after calling `get()`. This ensures the object can be freed when it's no longer needed.

Why Weak References?
--------------------

[](#why-weak-references)

Weak references are essential for efficient memory management in low-level operations. The library uses PHP's `WeakReference` to avoid increasing reference counts, allowing objects to be garbage-collected when no longer referenced. However, you can explicitly free memory `destroy()`.

### Key Points:

[](#key-points)

- Objects are eligible for garbage collection when no other references exist.
- Explicitly call `destroy()` to free memory immediately.
- Weak references prevent memory leaks in long-running applications.

Supported PHP Versions
----------------------

[](#supported-php-versions)

- Only PHP 8+

Contributing
------------

[](#contributing)

Contributions are welcome! Feel free to:

- Submit pull requests.
- Report issues or suggest improvements in the GitHub repository.

License
-------

[](#license)

This project is licensed under the MIT License. See the LICENSE file for details.

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance42

Moderate activity, may be stable

Popularity3

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~12 days

Total

2

Last Release

471d ago

Major Versions

1.0 → 2.02025-02-02

PHP version history (2 changes)1.0PHP >=7.4

2.0PHP >=8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/48c8c9b4a0375c4ed592c5a922db3c305bf74689e5fc4131fd0cfa0697a2bd6c?d=identicon)[NeiAozora](/maintainers/NeiAozora)

---

Top Contributors

[![NeiAozora](https://avatars.githubusercontent.com/u/92843449?v=4)](https://github.com/NeiAozora "NeiAozora (12 commits)")

### Embed Badge

![Health badge](/badges/neiaozora-memory-manager/health.svg)

```
[![Health](https://phpackages.com/badges/neiaozora-memory-manager/health.svg)](https://phpackages.com/packages/neiaozora-memory-manager)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)