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;
+}

tests/Definitions/Integrations/Laravel/Models/FirstModel.php

@@ -0,0 +1,22 @@
+<?php declare(strict_types=1);
+
+namespace Square\Pjson\Tests\Definitions\Integrations\Laravel\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Square\Pjson\Integrations\Laravel\JsonCaster;
+use Square\Pjson\Tests\Definitions\Integrations\Laravel\Address;
+use Square\Pjson\Tests\Definitions\Integrations\Laravel\CastableAddress;
+
+class FirstModel extends Model
+{
+    protected $table = 'first_model';
+    protected $guarded = [];
+    public $timestamps = false;
+
+    protected $casts = [
+        // Using laravel's castable interface
+        'castable_address' => CastableAddress::class,
+        // Using cast attributes
+        'address' => JsonCaster::class.':'.Address::class,
+    ];
+}

tests/Integrations/Laravel/LaravelCastTest.php

@@ -0,0 +1,85 @@
+<?php declare(strict_types=1);
+namespace Square\Pjson\Tests\Integrations\Laravel;
+
+use Illuminate\Support\Facades\Schema;
+use Orchestra\Testbench\TestCase;
+use Square\Pjson\Tests\Definitions\Integrations\Laravel\Address;
+use Square\Pjson\Tests\Definitions\Integrations\Laravel\CastableAddress;
+use Square\Pjson\Tests\Definitions\Integrations\Laravel\Models\FirstModel;
+
+class LaravelCastTest extends TestCase
+{
+    public function setUp(): void
+    {
+        parent::setUp();
+        Schema::create('first_model', function ($table) {
+            $table->increments('id')->unsigned();
+            $table->string('name')->nullable();
+            $table->text('castable_address')->nullable();
+            $table->text('address')->nullable();
+        });
+    }
+
+    public function testCasts()
+    {
+        $addr = '{"line1":"678 Lombard St.","line2":"","city":"San Fransokyo","zipcode":"94959","country":"USA"}';
+        (new FirstModel([
+            'name' => 'jane',
+            'castable_address' => CastableAddress::fromJsonString($addr),
+            'address' => Address::fromJsonString($addr),
+        ]))->save();
+        $m = FirstModel::query()->first();
+        $dbAddr = $m->getAttributes()['castable_address'];
+        $this->assertEquals($addr, $dbAddr);
+        $dbAddr = $m->getAttributes()['address'];
+        $this->assertEquals($addr, $dbAddr);
+
+        // Reading the attribute directly should give objects of the right class
+        $caddr = $m->castable_address;
+        $this->assertEquals(CastableAddress::class, get_class($caddr));
+        $this->assertEquals($addr, $caddr->toJson());
+        $oaddr = $m->address;
+        $this->assertEquals(Address::class, get_class($oaddr));
+        $this->assertEquals($addr, $oaddr->toJson());
+    }
+
+    public function testNullCase()
+    {
+        (new FirstModel([
+            'name' => 'jane',
+            'castable_address' => null,
+            'address' => null,
+        ]))->save();
+        $m = FirstModel::query()->first();
+        $this->assertTrue(null === $m->getAttributes()['castable_address']);
+        $this->assertTrue(null === $m->castable_address);
+        $this->assertTrue(null === $m->getAttributes()['address']);
+        $this->assertTrue(null === $m->address);
+    }
+
+    public function testNotSet()
+    {
+        (new FirstModel([
+            'name' => 'jane',
+        ]))->save();
+        $m = FirstModel::query()->first();
+        $this->assertTrue(null === $m->getAttributes()['castable_address']);
+        $this->assertTrue(null === $m->castable_address);
+        $this->assertTrue(null === $m->getAttributes()['address']);
+        $this->assertTrue(null === $m->address);
+    }
+
+    public function testEmptyString()
+    {
+        FirstModel::query()->insert([
+            'name' => 'jane',
+            'castable_address' => '',
+            'address' => '',
+        ]);
+        $m = FirstModel::query()->first();
+        $this->assertTrue('' === $m->getAttributes()['castable_address']);
+        $this->assertTrue('' === $m->castable_address);
+        $this->assertTrue('' === $m->getAttributes()['address']);
+        $this->assertTrue('' === $m->address);
+    }
+}