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.2(7mo ago)1789.1k↓10.2%14[12 PRs](https://github.com/beacon-hq/bag/pulls)3MITPHPPHP ^8.2|^8.3|^8.4CI 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 1mo ago

READMEChangelog (10)Dependencies (21)Versions (39)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

56

—

FairBetter than 98% of packages

Maintenance75

Regular maintenance activity

Popularity44

Moderate usage in the ecosystem

Community23

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 91.8% 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 ~20 days

Total

26

Last Release

222d ago

Major Versions

1.4.0 → 2.0.02025-01-04

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

1.2.0PHP ^8.2|^8.3|^8.4

### 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 (168 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)")[![nicekiwi](https://avatars.githubusercontent.com/u/738975?v=4)](https://github.com/nicekiwi "nicekiwi (1 commits)")[![raphaelstolt](https://avatars.githubusercontent.com/u/48225?v=4)](https://github.com/raphaelstolt "raphaelstolt (1 commits)")[![theofidry](https://avatars.githubusercontent.com/u/5175937?v=4)](https://github.com/theofidry "theofidry (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

[aedart/athenaeum

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

245.2k](/packages/aedart-athenaeum)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[illuminate/queue

The Illuminate Queue package.

20331.4M1.2k](/packages/illuminate-queue)[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[tehwave/laravel-achievements

Simple, elegant Achievements the Laravel way

7012.8k](/packages/tehwave-laravel-achievements)[wearepixel/laravel-cart

A cart implementation for Laravel

1310.5k](/packages/wearepixel-laravel-cart)

PHPackages © 2026

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