Laravel Cloud Search Laravel Package

Getting Started

This release (0.4.0) is a feature/compatibility release — no deprecations called out, no migration guide needed. Treat it as a safe upgrade unless you're still on PHP 7.0.

1. Check your PHP floor first. The package now requires PHP >= 7.1. If any CI job, Docker image, or legacy service still runs 7.0, pin the previous version. If you're on Laravel 8 you're already on PHP >= 7.3, so this is a non-issue in practice.
2. Upgrade: composer update the package (0.4.0 adds Laravel 8 support, so illuminate/* constraints now resolve on an L8 app that previously had to hold the package back — or was blocked entirely).
3. Read the README first. It was rewritten/refreshed in this release; that's the authoritative surface for the two methods worth learning on day one: whereLiteral() and expression().
4. First use case: you have a query where a plain where() can't express the condition — a comparison against a SQL function, a cast, a NOW()/INTERVAL term, or a column-to-column comparison. Instead of dropping to DB::raw() inside where() (which often gets quoted or bound in ways you didn't intend), use whereLiteral(). Then reach for the new FieldTypes constants anywhere your code currently passes field-type strings around.

Implementation Patterns

Encapsulate literals in query scopes. The natural home for whereLiteral() is a model scope or a repository method, not a controller:

public function scopeExpired(Builder $query): Builder
{
    return $query->whereLiteral('expires_at < NOW()');
}

This keeps raw fragments in one auditable place and makes it obvious during review where unparameterised SQL lives.

Pair expression() with selectRaw-style usage. The release notes mention a bug fix in expression() — so if you were working around it, remove the workaround and pin the constraint to >=0.4.0 in composer.json so the fix is guaranteed present:

"require": { "vendor/package": "^0.4" }

Use FieldTypes constants instead of magic strings. Anywhere you're mapping a column to a type — dynamic filter builders, schema introspection wrappers, validation-driven query construction — swap 'int' / 'string' literals for the new constants. The payoff is IDE autocompletion and a single place to change if a type name shifts:

$value = match ($field->type) {
    FieldTypes::INT    => (int) $value,
    FieldTypes::STRING => (string) $value,
};

Check the source for the exact constant names before bulk-replacing — release notes don't enumerate them.

Laravel 8 integration. No new config or service provider steps are implied. On L8 the package should drop into the existing auto-discovery flow; if you maintain a package that depends on this one, widen your own illuminate/support constraint to include ^8.0 now that upstream supports it.

Gotchas and Tips

• whereLiteral() is raw SQL — it does not parameterise. Never interpolate request input into it. If the fragment needs a value, build it with bindings elsewhere or pass it through the package's expression API and verify with ->toSql() / ->getBindings().
• The expression() fix is the real reason to upgrade. If you were previously getting slightly wrong SQL out of that method, your tests may have been written against the buggy output. Run your query-assertion tests after upgrading and re-check any toSql() snapshots.
• 0.x semver. The version is still pre-1.0, so minor bumps may contain signature changes. There's no upgrade guide in these notes — diff the public methods in src/ against your usage before rolling out broadly.
• Debugging raw fragments: dump the builder with dd($query->toSql(), $query->getBindings()) immediately after the whereLiteral() call. Placement matters — a literal inside an orWhere group can silently change precedence, so wrap groups with a closure when mixing with normal where()s.
• Don't be surprised by the .gitignore and README changes — they're housekeeping, not behaviour. Same for the "one small bug" phrasing: it's under-specified, so if you filed an issue about expression(), confirm your specific case is the one fixed rather than assuming.
• Extension point: the FieldTypes constants suggest the package expects you to hand it typed fields rather than raw strings. If you have your own field-type enum, this is the moment to align it — the package's constants become the canonical mapping and your enum just delegates.