Merge branch 'value_objects' into 'master'

Value objects base class for consistant re-usability

See merge request composer/Laravel-Helpers!17

Author: craigAtCD

.DS_Store

@@ -3,7 +3,7 @@ include:
     file: "php-packages.latest.yml"
 
 variables:
+  TEST_PHP_8_3: "true"
   TEST_PHP_8_2: "true"
   TEST_PHP_8_1: "true"
-  TEST_PHP_8_0: "true"
-
+  TEST_PHP_8_0: "false"

.gitlab-ci.yml

@@ -5,13 +5,15 @@ config:
   php: "8.2"
 
 services:
+
+  # php83:
+  #   type: php:8.3
+  #   via: "cli"
+
   php81:
     type: php:8.1
     via: "cli"
 
-  php80:
-    type: php:8.0
-    via: "cli"
 
 tooling:
   cleanup:
@@ -21,60 +23,73 @@ tooling:
     service: php81
     cmd: rm -rf vendor composer.lock && composer install
 
-  setup80:
-    service: php80
+  setup82:
+    service: php82
     cmd: rm -rf vendor composer.lock && composer install
 
-  setup82:
+  setup83:
     service: appserver
     cmd: rm -rf vendor composer.lock && composer install
 
-  test82:
-    service: appserver
-    cmd: composer phpunit
+
   test81:
     service: php81
     cmd: composer phpunit
-  test80:
-    service: php80
+  test82:
+    service: php82
+    cmd: composer phpunit
+  test83:
+    service: appserver
     cmd: composer phpunit
 
-  stan82:
+  stan83:
     service: appserver
     cmd: composer phpstan
+  stan82:
+    service: php82
+    cmd: composer phpstan
   stan81:
     service: php81
     cmd: composer phpstan
-  stan80:
-    service: php80
-    cmd: composer phpstan
 
-  all82:
+  all83:
     service: appserver
     cmd:
       - rm -rf vendor composer.lock && composer install
       - composer phpunit
       - composer phpstan
 
+  all82:
+    service: php82
+    cmd:
+      - rm -rf vendor composer.lock && composer install
+      - composer phpunit
+      - composer phpstan
+
   all81:
     service: php81
     cmd:
       - rm -rf vendor composer.lock && composer install
       - composer phpunit
       - composer phpstan
 
-  all80:
-    service: php80
+
+  lara11:
+    service: php83
     cmd:
-      - rm -rf vendor composer.lock && composer install
+      - rm -rf vendor composer.lock
+      - composer require laravel/laravel:^11
+      - composer install
       - composer phpunit
       - composer phpstan
+      # this is for removing a specific version
+      - composer remove laravel/laravel
 
-  lara8:
-    service: php81
+  lara10:
+    service: php82
     cmd:
       - rm -rf vendor composer.lock
-      - composer require laravel/laravel:^8
+      - composer require laravel/laravel:^10
       - composer install
       - composer phpunit
       - composer phpstan

.lando.yml

