+ You're browsing the documentation for an old version of Bag. Consider upgrading to + the latest version. +
+composer require dshafik/bag"
+ image: /assets/images/bag.png
+ actions:
+ - theme: brand
+ text: Get Started
+ link: ./install
+
+features:
+ - title: Immutable & Strongly typed
+ icon: π¦Ύ
+ details: Bag value objects are immutable and strongly typed, a safer and more predictable way to work with data.
+ - title: Composable
+ icon: π
+ details: Nest Bag value objects and collections to create complex data structures.
+ - title: Built on Laravel
+ icon: π¦
+ details: Built-in validation, controller dependency injection, and more. Bag is designed to work seamlessly with Laravel.
+---
+
+## What is Bag?
+
+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 should I use Value Objects?
+
+Value objects should be used in place of regular arrays, allowing you enforce type safety and immutability.
+
+### Does it work with Laravel/Symfony/Other Framework?
+
+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.
+
diff --git a/docs/versions/1.x/install.md b/docs/versions/1.x/install.md
new file mode 100644
index 0000000..0398583
--- /dev/null
+++ b/docs/versions/1.x/install.md
@@ -0,0 +1,15 @@
+# Get Started with Bag Value Objects
+
+Bag is a library for creating immutable value objects in PHP. It's a great way to encapsulate data within your application.
+
+## Requirements
+
+Bag requires PHP 8.2+, and supports Laravel 10+.
+
+## Installation
+
+To install Bag, use [Composer](https://getcomposer.org):
+
+```bash
+composer require dshafik/bag
+```
diff --git a/docs/versions/1.x/laravel-artisan-make-bag-command.md b/docs/versions/1.x/laravel-artisan-make-bag-command.md
new file mode 100644
index 0000000..be821a3
--- /dev/null
+++ b/docs/versions/1.x/laravel-artisan-make-bag-command.md
@@ -0,0 +1,289 @@
+# Generate Bag Value Objects, Collections, and Factories
+
+Bag includes the `make:bag` artisan command to make it easy to generate new Bag classes, Factories, and Collections.
+
+> [!NOTE] Namespaces
+> The `make:bag` command will use the provided namespace to determine the location of the generated classes.
+> You can set the namespace using the `--namespace` option or you will be prompted for it. The default namespace is `\App\Values`.
+
+## Generating Bags
+
+To create a new Bag class, use the `make:bag` command:
+
+```bash
+php artisan make:bag MyBag
+```
+
+This will create a new `MyBag` class in `app/Values/MyBag.php`:
+
+```php
+ [!NOTE]
+> When creating a new Bag _or_ when specifying the `--update` flag, it will automatically add the `Collection` attribute to the Bag class if necessary.
+
+## Generating Bag Factories
+
+The `make:bag` command can also generate Bag Factory classes, **and** will _automatically_ generate the `definition()` function based on the Bag class properties.
+
+To create a new Bag Factory class, use the `make:bag` command with the `--factory` option:
+
+```bash
+php artisan make:bag MyBag --factory
+```
+
+This will create a new `MyBagFactory` class in `app/Values/Factories/MyBagFactory.php`:
+
+```php
+ [!TIP]
+> When creating a new Bag _or_ when specifying the `--update` flag, it will automatically add the `Factory` attribute and `HasFactory` trait to the Bag class.
+
+## Updating Factories
+
+Once you had added properties to your Bag class, you can update the Factory class using the `--update` option:
+
+```bash
+php artisan make:bag MyBag --factory --docs --update
+```
+
+> [!TIP]
+> If you update the Bag class properties, you can re-run the `make:bag` command with the `--update` and `--force-excluding-bag` options to update the Factory class.
+
+For example, if we update our `MyBag` constructor to look like the following:
+
+```php
+public function __construct(
+ public string $name,
+ public int $age,
+ #[Cast(DateTime::class, 'y-m-d')]
+ public CarbonImmutable $birthday,
+ public Money $money,
+ public AnotherBag $test,
+ #[Cast(CollectionOf::class, AnotherBag::class)]
+ public Collection $collection,
+) {
+}
+```
+
+The generated factory will look like this:
+
+```php
+ $this->faker->word(),
+ 'age' => $this->faker->randomNumber(),
+ 'birthday' => new CarbonImmutable(),
+ 'money' => Money::ofMinor($this->faker->numberBetween(100, 10000), 'USD'),
+ 'test' => AnotherBag::factory()->make(),
+ 'collection' => AnotherBag::collect([AnotherBag::factory()->make()]),
+ ];
+ }
+}
+```
+
+## Documentation/Auto-Complete Helpers
+
+To enable easier use of named/positional arguments when creating a new Bag, you can use the `--docs` option to automatically generate it for the Bag,
+this will add an `@method` annotation to the Bag class to provide auto-complete for the `::from()` method:
+
+```bash
+php artisan make:bag MyBag --docs
+```
+
+This will add the following to the `MyBag` class:
+
+```php
+/**
+ * @method static static from(array $data)
+ */
+```
+
+## Updating Documentation
+
+Similar to Factories, you can update the documentation using the `--update` option:
+
+```bash
+php artisan make:bag MyBag --docs --update
+```
+
+This will update the `@method` annotation to include documentation for all defined Value attributes. For example, given the following bag:
+
+```php
+use App\Values\Collections\ReportCollection;
+use App\Values\Report;
+use App\Values\Team;
+use Carbon\CarbonImmutable;
+
+readonly class User extends Bag {
+ public function __construct(
+ public string $name,
+ public int $age,
+ public Team $team,
+ #[Cast(CollectionOf::class, Report::class)]
+ public ReportCollection $reports,
+ public CarbonImmutable $lastLogin,
+ ) {
+ }
+}
+```
+
+The `@method` annotation will added to the `User` class:
+
+```php
+use App\Values\Collections\ReportCollection;
+use App\Values\Report;
+use App\Values\Team;
+use Carbon\CarbonImmutable;
+
+/**
+ * @method static static from(string $name, int $age, Team $team, ReportCollectioncomposer require dshafik/bag"
+ image: /assets/images/bag.png
+ actions:
+ - theme: brand
+ text: Get Started
+ link: ./install
+
+features:
+ - title: Immutable & Strongly typed
+ icon: π¦Ύ
+ details: Bag value objects are immutable and strongly typed, a safer and more predictable way to work with data.
+ - title: Composable
+ icon: π
+ details: Nest Bag value objects and collections to create complex data structures.
+ - title: Built on Laravel
+ icon: π¦
+ details: Built-in validation, controller dependency injection, and more. Bag is designed to work seamlessly with Laravel.
+---
+
+## What is Bag?
+
+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 should I use Value Objects?
+
+Value objects should be used in place of regular arrays, allowing you enforce type safety and immutability.
+
+### Does it work with Laravel/Symfony/Other Framework?
+
+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.
+
diff --git a/docs/versions/2.0/install.md b/docs/versions/2.0/install.md
new file mode 100644
index 0000000..0398583
--- /dev/null
+++ b/docs/versions/2.0/install.md
@@ -0,0 +1,15 @@
+# Get Started with Bag Value Objects
+
+Bag is a library for creating immutable value objects in PHP. It's a great way to encapsulate data within your application.
+
+## Requirements
+
+Bag requires PHP 8.2+, and supports Laravel 10+.
+
+## Installation
+
+To install Bag, use [Composer](https://getcomposer.org):
+
+```bash
+composer require dshafik/bag
+```
diff --git a/docs/versions/2.0/laravel-artisan-make-bag-command.md b/docs/versions/2.0/laravel-artisan-make-bag-command.md
new file mode 100644
index 0000000..be821a3
--- /dev/null
+++ b/docs/versions/2.0/laravel-artisan-make-bag-command.md
@@ -0,0 +1,289 @@
+# Generate Bag Value Objects, Collections, and Factories
+
+Bag includes the `make:bag` artisan command to make it easy to generate new Bag classes, Factories, and Collections.
+
+> [!NOTE] Namespaces
+> The `make:bag` command will use the provided namespace to determine the location of the generated classes.
+> You can set the namespace using the `--namespace` option or you will be prompted for it. The default namespace is `\App\Values`.
+
+## Generating Bags
+
+To create a new Bag class, use the `make:bag` command:
+
+```bash
+php artisan make:bag MyBag
+```
+
+This will create a new `MyBag` class in `app/Values/MyBag.php`:
+
+```php
+ [!NOTE]
+> When creating a new Bag _or_ when specifying the `--update` flag, it will automatically add the `Collection` attribute to the Bag class if necessary.
+
+## Generating Bag Factories
+
+The `make:bag` command can also generate Bag Factory classes, **and** will _automatically_ generate the `definition()` function based on the Bag class properties.
+
+To create a new Bag Factory class, use the `make:bag` command with the `--factory` option:
+
+```bash
+php artisan make:bag MyBag --factory
+```
+
+This will create a new `MyBagFactory` class in `app/Values/Factories/MyBagFactory.php`:
+
+```php
+ [!TIP]
+> When creating a new Bag _or_ when specifying the `--update` flag, it will automatically add the `Factory` attribute and `HasFactory` trait to the Bag class.
+
+## Updating Factories
+
+Once you had added properties to your Bag class, you can update the Factory class using the `--update` option:
+
+```bash
+php artisan make:bag MyBag --factory --docs --update
+```
+
+> [!TIP]
+> If you update the Bag class properties, you can re-run the `make:bag` command with the `--update` and `--force-excluding-bag` options to update the Factory class.
+
+For example, if we update our `MyBag` constructor to look like the following:
+
+```php
+public function __construct(
+ public string $name,
+ public int $age,
+ #[Cast(DateTime::class, 'y-m-d')]
+ public CarbonImmutable $birthday,
+ public Money $money,
+ public AnotherBag $test,
+ #[Cast(CollectionOf::class, AnotherBag::class)]
+ public Collection $collection,
+) {
+}
+```
+
+The generated factory will look like this:
+
+```php
+ $this->faker->word(),
+ 'age' => $this->faker->randomNumber(),
+ 'birthday' => new CarbonImmutable(),
+ 'money' => Money::ofMinor($this->faker->numberBetween(100, 10000), 'USD'),
+ 'test' => AnotherBag::factory()->make(),
+ 'collection' => AnotherBag::collect([AnotherBag::factory()->make()]),
+ ];
+ }
+}
+```
+
+## Documentation/Auto-Complete Helpers
+
+To enable easier use of named/positional arguments when creating a new Bag, you can use the `--docs` option to automatically generate it for the Bag,
+this will add an `@method` annotation to the Bag class to provide auto-complete for the `::from()` method:
+
+```bash
+php artisan make:bag MyBag --docs
+```
+
+This will add the following to the `MyBag` class:
+
+```php
+/**
+ * @method static static from(array $data)
+ */
+```
+
+## Updating Documentation
+
+Similar to Factories, you can update the documentation using the `--update` option:
+
+```bash
+php artisan make:bag MyBag --docs --update
+```
+
+This will update the `@method` annotation to include documentation for all defined Value attributes. For example, given the following bag:
+
+```php
+use App\Values\Collections\ReportCollection;
+use App\Values\Report;
+use App\Values\Team;
+use Carbon\CarbonImmutable;
+
+readonly class User extends Bag {
+ public function __construct(
+ public string $name,
+ public int $age,
+ public Team $team,
+ #[Cast(CollectionOf::class, Report::class)]
+ public ReportCollection $reports,
+ public CarbonImmutable $lastLogin,
+ ) {
+ }
+}
+```
+
+The `@method` annotation will added to the `User` class:
+
+```php
+use App\Values\Collections\ReportCollection;
+use App\Values\Report;
+use App\Values\Team;
+use Carbon\CarbonImmutable;
+
+/**
+ * @method static static from(string $name, int $age, Team $team, ReportCollection