Initial commit

Author: markusjwetzel

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-present Markus Wetzel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,129 @@
+# Laravel Struct
+
+[![Latest Stable Version](https://poser.pugx.org/proai/laravel-struct/v/stable)](https://packagist.org/packages/proai/laravel-struct) [![Total Downloads](https://poser.pugx.org/proai/laravel-struct/downloads)](https://packagist.org/packages/proai/laravel-struct) [![Latest Unstable Version](https://poser.pugx.org/proai/laravel-struct/v/unstable)](https://packagist.org/packages/proai/laravel-struct) [![License](https://poser.pugx.org/proai/laravel-struct/license)](https://packagist.org/packages/proai/laravel-struct)
+
+A struct is a collection of typed variables. Structs are a well known datatype in other programming languages, but unfortunately not natively part of PHP yet. This package aims to bring structs to PHP and in particular to Laravel.
+
+## Installation
+
+You can install the package via composer:
+
+```bash
+composer require proai/laravel-struct
+```
+
+Please note that you need at least **PHP 7.4** and **Laravel 8** for this package.
+
+## Usage
+
+The package uses named properties, which were introduced in PHP 7.4, to define a struct:
+
+```php
+use App\Structs\GeoLocation;
+use ProAI\Struct\Struct;
+
+class Address extends Struct
+{
+    public string $street;
+
+    public string $city;
+
+    public GeoLocation $geo_location;
+}
+```
+
+You can use all primitive types like `string`, `bool`, `float`, `int`, but also you can type a property as an object. The object can also be another struct, which enables you to nest structs (like `GeoLocation` above).
+
+Structs are instantiated by using an array of values:
+
+```php
+$address = new Address([
+    'street' => 'Baker Street',
+    'city' => 'London',
+    'geo_location' => [
+        'latitude' => 51.52,
+        'longitude' => -0.1566,
+    ],
+]);
+```
+
+Properties that are typed as objects will be converted to these objects on instantiation. Thus in the example above an object of `App\Structs\GeoLocation` will be created for the `$geo_location` property.
+
+Properties can be accessed normally:
+
+```php
+$address->street
+=> "Baker Street"
+
+$address->country
+=> App\Structs\GeoLocation { ... }
+```
+
+**Hint: Snake cased properties are used to mimic the behaviour of Eloquent attributes.**
+
+### Attribute Casting
+
+You can use attribute casting with structs in your Eloquent models:
+
+```php
+use App\Structs\Address;
+use Illuminate\Database\Eloquent\Model;
+
+class User extends Model
+{
+    protected $casts = [
+        'address' => Address::class,
+    ];
+}
+```
+
+In order to make this work you need to define a `json` column of the specified key, so in this case `address`.
+
+Alternatively you can use the composed struct caster by adding the argument `composed` to compose a struct from multiple columns:
+
+```php
+use App\Structs\Address;
+use Illuminate\Database\Eloquent\Model;
+
+class User extends Model
+{
+    protected $casts = [
+        'address' => Address::class.':composed',
+    ];
+}
+```
+
+The column names must start with the specified key followed by an underscore and the property name. This also works with nested structs. For the example above we would need the following columns:
+
+```
+address_street
+address_city
+address_geo_location_latitude
+address_geo_location_longitude
+```
+
+Finally you can also write your own custom caster by overwriting the `castUsing` method of the struct like described in the Laravel docs.
+
+### Collections
+
+Sometimes you need an array of structs. For this purpose you can define a struct collection. The struct collection class is inherited from the Laravel collection class, so you can use all methods of a Laravel collection.
+
+```php
+use App\Structs\Address;
+use ProAI\Struct\Collection;
+
+class AddressCollection extends Collection
+{
+    public $type = Address::class;
+}
+```
+
+By the way, attribute casting also works with struct collections for `json` columns.
+
+## Support
+
+Bugs and feature requests are tracked on [GitHub](https://github.com/proai/laravel-struct/issues).
+
+## License
+
+This package is released under the [MIT License](LICENSE).

composer.json

@@ -0,0 +1,29 @@
+{
+  "name": "proai/laravel-struct",
+  "description": "A Laravel package for using structs with Laravel including attribute casting.",
+  "keywords": [
+    "laravel",
+    "struct",
+    "eloquent",
+    "attribute casting",
+    "value object"
+  ],
+  "homepage": "http://github.com/proai/laravel-struct",
+  "license": "MIT",
+  "authors": [
+    {
+      "name": "Markus J. Wetzel",
+      "email": "[email protected]"
+    }
+  ],
+  "require": {
+    "php": ">=7.4",
+    "illuminate/database": "^8.0",
+    "illuminate/support": "^8.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "ProAI\\Struct\\": "src/"
+    }
+  }
+}

src/Casts/CollectionCast.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace ProAI\Struct\Casts;
+
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+use InvalidArgumentException;
+
+class CollectionCast implements CastsAttributes
+{
+    /**
+     * The struct collection class name.
+     *
+     * @var string
+     */
+    protected $class;
+
+    /**
+     * Create a new collection cast.
+     *
+     * @param  string  $class
+     * @return void
+     */
+    public function __construct($class)
+    {
+        $this->class = $class;
+    }
+
+    /**
+     * Transform the attribute from the underlying model values.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array  $attributes
+     * @return mixed
+     */
+    public function get($model, $key, $value, $attributes)
+    {
+        if (is_null($value)) {
+            return null;
+        }
+
+        $class = $this->class;
+        $typeClass = (new $class)->getTypeClass();
+
+        $items = array_map(function ($item) use ($typeClass) {
+            return new $typeClass($typeClass::parseDatabase($item));
+        }, json_decode($value, true));
+
+        return new $class($items);
+    }
+
+    /**
+     * Transform the attribute to its underlying model values.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array  $attributes
+     * @return mixed
+     */
+    public function set($model, $key, $value, $attributes)
+    {
+        $class = $this->class;
+
+        if (! $value instanceof $class) {
+            throw new InvalidArgumentException('The given value is not a struct collection instance, "'.get_class($value).'" given.');
+        }
+
+        $typeClass = $value->getTypeClass();
+
+        $value = array_map(function ($item) use ($typeClass) {
+            return $typeClass::serializeDatabase($item);
+        }, $value->all());
+        
+        return json_encode($value);
+    }
+}

src/Casts/ComposedStructCast.php

@@ -0,0 +1,105 @@
+<?php
+
+namespace ProAI\Struct\Casts;
+
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+use ProAI\Struct\Struct;
+use InvalidArgumentException;
+
+class ComposedStructCast implements CastsAttributes
+{
+    /**
+     * The struct class name.
+     *
+     * @var string
+     */
+    protected $class;
+
+    /**
+     * Create a new composed struct cast.
+     *
+     * @param  string  $class
+     * @return void
+     */
+    public function __construct($class)
+    {
+        $this->class = $class;
+    }
+
+    /**
+     * Transform the attribute from the underlying model values.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array  $attributes
+     * @return mixed
+     */
+    public function get($model, $key, $value, $attributes)
+    {
+        $properties = [];
+
+        foreach ($attributes as $name => $attribute) {
+            if (! Str::startsWith($name.'_')) {
+                continue;
+            }
+
+            $properties[Str::after($name.'_')] = $attribute;
+        }
+
+        $class = $this->class;
+
+        return new $class($class::parseDatabase($properties));
+    }
+
+    /**
+     * Transform the attribute to its underlying model values.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array  $attributes
+     * @return mixed
+     */
+    public function set($model, $key, $value, $attributes)
+    {
+        if (! $value instanceof Struct) {
+            throw new InvalidArgumentException('The given value is not a struct instance, "'.get_class($value).'" given.');
+        }
+
+        $class = $this->class;
+
+        $value = $class::serializeDatabase($value);
+
+        return $this->composeProperties($key, $value);
+    }
+
+    /**
+     * Compose properties of struct.
+     *
+     * @param  array  $columns
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array  $attributes
+     * @return mixed
+     */
+    public function composeProperties($prefix, $properties)
+    {
+        foreach ($properties as $name => $property) {
+            $key = $prefix.'_'.$name;
+
+            if (! is_array($property)) {
+                $columns[$key] = $property;
+
+                continue;
+            }
+
+            $columns = array_merge(
+                $this->composeProperties($key, $property),
+                $columns
+            );
+        }
+
+        return $columns;
+    }
+}