@@ -17,11 +17,15 @@ Collection of helpers for re-use accross a few of our projects
   - [Helpers](#helpers)
   - [DB Macros](#db-macros)
     - [Null Or Empty](#null-or-empty)
+    - [Case insensitive statments](#case-insensitive-statments)
     - [Enforced Non Nullable Relations (orFail chain)](#enforced-non-nullable-relations-orfail-chain)
   - [DB Repositories](#db-repositories)
   - [String Macros](#string-macros)
+  - [Observerable trait](#observerable-trait)
   - [Date Manipulation](#date-manipulation)
     - [Date(Carbon) Helpers attached to above:](#datecarbon-helpers-attached-to-above)
+    - [Value Objects](#value-objects)
+    - [Larastan Stubs](#larastan-stubs)
   - [Credits](#credits)
 
 ## Installation
@@ -124,10 +128,10 @@ example in the [UserRepository.stub.php](https://git.customd.com/composer/Larave
 ## Observerable trait
 adding this trait to your models will automatically look for an observer in the app/Observers folder with the convension {model}Observer as the classname,
 
-you can additionally/optionally add 
+you can additionally/optionally add
 ```php
 protected static $observers = [ ...arrayOfObservers]
-``` 
+```
 to add a additional ones if needed
 
 ## Date Manipulation
@@ -177,6 +181,40 @@ methods available:
 
 You can also use the CDCarbonDate to create a few differnt date objects.
 
+### Value Objects
+Example:
+```php
+<?php
+declare(strict_types=1);
+
+namespace CustomD\LaravelHelpers\Tests\ValueObjects;
+
+use CustomD\LaravelHelpers\ValueObjects\ValueObject;
+
+class SimpleValue extends ValueObject
+{
+    protected function __construct(
+        readonly public string $value,
+        readonly public int $count = 0
+    ) {
+    }
+
+  /** optionally add some validation rules, leave out the method if the type sets are enough **/
+    public function rules(): array
+    {
+        return [
+          'value' => ['string', 'max:250'],
+          'count' => ['max:99'],
+        ];
+    }
+}
+
+$simpleValue = SimpleValue::make(value: 'hello World', count: 33);
+
+```
+
+Best practice is to use the make option, which will validate, if you use a public constructor it will not.
+
 ### Larastan Stubs
 **these are temporary only till implemented by larastan**
 
@@ -191,4 +229,3 @@ parameters:
 
 - [](https://github.com/custom-d/laravel-helpers)
 - [All contributors](https://github.com/custom-d/laravel-helpers/graphs/contributors)
-

README.md

@@ -18,12 +18,12 @@
     }
   ],
   "require": {
-    "php": "^8.0",
-    "illuminate/notifications": "^8.5|^9.0|^10.0",
-    "illuminate/support": "^8.5|^9.0|^10"
+    "php": "^8.1",
+    "illuminate/notifications": "^9.0|^10.0|^11.0",
+    "illuminate/support": "^9.0|^10|^11.0"
   },
   "require-dev": {
-    "orchestra/testbench": "^6.0|^7.0|^8.0",
+    "orchestra/testbench": "^7.0|^8.0|^9.0",
     "nunomaduro/larastan": "^1.0|^2.0",
     "phpunit/phpunit": "^9.0|^10.0"
   },

composer.json

@@ -0,0 +1,86 @@
+<?php
+namespace CustomD\LaravelHelpers\ValueObjects;
+
+use Illuminate\Contracts\Container\BindingResolutionException;
+use Illuminate\Contracts\Support\Arrayable;
+use ReflectionClass;
+use Illuminate\Support\Collection;
+use Illuminate\Foundation\Http\FormRequest;
+use ReflectionParameter;
+
+/**
+ * @implements Arrayable<string,mixed>
+ */
+abstract class ValueObject implements Arrayable
+{
+    /**
+     *
+     * @param mixed $args
+     * @return static
+     * @throws BindingResolutionException
+     */
+    public static function make(...$args): static
+    {
+        $instance =  new static(...$args); //@phpstan-ignore-line -- meant to be static
+        $instance->validate();
+        return $instance;
+    }
+
+    /**
+     *
+     * @param mixed $args
+     * @return ?static
+     * @throws BindingResolutionException
+     */
+    public static function makeOrNull(...$args): ?static
+    {
+        try {
+            return static::make(...$args);
+        } catch (\Throwable $th) {
+            return null;
+        }
+    }
+
+
+    public static function fromRequest(FormRequest $request, bool $onlyValidated = true): static
+    {
+        /** @var array<string, mixed> */
+        $data = $onlyValidated ? $request->validated() : $request->all();
+
+        $args = collect($data)->only(static::getConstructorArgs())->toArray();
+
+        return new static(...$args); //@phpstan-ignore-line -- meant to be static
+    }
+
+    /**
+     *
+     * @return Collection<int, string>
+     */
+    protected static function getConstructorArgs(): Collection
+    {
+        return collect((new ReflectionClass(static::class))->getConstructor()?->getParameters() ?? [])
+            ->map(fn(ReflectionParameter $parameter) => $parameter->getName());
+    }
+
+    /**
+     *
+     * @return array<string, mixed>
+     */
+    public function rules(): array
+    {
+        return [];
+    }
+
+    protected function validate(): void
+    {
+        $validator = app('validator')->make($this->toArray(), $this->rules());
+        $validator->validate();
+    }
+
+    public function toArray(): array
+    {
+        return static::getConstructorArgs()
+            ->mapWithKeys(fn($property) => [$property => $this->{$property}])
+            ->toArray();
+    }
+}

src/ValueObjects/ValueObject.php

@@ -0,0 +1,88 @@
+<?php
+namespace CustomD\LaravelHelpers\Tests;
+
+use Orchestra\Testbench\TestCase;
+use CustomD\LaravelHelpers\Tests\ValueObjects\SimpleValue;
+use CustomD\LaravelHelpers\Tests\ValueObjects\ComplexValue;
+use CustomD\LaravelHelpers\Tests\ValueObjects\SimpleValueFormRequest;
+
+class ValueObjectTest extends TestCase
+{
+
+    public function test_it_can_create_a_value_object()
+    {
+        $value = SimpleValue::make('test', 10);
+        $this->assertInstanceOf(SimpleValue::class, $value);
+
+        $this->assertEquals('test', $value->value);
+        $this->assertEquals(10, $value->count);
+        $this->assertIsInt($value->count);
+    }
+
+    public function test_it_can_create_a_value_object_from_request()
+    {
+        $request = new SimpleValueFormRequest(query: ['value' => 'test','count' => '11','age' => 33]);
+
+        $validator = app('validator')->make(['value' => 'test','count' => '11', 'age' => 33], $request->rules());
+
+        $request->setValidator($validator);
+        $request->validateResolved();
+
+        $value = SimpleValue::fromRequest($request, false);
+        $this->assertInstanceOf(SimpleValue::class, $value);
+
+        $this->assertEquals('test', $value->value);
+    }
+
+    public function test_it_validates_when_constructed()
+    {
+        $this->expectException(\Illuminate\Validation\ValidationException::class);
+        $data = ['value' => 'test', 'count' => 9];
+        $value = SimpleValue::make(...$data);
+    }
+
+    public function test_it_can_be_passed_an_array()
+    {
+        $data = ['value' => 'test', 'count' => 11];
+        $value = SimpleValue::make(...$data);
+        $this->assertEquals('test', $value->value);
+        $this->assertEquals(11, $value->count);
+        $this->assertIsInt($value->count);
+    }
+
+    public function test_a_complex_value()
+    {
+        $data = [
+            'value'       => 'test',
+            'address'     => [
+                'street' => '123 Fake St'
+            ],
+            'simpleValue' => SimpleValue::make(
+                'test',
+                11
+            )
+        ];
+        $value = ComplexValue::make(...$data);
+        $this->assertEquals('test', $value->value);
+        $this->assertEquals(11, $value->simpleValue->count);
+        $this->assertEquals('123 Fake St', $value->address['street']);
+    }
+
+    public function test_a_complex_value_construct()
+    {
+        $data = [
+            'value'       => 'test',
+            'simpleValue' => SimpleValue::make(...[
+                'count' => 11,
+                'value' => 'test',
+            ]),
+            'address'     => [
+                'street' => '123 Fake St'
+            ],
+        ];
+        $value = ComplexValue::make(...$data);
+        $this->assertEquals('test', $value->value);
+        $this->assertEquals(11, $value->simpleValue->count);
+        $this->assertEquals('123 Fake St', $value->address['street']);
+    }
+}