Laravel Pdo Via Oci8 Laravel Package

Getting Started

Install the package via Composer:

composer require yajra/laravel-pdo-via-oci8

This package is a low-level PDO proxy for Oracle’s OCI8 extension — it is not intended for direct use by developers. Instead, it powers Laravel Oracle integrations like yajra/laravel-oci8. Your first real-world interaction will be through Laravel’s DB facades or Eloquent when configured for Oracle.

To begin:

1. Install yajra/laravel-oci8 (which depends on this package)
2. Configure an Oracle connection in config/database.php using driver oci8
3. Verify connectivity via DB::connection('oracle')->getPdo() — it will now return an instance of this package’s PDO wrapper.

Implementation Patterns

• Transparent Oracle PDO Abstraction: Use standard PDO methods (prepare, execute, bindValue) as usual — this package intercepts calls and delegates to OCI8 under the hood. It handles Oracle-specific challenges like CLOB binding, RAW types, and bind variable normalization.

• LOB Handling: Always bind CLOB/BLOB using PDO::PARAM_LOB:

  $stmt = $pdo->prepare("INSERT INTO logs (id, content) VALUES (?, ?)");
  $stmt->bindValue(1, $id);
  $stmt->bindValue(2, $content, PDO::PARAM_LOB);
  $stmt->execute();
  

• Client Identifier Tracking: For Oracle AWR/active session report visibility:

  $pdo->setAttribute(PDO::ATTR_CLIENT_IDENTIFIER, 'app-user-123');
  

• Timeout Control: Use statement-level call timeouts (v3.1+):

  $pdo->setAttribute(PDO::ATTR_ORACLE_TIMEOUT, 30000); // 30s
  

• Stringify Fetches for Consistency: Prevent numeric/decimal ambiguity from Oracle NUMBER:

  $pdo->setAttribute(PDO::ATTR_STRINGIFY_FETCHES, true);
  

Gotchas and Tips

• NULL CLOB Bug (Pre-v3.7.3): Prior versions crash on NULL LOBs. Ensure ≥v3.7.3 if handling CLOBs/NCLOBs.
• Placeholder Normalization: This package converts ? to :p0, :p1, etc. Avoid mixing ? and :named in one statement — Oracle’s parser may break unexpectedly.
• Connection State Isolation: Prefer oci_new_connect() (enabled by default in v3.7+) over oci_connect() to avoid session leaks (e.g., temp tables, PL/SQL package state persisting across requests).
• Error Suppression (Pre-v3.2.5): Old versions swallowed connection failures. Use ≥v3.2.5 to see exceptions and log Oracle connect errors properly.
• Raw OCI Access: Need OCI8-specific flags (e.g., OCI_COMMIT_ON_SUCCESS)? Get the underlying resource:

  $ociResource = $pdo->getAttribute(PDO::ATTR_ORIGINAL_CONNECTION);
  oci_execute($stmt, OCI_COMMIT_ON_SUCCESS);
  

• PHP 8.4 Compatibility: v3.6.0+ adds explicit support, and v3.7.1 silences deprecation warnings — upgrade if using PHP 8.4.
• Type Safety: v3.1+ adds strict return types and property hints. Ensure your IDE and Psalm/PHPStan configs align to avoid false positives.