Laravel 8: Database JSON fields (migration, casts, feature tests, update JSON attributes in DB)

add_column_options_to_something_table.php

<?php
declare(strict_types=1);

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class AddColumnOptionsToSomethingTable extends Migration
{
    /**
     * Run the migrations.
     *
     * @return void
     */
    public function up()
    {
        Schema::table('something', function (Blueprint $table) {
            $table->json('options');
        });
    }

    /**
     * Reverse the migrations.
     *
     * @return void
     */
    public function down()
    {
        Schema::table('something', function (Blueprint $table) {
            $table->dropColumn('options');
        });
    }
}

Something.php

<?php
declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Model;


class Something extends Model {
      // if JSON field contains object use 'object' type
      // if JSON field is array -> use 'array' type
      protected $casts = [
        'stats' => 'object'
    ];
    
    // IMPORTANT: default JSON attributes cannot be null or empty string
    protected $attributes = [
        'stats' => '{}'
    ];
}

usage_example.php

<?php
declare(strict_types=1);

use Tests\TestCase;
use App\Models\Something;

class TestMe extends TestCase {
  
    public function testMe() {
      $options = new \stdClass();
      $options->nested1 = new \stdClass();
      $options->nested1->myStr = "myStr";
      $options->nested2 = [1, 5, 10];

      $model = Something::find(1);

      $model->options = $options; // do not encode to JSON here if we already have a cast in model

      $model->save();

      $model->refresh();
      
      $this->assertEquals(10, $model->options->nested2[2]);
      
      $this->assertEquals("myStr", $model->options->nested1->myStr);
    }
   /**
     * WARNING! DO NOT MUTATE JSON PROPERTY LIKE YOU WOULD MUTATE MODEL ATTRIBUTE
     * 
     */
    public function testMutateJSONAttributes()
    {
        /** @var Listing $listing */
        $model = Something::find(1);
      
        $oneChange = new \stdClass;
        $oneChange->statusChange = "changed status 123";
      
        if (empty($model->stats) || !is_object($model->stats)) {
            $stats = new \stdClass;
            $stats->statusChanges = [
               $oneChange
            ];
          
            // TO UPDATE JSON FIELD ON MODEL USE forceFill
            // due to: https://github.com/laravel/framework/issues/15433
            $model->forceFill(['stats' => $stats]);
        } else {
            // WARNING: following mutation WON'T WORK
            // $model->stats->statusChanges[] = $oneChange
            // you have to mutate the JSON attributes by copy
            $changes = $model->stats->statusChanges;
            $changes[] = $oneChange;
            $model->forceFill(['stats->statusChanges' => $changes]);
        }

        $this->assertTrue($model->save());
        $model->refresh();
        
        dump($model->stats->statusChanges); // you should see the reflected changes in JSON
    }
  
}