Merge pull request #16 from square/laravel-casts

Proposal for integration with Laravel casts

Author: khepin

.github/workflows/php-8-0.yml

@@ -21,6 +21,7 @@ jobs:
       uses: shivammathur/setup-php@v2
       with:
         php-version: '8.0'
+        extensions: pdo, pdo_sqlite
 
     - name: Validate composer.json and composer.lock
       run: composer validate --strict

.github/workflows/php-8-1.yml

@@ -21,6 +21,7 @@ jobs:
       uses: shivammathur/setup-php@v2
       with:
         php-version: '8.1'
+        extensions: pdo, pdo_sqlite
 
     - name: Validate composer.json and composer.lock
       run: composer validate --strict

Makefile

@@ -1,9 +1,9 @@
 ci-php80:
-	./vendor/bin/phpcs --standard=PSR2  src/ tests/
 	./vendor/bin/phpunit --testsuite php80
+	./vendor/bin/phpcs --standard=PSR2  src/ tests/
 	vendor/bin/phpstan analyse src tests --level 5 -c phpstan.php80.neon
 
 ci-php81:
-	./vendor/bin/phpcs --standard=PSR2  src/ tests/
 	./vendor/bin/phpunit --testsuite php81
+	./vendor/bin/phpcs --standard=PSR2  src/ tests/
 	vendor/bin/phpstan analyse src tests --level 5 -c phpstan.neon

README.md

@@ -481,3 +481,76 @@ that this is expected behavior by adding this library's extension in your `phpst
 includes:
   - vendor/square/pjson/extension.neon
 ```
+
+## Laravel Integration
+
+### via castable
+
+If you wish to cast Eloquent model attributes to classes via Pjson, you might do so with the provided casting utilities:
+
+```php
+use Illuminate\Contracts\Database\Eloquent\Castable;
+use Square\Pjson\Json;
+use Square\Pjson\JsonSerialize;
+use Square\Pjson\Integrations\Laravel\JsonCastable;
+
+class Schedule implements Castable // implement the laravel interface
+{
+    use JsonSerialize;
+    use JsonCastable; // use the provided Pjson trait
+
+    #[Json]
+    protected int $start;
+
+    #[Json]
+    protected int $end;
+
+    public function __construct(int $start, int $end)
+    {
+        $this->start = $start;
+        $this->end = $end;
+    }
+}
+```
+
+Then in your Eloquent model:
+
+```php
+$casts = [
+    'schedule' => Schedule::class,
+];
+```
+
+### via cast arguments
+
+Alternatively, you can simply use Laravel's cast arguments. In this case the `Schedule` class stays the way it used to be:
+
+```php
+use Square\Pjson\Json;
+use Square\Pjson\JsonSerialize;
+
+class Schedule
+{
+    use JsonSerialize;
+
+    #[Json]
+    protected int $start;
+
+    #[Json]
+    protected int $end;
+
+    public function __construct(int $start, int $end)
+    {
+        $this->start = $start;
+        $this->end = $end;
+    }
+}
+```
+
+And you provide the class target of the cast like:
+
+```php
+$casts = [
+    'schedule' => JsonCaster::class.':'.Schedule::class,
+];
+```

composer.json

@@ -22,6 +22,7 @@
         "symfony/var-dumper": "^6.0",
         "phpunit/phpunit": "^9.5",
         "squizlabs/php_codesniffer": "^3.7",
-        "phpstan/phpstan": "^1.8"
+        "phpstan/phpstan": "^1.8",
+        "orchestra/testbench": "^7.11"
     }
 }

phpunit.xml

@@ -19,4 +19,7 @@
       <directory suffix="Test.php">tests</directory>
     </testsuite>
   </testsuites>
+  <php>
+    <env name="DB_CONNECTION" value="testing"/>
+  </php>
 </phpunit>

src/Integrations/Laravel/JsonCastable.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types=1);
+
+namespace Square\Pjson\Integrations\Laravel;
+
+trait JsonCastable
+{
+    public static function castUsing(array $arguments)
+    {
+        return new JsonCaster(static::class);
+    }
+}

src/Integrations/Laravel/JsonCaster.php

@@ -0,0 +1,27 @@
+<?php declare(strict_types=1);
+
+namespace Square\Pjson\Integrations\Laravel;
+
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+
+class JsonCaster implements CastsAttributes
+{
+    public function __construct(
+        protected string $target
+    ) {
+    }
+
+    public function get($model, $key, $value, $attributes)
+    {
+        if ($value === null || $value === '') {
+            return $value;
+        }
+
+        return $this->target::fromJsonString($value);
+    }
+
+    public function set($model, $key, $value, $attributes)
+    {
+        return $value?->toJson();
+    }
+}

tests/Definitions/Integrations/Laravel/Address.php

@@ -0,0 +1,22 @@
+<?php declare(strict_types=1);
+
+namespace Square\Pjson\Tests\Definitions\Integrations\Laravel;
+
+use Square\Pjson\Json;
+use Square\Pjson\JsonSerialize;
+
+class Address
+{
+    use JsonSerialize;
+
+    #[Json]
+    protected string $line1;
+    #[Json]
+    protected string $line2;
+    #[Json]
+    protected string $city;
+    #[Json]
+    protected string $zipcode;
+    #[Json]
+    protected string $country;
+}

tests/Definitions/Integrations/Laravel/CastableAddress.php

@@ -0,0 +1,11 @@
+<?php declare(strict_types=1);
+
+namespace Square\Pjson\Tests\Definitions\Integrations\Laravel;
+
+use Illuminate\Contracts\Database\Eloquent\Castable;
+use Square\Pjson\Integrations\Laravel\JsonCastable;
+
+class CastableAddress extends Address implements Castable
+{
+    use JsonCastable;
+}