Dialect Laravel Package

Getting Started

First, check whether you actually need it. darrylkuhn/dialect predates native JSON support in Laravel. If you are on Laravel 5.4+ you already get almost everything this package offers ($casts = ['meta' => 'array'] for encode/decode and where('meta->key', ...) for querying). Only reach for Dialect if you are pinned to an older Laravel (roughly 5.0–5.3) or have a legacy codebase that already depends on it.

Install (on a compatible framework version):

composer require darrylkuhn/dialect

First use case — store and query a JSON document on a model:

1. Add a json column in a migration (or use the package's JSON column type if you are on an old Laravel that lacks it):

Schema::table('users', function (Blueprint $table) {
    $table->json('settings')->nullable();
});

2. Pull the trait into the model and declare which attributes are JSON:

use DarrylKuhn\Dialect\Json;

class User extends Model
{
    use Json;

    protected $jsonColumns = ['settings'];
}

3. Write an array and query a nested key:

$user->settings = ['theme' => 'dark', 'lang' => 'en'];
$user->save();

User::where('settings->lang', 'en')->get();

Where to look first: the trait you add to the model, the jsonColumns (or equivalent cast list) property, and the package's query grammar overrides. Those three pieces are the whole mental model — everything else is driver-specific SQL generation.

Implementation Patterns

Declarative JSON columns on the model. Rather than scattered json_encode/json_decode calls, list JSON-backed attributes once on the model. All reads return arrays (or scalars/objects depending on config) and all writes accept arrays. This keeps controller and repository code free of serialization logic.

Query with arrow notation. The core convenience is treating a JSON document like a namespaced column:

User::where('settings->theme', 'dark')->first();
User::where('settings->notifications->email', true)->get();

The package rewrites these into the driver's native extract expression at compile time, so it works in where, orderBy, and (depending on version) pluck/select.

Combine with normal Eloquent features. Because the package plugs into the query grammar, the arrow syntax composes with the rest of the builder — scopes, orWhere, whereIn, pagination, and relationships all behave normally. Prefer wrapping common JSON filters in local scopes so the arrow syntax lives in one place:

public function scopeWithTheme($q, string $theme)
{
    return $q->where('settings->theme', $theme);
}

Service/repository integration. Treat the JSON document as an aggregate: expose typed accessors or value objects (e.g., a Settings class) that read from the JSON column and write back through the model. This gives you validation and defaults without losing the flexibility of a schemaless column.

Integration tip — dual-write during migration. If you are moving off Dialect onto native Laravel casting, keep jsonColumns populated and add a $casts entry, then read via the native cast. The on-disk format is the same JSON text; only the access layer changes.

Feature flags / arbitrary metadata. The classic good fit: a meta column for options that vary per row (theme, locale, feature toggles) where you do not want a migration for every new key, but you do want to filter on it.

Gotchas and Tips

This package is effectively abandoned. Last release was August 2021, and it has no support for modern Laravel (8/9/10/11+). Composer will almost certainly refuse to install it against current laravel/framework constraints, and even if forced, the query-grammar internals it overrides have changed substantially. On any new project, use native $casts + -> syntax instead; that is the single most important takeaway.

Driver differences are where the bugs hide. The package generates different SQL for MySQL (JSON_EXTRACT), Postgres (-> / ->>), and SQLite. Two things commonly differ from what you expect:

• -> vs ->> on Postgres affects whether you get a quoted JSON string or a plain text scalar. Comparisons can silently fail if you compare "en" (with quotes) to en.
• Boolean and numeric values may come back as strings from Postgres unless you cast explicitly.

Cast the extracted value. Do not assume a where('meta->count', '>', 5) comparison happens on an integer. Coerce with ->where('meta->count', '>', (int) $n) and, where supported, cast the column in the select list.

Index your JSON paths deliberately. Neither Dialect nor native Laravel can index an arbitrary JSON query for you. On MySQL 5.7+ use generated columns + indexes; on Postgres use expression indexes (((meta->>'status'))). Without this, JSON filters degrade to full scans.

Null and missing-key semantics. A missing key and an explicit null are frequently indistinguishable after extraction. If your application relies on the difference, encode a sentinel or check key existence separately (JSON_CONTAINS_PATH / ? operator), not through the package's convenience syntax.

Debug the generated SQL. When an arrow query returns nothing, call ->toSql() and ->getBindings() before blaming the package — most failures are quoting/escaping issues with keys containing dots, dashes, or spaces. Keys with . are ambiguous with nesting syntax; avoid them or use a separate extraction path.

Quoting and case sensitivity. Postgres folds unquoted identifiers; MySQL column names are case-insensitive on some platforms but not others. Keep JSON keys lowercase and delimiter-free to stay portable across drivers.

Extension point: if you need a driver the package does not handle well, the grammar override is the place to hook in — but treat this as a maintenance liability. A custom cast plus a handful of raw selectRaw/whereRaw expressions is usually a sturdier, more upgrade-safe alternative than forking an abandoned grammar.

Plan the exit. Because the storage format (JSON text) is identical to native Laravel, migration is mostly mechanical: replace use Json with $casts, delete $jsonColumns, and keep the arrow query syntax (native Laravel supports it). Budget this migration rather than building new features on Dialect.