Aranguent Laravel Package

Getting Started

Before you install anything, check your platform. This release drops Laravel 11 and adds Laravel 12, so the package is now locked to a single major Laravel version. Verify composer.json (laravel/framework: ^12.0, PHP 8.4 supported) before running composer update, otherwise you will resolve to an older beta or get a conflict.

Minimal path:

1. composer require the driver, then publish its config if the package ships one.
2. Add an arangodb connection block to config/database.php (host, port, database, username, password, and any graph/analyzer defaults) and set DB_CONNECTION=arangodb in .env.
3. Confirm the handshake. The new getServerVersion on the connection makes this a one-liner you can drop into php artisan tinker or a health-check route — useful for asserting the ArangoDB server version your deployment targets.
4. Run php artisan db:show. This release extends it with ArangoDB-specific output (server version, collections, graphs, analyzers), so it is the fastest way to validate credentials, database selection, and permissions in one shot.
5. Follow with php artisan db:table <collection> — new in this release — to inspect a single collection's structure, indexes, and document count before you write any model code.

Where to look first in the docs: docs/key-options.md. The migration key-option selection logic was reworked here, and it determines _key generation strategy for every collection you create. Getting it wrong is expensive to fix later; getting it right up front saves a data migration.

First real use case: a read-only Eloquent model over an existing collection, plus db:table to confirm the schema matches your assumptions. Don't start with migrations — start by reading data you already have.

Implementation Patterns

Model-first, graph-second. Use standard Eloquent models for document CRUD; reach for the graph APIs only when traversal actually pays for itself. The whereDoesntHaveRelation family added in this release lets you express "documents with no edges matching X" in the query builder, which removes a large class of N+1 traversals from graph-adjacent models.

Pattern matching belongs in the builder now. whereLike / orWhereLike / whereNotLike / orWhereNotLike and the NOT LIKE string operator mean you should stop hand-writing AQL for the common prefix/suffix search cases. Keep a thin repository boundary so the handful of genuinely AQL-shaped queries stay isolated from the ones that are now plain builder calls.

Array operators for set membership. ALL NOT IN, ANY NOT IN, and NONE NOT IN map directly onto AQL's quantified array semantics. This is the idiomatic way to express "none of these tags are present" in a document store — prefer it over chained whereNotIn, which reads poorly and generates noisier filters.

Correlated queries via lateralJoin. For "latest N child documents per parent" style reports, lateralJoin is far cheaper than pulling parents and looping. Pair it with the new union aggregate support when you need a rolled-up total across the lateral result set.

Migrations as the source of truth for schema objects. Collections, indexes, analyzers, and graphs all belong in migrations. This release adds dropAllAnalyzers() and getIndex / getIndexes / columns on the schema builder, which finally makes analyzer and index lifecycles testable — you can assert on introspection output inside a test rather than eyeballing the web UI. Multidimensional index support is available if you index nested array fields.

Idempotent upserts. insertOrIgnoreUsing is the pattern for sync jobs: feed it a batch, let the unique index arbitrate, and diff the affected count to decide whether to emit change events. It replaces the read-then-write loop most people were writing by hand.

Introspection for admin tooling. getViews(), getAnalyzers(), and getGraphs() (renamed this release) return Laravel-standard arrays/lists, so you can build a schema browser or a CI drift check that compares migration-declared structure against live structure.

Operational hooks. threadCount() on the connection plus corrected query-duration logging gives you a usable dashboard: emit duration as a histogram, threadCount as a gauge, and alert on saturation. This is a meaningful upgrade over the previous release, where duration numbers could not be trusted for SLOs.

Gotchas and Tips

The three renames are silent breakage. getAllViews → getViews, getAllAnalyzers → getAnalyzers, getAllGraphs → getGraphs. Nothing will warn you at install time; you will get BadMethodCallException at runtime, possibly only inside an admin screen nobody tests. grep -rn "getAllViews\|getAllAnalyzers\|getAllGraphs" app/ tests/ database/ before you bump.

Schema introspection now returns arrays, not objects. Methods like getTable and getTables conform to the Laravel standard and return arrays or lists of arrays. Any code doing $table->name instead of $table['name'] breaks. This is the change most likely to bite Laravel developers specifically, because it looks like the framework's own API and code was written assuming the old shape.

Pin the beta exactly. "vendor/package": "1.0.0-beta.12" — not ^1.0@beta. Beta releases in a package this young routinely carry breaking changes between patch-level betas, and the renames above are proof. Pair the pin with a CI matrix that runs against Laravel 12 only.

Existing collections don't get new key options. The improved default key-option selection applies to collections created by new migrations. If you have production collections already, you need an explicit migration (and a data copy) to change _key strategy — the docs page is worth reading in full before you assume it's retroactive.

Query duration logging was broken. If you built alerts or budget dashboards on the old numbers, recalibrate rather than assuming a regression. Historical data is not comparable to what this release emits.

The regex operator (=~) was fixed. If you had a workaround — escaped patterns, a raw AQL escape hatch, or a client-side filter — remove it and re-test. Leaving a workaround on top of a fixed operator usually produces double-escaping and silent zero-result queries, which is a miserable thing to debug.

Prefer model:show over guesswork. The new Artisan command resolves attributes, casts, relations, and the underlying collection in one view. When a model behaves unexpectedly, this is a faster first step than dumping the query log — particularly with document stores where "column not found" isn't the error you get.

Extension points worth knowing: the schema builder is the safest place to add custom ArangoDB-specific helpers (analyzers, graph definitions) because it's already versioned through migrations. Wrap raw AQL in a dedicated query object rather than sprinkling DB::select through controllers — when the next breaking change lands on the builder, you'll have one place to fix.

Debugging tip: when a builder query returns nothing unexpectedly, drop to db:table on the target collection first. Document stores make it easy to be querying the right field name in the wrong collection (or the right collection in the wrong database), and the schema view catches that in seconds.