PHPackages                             beacon-hq/bag - 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. beacon-hq/bag

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

beacon-hq/bag
=============

A comprehensive immutable value objects implementation

2.6.3(2mo ago)18314.4k↓65.1%15[4 issues](https://github.com/beacon-hq/bag/issues)[11 PRs](https://github.com/beacon-hq/bag/pulls)3MITPHPPHP ^8.2|^8.3|^8.4|^8.5CI passing

Since May 12Pushed 2mo ago3 watchersCompare

[ Source](https://github.com/beacon-hq/bag)[ Packagist](https://packagist.org/packages/beacon-hq/bag)[ RSS](/packages/beacon-hq-bag/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (42)Versions (41)Used By (3)

 [![Bag](https://camo.githubusercontent.com/f075966e44af2b0adfc4a2dc78b29015a23f2dc6f2e09180f35e625664310814/68747470733a2f2f6473686166696b2e6769746875622e696f2f6261672f6173736574732f696d616765732f736f6369616c2e706e67)](https://camo.githubusercontent.com/f075966e44af2b0adfc4a2dc78b29015a23f2dc6f2e09180f35e625664310814/68747470733a2f2f6473686166696b2e6769746875622e696f2f6261672f6173736574732f696d616765732f736f6369616c2e706e67)

 [ ![Coverage](https://camo.githubusercontent.com/952f20821455043629dc588647de0cf95d0ddaf1187e9c6ce66b5156e44d1f64/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d626167266d65747269633d636f766572616765) ](https://sonarcloud.io/summary/new_code?id=bag) [ ![Quality Gate Status](https://camo.githubusercontent.com/e1e751d4368bba2c7307217161f2f757bb85bccb9a23e02c70eef79dfd7c0d90/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d626167266d65747269633d616c6572745f737461747573) ](https://sonarcloud.io/summary/new_code?id=bag)

Bag
===

[](#bag)

Immutable Value Objects for PHP 8.3+ inspired by [spatie/laravel-data](https://spatie.be/docs/laravel-data/v4/introduction), created by [Davey Shafik](https://www.daveyshafik.com).

Introduction
------------

[](#introduction)

Bag helps you create immutable value objects. It's a great way to encapsulate data within your application.

Bag prioritizes immutability and type safety with built-in validation and data casting.

### When to use Value Objects

[](#when-to-use-value-objects)

Value objects should be used in place of regular arrays, allowing you enforce type safety and immutability.

### Features

[](#features)

- Immutable & Strongly typed
- Value casting — both input and output
- Collection support
- Composable — nest Bag value objects and collections
- Built-in validation

Note

Bag is framework-agnostic, but it works great with Laravel. Bag uses standard Laravel [Collections](https://laravel.com/docs/11.x/collections) and [Validation](https://laravel.com/docs/11.x/validation). In addition, it will automatically inject `Bag\Bag` value objects into your controllers with validation.

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

[](#requirements)

Bag requires PHP 8.3+, and supports Laravel 11.x.

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

[](#installation)

You can install the package via composer:

```
composer require beacon-hq/bag
```

Usage
-----

[](#usage)

### Creating a Value Object

[](#creating-a-value-object)

To create a basic Value Object, extend the `Bag\Bag` class and define your properties in the constructor:

```
use Bag\Bag;

readonly class MyValue extends Bag {
    public function __construct(
        public string $name,
        public int $age,
    ) {
    }
}
```

### Instantiating a Value Object

[](#instantiating-a-value-object)

To create a new instance of your Value Object, call the `::from()` method:

```
$value = MyValue::from([
    'name' => 'Davey Shafik',
    'age' => 40,
]);
```

Documentation
-------------

[](#documentation)

Full documentation can be found [here](https://dshafik.github.io/bag).

###  Health Score

60

—

FairBetter than 98% of packages

Maintenance85

Actively maintained with recent releases

Popularity45

Moderate usage in the ecosystem

Community25

Small or concentrated contributor base

Maturity71

Established project with proven stability

 Bus Factor1

Top contributor holds 90.9% 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 ~27 days

Recently: every ~73 days

Total

27

Last Release

73d ago

Major Versions

1.4.0 → 2.0.02025-01-04

PHP version history (3 changes)1.0.0PHP ^8.2|^8.3

1.2.0PHP ^8.2|^8.3|^8.4

2.6.3PHP ^8.2|^8.3|^8.4|^8.5

### Community

Maintainers

![](https://www.gravatar.com/avatar/950c044ac0c43c20172483e6cd7c13afed5976380e86dad6308cc4a667329b27?d=identicon)[dshafik](/maintainers/dshafik)

---

Top Contributors

[![dshafik](https://avatars.githubusercontent.com/u/58074?v=4)](https://github.com/dshafik "dshafik (169 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (10 commits)")[![elazar](https://avatars.githubusercontent.com/u/15487?v=4)](https://github.com/elazar "elazar (2 commits)")[![raphaelstolt](https://avatars.githubusercontent.com/u/48225?v=4)](https://github.com/raphaelstolt "raphaelstolt (1 commits)")[![chuckadams](https://avatars.githubusercontent.com/u/3925?v=4)](https://github.com/chuckadams "chuckadams (1 commits)")[![theofidry](https://avatars.githubusercontent.com/u/5175937?v=4)](https://github.com/theofidry "theofidry (1 commits)")[![emmanix2002](https://avatars.githubusercontent.com/u/456165?v=4)](https://github.com/emmanix2002 "emmanix2002 (1 commits)")[![nicekiwi](https://avatars.githubusercontent.com/u/738975?v=4)](https://github.com/nicekiwi "nicekiwi (1 commits)")

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/beacon-hq-bag/health.svg)

```
[![Health](https://phpackages.com/badges/beacon-hq-bag/health.svg)](https://phpackages.com/packages/beacon-hq-bag)
```

###  Alternatives

[illuminate/queue

The Illuminate Queue package.

21332.6M1.6k](/packages/illuminate-queue)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9762.4M131](/packages/roots-acorn)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8793.2M25](/packages/yajra-laravel-oci8)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[illuminate/pagination

The Illuminate Pagination package.

12234.1M1.0k](/packages/illuminate-pagination)

PHPackages © 2026

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