{"id":290,"date":"2025-08-27T19:18:35","date_gmt":"2025-08-27T19:18:35","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=290"},"modified":"2025-08-27T19:18:37","modified_gmt":"2025-08-27T19:18:37","slug":"using-json-columns-in-laravel-eloquent-practical-guide","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/using-json-columns-in-laravel-eloquent-practical-guide\/","title":{"rendered":"Using JSON Columns in Laravel Eloquent (Practical Guide)"},"content":{"rendered":"\n

Using JSON Columns in Laravel Eloquent (Practical Guide)<\/strong><\/h2>\n\n\n\n

JSON columns help you store flexible, semi-structured data without exploding your schema. In this practical guide, you\u2019ll create JSON columns, cast them in Eloquent, query nested paths efficiently, validate JSON payloads, update nested keys, and build a small UI to edit JSON-based user settings.<\/p>\n\n\n\n

<\/div>\n\n\n\n\n

1 – Creating JSON Columns<\/strong><\/h2>\n\n\n\n

Define JSON columns with the schema builder. On MySQL 5.7+\/8 and PostgreSQL, JSON is a native type; on SQLite it\u2019s stored as text but works fine for most cases.<\/p>\n\n\n

\/\/ database\/migrations\/2025_08_27_000000_add_profile_json_to_users_table.php<\/span>\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Migrations<\/span>\\Migration<\/span>;\nuse<\/span> Illuminate<\/span>\\Database<\/span>\\Schema<\/span>\\Blueprint<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Schema<\/span>;\n\nreturn<\/span> new<\/span> class<\/span> extends<\/span> Migration<\/span> <\/span>{\n    public<\/span> function<\/span> up<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        Schema::table('users'<\/span>, function<\/span> (Blueprint $table)<\/span> <\/span>{\n            $table->json('profile'<\/span>)->nullable();   \/\/ e.g. {\"country\":\"TR\",\"preferences\":{\"theme\":\"dark\"}}<\/span>\n        });\n    }\n\n    public<\/span> function<\/span> down<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        Schema::table('users'<\/span>, function<\/span> (Blueprint $table)<\/span> <\/span>{\n            $table->dropColumn('profile'<\/span>);\n        });\n    }\n};<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This migration adds a nullable profile<\/code> column intended to hold a JSON object with free-form keys such as country<\/code> and preferences<\/code>. Removing it in down()<\/code> keeps the migration reversible.<\/p>\n\n\n\n
Indexing tip:<\/strong> If you frequently filter by a nested property, consider indexing via a generated column (MySQL) or a GIN index (PostgreSQL JSONB).<\/p>\n\n\n
-- MySQL: generated (virtual) column + index for profile->country<\/span>\nALTER<\/span> TABLE<\/span> users<\/span>\n  ADD<\/span> COLUMN<\/span> country_code VARCHAR<\/span>(2<\/span>)\n    GENERATED<\/span> ALWAYS<\/span> AS<\/span> (JSON_UNQUOTE(JSON_EXTRACT(profile, '$.country'<\/span>))) VIRTUAL<\/span>,\n  ADD<\/span> INDEX<\/span> idx_users_country_code (country_code);\n\n-- PostgreSQL: convert to JSONB and index<\/span>\n-- ALTER TABLE users ADD COLUMN profile JSONB;<\/span>\nCREATE<\/span> INDEX<\/span> idx_users_profile_gin ON<\/span> users<\/span> USING<\/span> GIN ((profile));<\/code><\/span>Code language:<\/span> SQL (Structured Query Language)<\/span> (<\/span>sql<\/span>)<\/span><\/small><\/pre>\n\n\n
MySQL example projects $.country<\/code> into a virtual column to index it. PostgreSQL\u2019s GIN index accelerates containment and path queries on JSONB.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
2 – Casting JSON to Arrays\/Objects in Eloquent<\/strong><\/h2>\n\n\n\n
Use attribute casting so you can read\/write JSON naturally as arrays. Eloquent will automatically JSON-encode\/decode on save\/fetch.<\/p>\n\n\n
\/\/ app\/Models\/User.php<\/span>\nnamespace<\/span> App<\/span>\\Models<\/span>;\n\nuse<\/span> Illuminate<\/span>\\Foundation<\/span>\\Auth<\/span>\\User<\/span> as<\/span> Authenticatable<\/span>;\n\nclass<\/span> User<\/span> extends<\/span> Authenticatable<\/span>\n<\/span>{\n    protected<\/span> $fillable = ['name'<\/span>,'email'<\/span>,'password'<\/span>,'profile'<\/span>];\n\n    protected<\/span> $casts = [\n        'profile'<\/span> => 'array'<\/span>, \/\/ or 'collection' if you prefer Illuminate\\Support\\Collection<\/span>\n    ];\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Setting 'profile' => 'array'<\/code> means $user->profile<\/code> is an array in PHP. Assigning an array automatically serializes back to JSON when the model is saved.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
3 – Querying JSON Columns<\/strong><\/h2>\n\n\n\n
Laravel supports vendor-agnostic JSON path syntax like where('profile->country','TR')<\/code>, plus helpers such as whereJsonContains<\/code> for arrays\/objects.<\/p>\n\n\n
use<\/span> App<\/span>\\Models<\/span>\\User<\/span>;\n\n\/\/ Path operator (country == 'TR')<\/span>\n$turkish = User::where('profile->country'<\/span>, 'TR'<\/span>)->get();\n\n\/\/ Array contains (roles includes 'admin')<\/span>\n$admins = User::whereJsonContains('profile->roles'<\/span>, 'admin'<\/span>)->get();\n\n\/\/ Object contains (preferences has {\"theme\":\"dark\"})<\/span>\n$darkTheme = User::whereJsonContains('profile->preferences'<\/span>, ['theme'<\/span> => 'dark'<\/span>])->get();\n\n\/\/ Null checks inside JSON<\/span>\n$missingPhone = User::whereNull('profile->phone'<\/span>)->get();<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
where('profile->country','TR')<\/code> targets a nested key under profile<\/code>. whereJsonContains<\/code> is ideal when filtering arrays (roles<\/code>) or matching object fragments (preferences<\/code> contains theme: dark<\/code>).<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
4 – Validating and Persisting JSON Input<\/strong><\/h2>\n\n\n\n
Validate incoming JSON as an array and validate nested keys with dot notation. Then assign the validated array to the casted attribute.<\/p>\n\n\n
\/\/ app\/Http\/Controllers\/ProfileController.php<\/span>\nnamespace<\/span> App<\/span>\\Http<\/span>\\Controllers<\/span>;\n\nuse<\/span> App<\/span>\\Models<\/span>\\User<\/span>;\nuse<\/span> Illuminate<\/span>\\Http<\/span>\\Request<\/span>;\nuse<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\Auth<\/span>;\n\nclass<\/span> ProfileController<\/span> extends<\/span> Controller<\/span>\n<\/span>{\n    public<\/span> function<\/span> update<\/span>(Request $request)<\/span>\n    <\/span>{\n        $data = $request->validate([\n            'profile'<\/span> => ['required'<\/span>,'array'<\/span>],\n            'profile.country'<\/span> => ['required'<\/span>,'string'<\/span>,'size:2'<\/span>],\n            'profile.phone'<\/span> => ['nullable'<\/span>,'string'<\/span>,'max:30'<\/span>],\n            'profile.roles'<\/span> => ['nullable'<\/span>,'array'<\/span>],\n            'profile.roles.*'<\/span> => ['string'<\/span>],\n            'profile.preferences'<\/span> => ['nullable'<\/span>,'array'<\/span>],\n            'profile.preferences.theme'<\/span> => ['nullable'<\/span>,'in:light,dark'<\/span>],\n            'profile.preferences.notifications'<\/span> => ['nullable'<\/span>,'array'<\/span>],\n            'profile.preferences.notifications.email'<\/span> => ['boolean'<\/span>],\n            'profile.preferences.notifications.sms'<\/span> => ['boolean'<\/span>],\n        ]);\n\n        $user = Auth::user();\n        $user->profile = $data['profile'<\/span>]; \/\/ cast handles JSON<\/span>\n        $user->save();\n\n        return<\/span> back()->with('status'<\/span>,'Profile saved.'<\/span>);\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The validator ensures profile<\/code> is an array and that expected nested keys conform to your rules. Assigning the array to $user->profile<\/code> triggers casting and JSON persistence.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
5 – Updating Individual Nested Keys<\/strong><\/h2>\n\n\n\n
You can update a single nested path using the JSON path key syntax. This avoids fetching and rewriting the whole object for simple toggles.<\/p>\n\n\n
use<\/span> Illuminate<\/span>\\Support<\/span>\\Facades<\/span>\\DB<\/span>;\nuse<\/span> App<\/span>\\Models<\/span>\\User<\/span>;\n\n\/\/ Toggle email notifications ON for a user<\/span>\nUser::whereKey($id)->update([\n    \"profile->preferences->notifications->email\"<\/span> => true<\/span>,\n]);\n\n\/\/ Append item into a JSON array (DB-specific alternative)<\/span>\nDB::table('users'<\/span>)\n  ->where('id'<\/span>, $id)\n  ->update([\n      'profile'<\/span> => DB::raw(\"JSON_SET(profile, '$.roles', JSON_ARRAY_APPEND(JSON_EXTRACT(profile, '$.roles'), '$', 'editor'))\"<\/span>)\n  ]);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The first example uses Laravel\u2019s dotted JSON path to set a boolean inside nested objects. The second shows a DB-level array append using raw SQL (syntax varies by engine).<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
6 – UI: Editing JSON Settings in a Form<\/strong><\/h2>\n\n\n\n
Here\u2019s a small UI: a controller method to show the form and a Blade template that binds to the JSON fields. Submissions hit ProfileController@update<\/code> from above.<\/p>\n\n\n
\/\/ app\/Http\/Controllers\/ProfileController.php (add show() action)<\/span>\npublic<\/span> function<\/span> show<\/span>()<\/span>\n<\/span>{\n    $user = auth()->user();\n    return<\/span> view('profile.edit'<\/span>, ['user'<\/span> => $user]);\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The show()<\/code> action passes the current user to the view so you can pre-populate the form from the JSON column.<\/p>\n\n\n
<!-- resources\/views\/profile\/edit.blade.php -->\n@extends('layouts.app'<\/span>)\n\n@section('content'<\/span>)\n<div class<\/span>=\"container<\/span>\">\n  <h1<\/span> class<\/span>=\"mb<\/span>-4\">Profile<\/span> Settings<\/span><\/h1<\/span>>\n\n  @if<\/span>(session<\/span>('status<\/span>'))\n    <div<\/span> class<\/span>=\"alert<\/span> alert<\/span>-success<\/span>\"><\/span>{{ session('status'<\/span>) }}<\/div>\n  @endif<\/span>\n\n  <form method=\"POST\"<\/span> action=\"{{ route('profile.update') }}\"<\/span>>\n    @csrf\n    @method('PUT'<\/span>)\n\n    <div class<\/span>=\"row<\/span> g<\/span>-3\">\n      <div<\/span> class<\/span>=\"col<\/span>-md<\/span>-3\">\n        <label<\/span> class<\/span>=\"form<\/span>-label<\/span>\">Country<\/span> Code<\/span> (ISO2<\/span>)<\/label<\/span>>\n        <input<\/span> name<\/span>=\"profile<\/span>[country<\/span>]\" class<\/span>=\"form<\/span>-control<\/span>\"\n               value<\/span>=\"<\/span>{{ data_get($user->profile, 'country'<\/span>) }}\" maxlength=\"<\/span>2<\/span>\"\/>\n      <\/div>\n\n      <div class=\"<\/span>col-md-6<\/span>\">\n        <label class=\"<\/span>form-label\">Phone<\/label>\n        <input name=\"<\/span>profile[phone]\" class=\"<\/span>form-control\"\n               value=\"<\/span>{{ data_get($user->profile, 'phone'<\/span>) }}\"\/>\n      <\/div>\n\n      <div class=\"<\/span>col-md-12<\/span>\">\n        <label class=\"<\/span>form-label\">Roles (comma separated)<\/label>\n        <input name=\"<\/span>roles_csv\" class=\"<\/span>form-control\"\n               value=\"<\/span>{{ implode(','<\/span>, (array<\/span>) data_get($user->profile, 'roles'<\/span>, [])) }}\"\/>\n      <\/div>\n\n      <div class=\"<\/span>col-md-4<\/span>\">\n        <label class=\"<\/span>form-label\">Theme<\/label>\n        <select name=\"<\/span>profile[preferences][theme]\" class=\"<\/span>form-select\">\n          @php $theme = data_get($user->profile,'preferences.theme'); @endphp\n          <option value=\"<\/span>\" {{ $theme ? '' : 'selected' }}>System<\/option>\n          <option value=\"<\/span>light\" {{ $theme==='light' ? 'selected' : '' }}>Light<\/option>\n          <option value=\"<\/span>dark\"  {{ $theme==='dark'  ? 'selected' : '' }}>Dark<\/option>\n        <\/select>\n      <\/div>\n\n      <div class=\"<\/span>col-md-4<\/span> form-check mt-4<\/span>\">\n        @php $emailOn = (bool) data_get($user->profile,'preferences.notifications.email'); @endphp\n        <input id=\"<\/span>notif_email\" type=\"<\/span>checkbox\" class=\"<\/span>form-check-input\"\n               name=\"<\/span>profile[preferences][notifications][email]\" value=\"<\/span>1<\/span>\"\n               {{ $emailOn ? 'checked' : '' }} \/>\n        <label for=\"<\/span>notif_email\" class=\"<\/span>form-check-label\">Email Notifications<\/label>\n      <\/div>\n\n      <div class=\"<\/span>col-md-4<\/span> form-check mt-4<\/span>\">\n        @php $smsOn = (bool) data_get($user->profile,'preferences.notifications.sms'); @endphp\n        <input id=\"<\/span>notif_sms\" type=\"<\/span>checkbox\" class=\"<\/span>form-check-input\"\n               name=\"<\/span>profile[preferences][notifications][sms]\" value=\"<\/span>1<\/span>\"\n               {{ $smsOn ? 'checked' : '' }} \/>\n        <label for=\"<\/span>notif_sms\" class=\"<\/span>form-check-label\">SMS Notifications<\/label>\n      <\/div>\n    <\/div>\n\n    <button class=\"<\/span>btn btn-theme mt-3<\/span>\">Save Settings<\/button>\n  <\/form>\n<\/div>\n@endsection<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This form posts nested arrays using PHP\u2019s bracket notation (e.g., profile[preferences][theme]<\/code>). In the controller, the validator receives a structured array, which you assign to $user->profile<\/code>. The optional roles_csv<\/code> field is a UX shortcut\u2014if you want to support it, convert to an array before validation or within a form request.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
7 – Performance & Gotchas<\/strong><\/h2>\n\n\n\n
JSON columns are flexible but keep these in mind: index frequently filtered paths, avoid storing huge blobs that you rewrite often, and prefer stable columns for high-cardinality filters. When schema hardens, consider migrating hot properties into first-class columns.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
Wrapping Up<\/h2>\n\n\n\n
You created JSON columns, cast them in Eloquent, queried nested paths, validated and saved structured input, and built a UI for editing JSON settings. With careful indexing and path updates, JSON gives you agility without sacrificing query power.<\/p>\n\n\n\n\n
<\/div>\n\n\n\n\n
What\u2019s Next<\/h2>\n\n\n\n