PHPackages                             randomphp/scoped - 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. [Framework](/categories/framework)
4. /
5. randomphp/scoped

ActiveLibrary[Framework](/categories/framework)

randomphp/scoped
================

A small library implementing DI scopes on top of PHP-DI

0.1.0(2mo ago)01UNLICENSEPHPPHP >=8.4

Since Feb 18Pushed 2mo agoCompare

[ Source](https://github.com/randomphp/scoped)[ Packagist](https://packagist.org/packages/randomphp/scoped)[ RSS](/packages/randomphp-scoped/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

[![RandomPHP](./assets/randomphp_text.png)](./assets/randomphp_text.png)

RandomPHP Scoped
================

[](#randomphp-scoped)

Directory-driven **Dependency Injection scopes** for PHP, built on top of PHP-DI.

RandomPHP Scoped adds hierarchical, lifecycle-aware scopes on top of PHP-DI using a filesystem-driven configuration model. Each directory represents a scope. Each subdirectory represents a nested sub-scope. Definition files inside each directory are standard PHP-DI definition files.

This allows you to model application lifecycles such as:

- Long-lived root application container
- Per-request scopes
- Per-job / per-message scopes
- Nested contextual scopes (e.g.request.user, request.transaction)
- CLI execution scopes
- Worker attempt scopes

---

Requirements
------------

[](#requirements)

- PHP >= 8.4

---

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

[](#installation)

Install via Composer:

```
composer require randomphp/scoped
```

---

Core Concepts
-------------

[](#core-concepts)

RandomPHP Scoped introduces the concept of *runtime invocation scopes*layered on top of PHP-DI.

Each scope:

- Has its own container
- Can override parent definitions
- Can access parent definitions when not overridden
- Can register teardown finalizers
- Is destroyed automatically when invocation completes

Scopes are created and destroyed dynamically via `invokeScope()`.

The root scope is long-lived. Sub-scopes are typically short-lived.

---

Directory Structure and Scope Hierarchy
---------------------------------------

[](#directory-structure-and-scope-hierarchy)

The library builds the scope hierarchy from a directory structure.

Example:

```
di/
  00-root.php
  10-services.php
  request/
    00-request.php
    user/
      00-user.php
  cli/
    00-cli.php

```

Meaning:

- `di/` → root scope
- `di/request/` → sub-scope named `request`
- `di/request/user/` → nested sub-scope `user` under `request`
- `di/cli/` → sub-scope named `cli`

Rules:

- All `*.php` files in a directory are loaded as definition files.
- Files are sorted alphabetically.
- Each subdirectory name becomes the scope name.
- Scope nesting mirrors directory nesting.

---

PHP-DI definition files
-----------------------

[](#php-di-definition-files)

A definition file is a PHP file that returns an array of definitions:

```