Db Oracle Laravel Package

Getting Started

This package is the Oracle DB driver for the Yii3 database abstraction layer (yiisoft/db), not a Laravel package — so the first decision is whether you're adopting it standalone or bridging it into a Laravel app. If you're on Laravel, expect to bypass Eloquent entirely and use yiisoft/db query builders directly (e.g. via a service provider binding that wraps the Connection).

1. Prerequisites: PHP 8.1 – 8.5 (v2.0.0 dropped older versions). You also need the oci8 or pdo_oci extension and an Oracle client library available to PHP.
2. Install: composer require yiisoft/db-oracle:^2.0. This pulls in yiisoft/db (v2 compatible) — note the v2 driver is tightly coupled to the v2 db package, so pin both together.
3. First wiring: Build a Connection with a Dsn (refactored in #283/#344), then obtain a Schema, Command, and QueryBuilder from it. The Connection::getColumnBuilderClass() method (#358) is your extension point for custom column behavior.
4. First use case: Introspecting an existing Oracle schema and running typed queries — $connection->getSchema()->getTableSchema('ORDERS') will now return columns parsed into typed ColumnInterface implementations (BooleanColumn, DateTimeColumn, JsonColumn, etc.), which you can branch on for casting.

Look at Schema::findColumns() and ColumnFactory first if anything behaves oddly on introspection — that's where the v2 refactor concentrated most of the risk.

Implementation Patterns

Typed column handling. v2.0.0 is fundamentally about replacing generic string-based column metadata with ColumnInterface classes chosen by database type. Day-to-day this means: when you read a schema, you get behavior-specific objects. Use instanceof checks (or the column's type constant, now separated per #279) to decide casting logic rather than comparing raw type strings — which are now lowercased (#299).

Batch inserts. The API changed in v2: DMLQueryBuilder::insertBatch($table, $rows, $columns = []) replaces the old batchInsert($table, $columns, $rows) (#268). Note also that $rows now accepts Traversable when $columns is empty (#260), so you can stream a generator of rows directly.

RETURNING clauses. insertReturningPks() replaces insertWithReturningPks() (#330) in both Command and DMLQueryBuilder. If you rely on Oracle's RETURNING ... INTO to get generated IDs back after insert, this is the method your repository layer calls.

DDL with safety. dropTable() now takes $ifExists and $cascade flags (#307). Wrap migrations using:

$command->dropTable('LEGACY_TABLE', ifExists: true, cascade: true);

Case-sensitive LIKE. The new caseSensitive option on the like condition (#311) matters on Oracle, where collation behavior differs from MySQL/Postgres. Use it explicitly for user-facing search filters where you don't want Oracle's default collation semantics bleeding through.

Type support to lean on. v2 adds JSON (#303), boolean (#319), enumeration (#382), and collation (#352) column support. For enum columns, you can now let the driver validate against allowed values instead of hand-rolling checks in your model layer.

Custom aggregation SQL. ArrayMergeBuilder, LongestBuilder, and ShortestBuilder (#357/#363) give you first-class builders for Oracle's COLLECT, LONGEST, and SHORTEST aggregate functions instead of raw SQL fragments.

Gotchas and Tips

• This is a major bump with many renames and removals. Before upgrading from 1.x, grep your codebase for: batchInsert → insertBatch, insertWithReturningPks → insertReturningPks, ColumnSchemaInterface → ColumnInterface (and the old ColumnInterface was removed, #296/#298), and TableSchema (removed entirely, #348). These will be silent-ish failures or fatal errors depending on strict typing.
• Unsigned columns now throw. If you have any schema definitions or migrations specifying unsigned, Oracle will reject them with an exception (#378). This is intentional — Oracle has no unsigned concept — but it means porting MySQL schemas needs sanitization.
• Exception class change. Yiisoft\Db\Exception\InvalidArgumentException is replaced by native \InvalidArgumentException (#332). Any catch blocks targeting the old class will miss.
• getCacheKey() / getCacheTag() are gone from Schema (#315). If you were using schema caching via these, you'll need to rebuild caching around your own layer or the db package's newer mechanisms.
• Debugging introspection failures: Most v2 bugs will surface in ColumnFactory or ColumnDefinitionParser. The #383 fix (parentheses parsing in column definitions) is a hint that Oracle type strings with nested parens (e.g. NUMBER(10,2)) were a fragile area — verify your numeric and enum columns after upgrade.
• QuoterInterface swap (#272): if you subclassed Schema and overrode getRawTableName(), that contract now lives elsewhere. Check your custom schema subclasses.
• Expression namespaces moved (#365): any hard-coded use statements for expression classes need updating to the new namespace paths in yiisoft/db v2.
• Constructor signature changes on QueryBuilder (#294) and Dsn (#283/#344) mean any manual instantiation (common in test fixtures or DI factories) will break. Prefer factory methods from Connection where available.
• selectExists() alias change (#326): if you compare generated SQL strings in tests, snapshots will need regenerating — the alias now matches other DBMS drivers for consistency.
• Extension point: for custom column casting, override via Connection::getColumnBuilderClass() (#358) rather than monkey-patching Schema. That's the sanctioned v2 hook.