Download the PHP package codyjheiser/laravel-db2-eloquent without Composer

Laravel DB2 Eloquent

Laravel Eloquent extensions for IBM DB2 databases with column mapping, multi-column relationships, and auto-filtering.

Table of Contents

• Installation
• Basic Usage
• Generating Models
• Database Schema
  • Testing Database
• Column Mapping
  • Casts
  • IBM Date Cast
  • IBM Time Cast
  • IBM DateTime Cast
• Automatic Filtering
• Multi-Column Relationships
• Union ALL (Combined Tables)
• Extensions (Joined Tables)
• Query Logging
• Helper Methods
• Configuration
• Development
• License

Installation

Requirements

• PHP 8.4+
• Laravel 12+

Basic Usage

Generating Models

Use the Artisan command to quickly scaffold new DB2 models:

The generated model includes the schema, table, casts, and maps properties ready to be filled in.

Database Schema

Models use a $schema property to define the database schema prefix, keeping table definitions DRY.

If your table already includes the schema prefix (e.g., R60FILES.VINITEM), it will be used as-is.

Testing Database

Use the testing() scope to query the testing database instead of production. By default, this swaps R to T in the schema prefix:

Custom Schema Configuration

You can customize how test schemas are determined:

Important: When using testing() with withExtensions(), you must call testing() FIRST:

Column Mapping

Define $maps to translate DB columns to human-readable names:

• Queries use mapped names: where('customer_number', '123')
• Output uses mapped names: { "customer_number": "123", "name": "Acme" }
• Access properties with mapped names: $customer->customer_number

Auto-Select Mapped Columns

By default, queries automatically select only columns defined in $maps. This prevents selecting unnecessary columns.

Select All Columns

Disable Auto-Select Per Model

Disable Auto-Mapping on Output

Casts

Casts can use either raw DB column names or mapped names:

The company_number column is auto-cast to integer for all IBM models.

IBM Date Cast

IBM stores dates as integers in Ymd format (e.g., 20251217). Use the IbmDate cast to convert to Carbon or a formatted string:

Format shortcuts:

• :date → Y-m-d
• :us → m/d/Y
• :eu → d/m/Y
• Or use any custom PHP date format string

Carbon instance (no format):

IBM Time Cast

IBM stores times as integers in Hms format (e.g., 73733 = 07:37:33). Use the IbmTime cast to convert to Carbon or a formatted string:

Format shortcuts:

• :time → H:i:s
• :12h → g:i:s A
• :short → H:i
• Or use any custom PHP date format string

Carbon instance (no format):

IBM DateTime Cast

Combine date and time into a single Carbon instance. Works with a single datetime column or two separate date + time columns:

Format shortcuts:

• :datetime → Y-m-d H:i:s
• :date → Y-m-d
• :us → m/d/Y g:i:s A
• :eu → d/m/Y H:i:s
• Or use any custom PHP date format string

Two-column access:

Custom input formats:

Duplicate Mapped Names

When multiple DB columns map to the same name, first wins:

Automatic Filtering

By default, queries automatically filter by:

• delete_code = 'A' (active records only)
• company_number = '1' (default company)

These filters only apply if the model has delete_code and company_number mapped.

Bypass Filters

Disable Per Model

Multi-Column Relationships

IBM/DB2 tables often use composite keys. Use array syntax for multi-column relationships.

When both models have the same mapped column names, you only need to specify them once:

Supported relationship types:

• belongsTo($related, $foreignKey) - ownerKey defaults to same as foreignKey
• hasMany($related, $foreignKey) - localKey defaults to same as foreignKey
• hasOne($related, $foreignKey) - localKey defaults to same as foreignKey

Column names are automatically translated to DB columns using each model's $maps. The trait generates DB2-compatible SQL using AND/OR conditions instead of tuple IN syntax.

Union ALL (Combined Tables)

IBM DB2 tables often have a "live" and "history" version with identical columns (e.g., SBSCHD for live service calls and SBHSHD for history). The HasUnionSources trait lets you query both tables as one unified, read-only model via UNION ALL.

Define a Base Union Model

The base class uses the trait and defines the shared columns, casts, and relationships. Only columns common to all source tables should be in $maps:

Extend Into Individual Tables

Child classes extend the base and override $table. They inherit all maps, casts, and relationships — no code duplication. The trait automatically detects child classes and skips all union/read-only behavior for them, so they work as normal models:

Query the Union

The union model works like any other model for reads. All standard query methods work:

Source Identification

Every row includes a _source column identifying which table it came from:

Read-Only Protection

The union model is read-only. All write operations throw ReadOnlyModelException:

Child classes (Live, History) are not read-only — they work as normal models.

How It Works

1. The trait rewrites $maps to identity mappings (call_number => call_number) so the outer query operates on already-aliased names
2. Each source gets its own SELECT DB_COL AS mapped_name FROM table with auto-filters applied individually
3. Sources are joined with UNION ALL as a FROM subquery
4. A _source literal column is added to each source identifying the origin table
5. isUnionModel() uses reflection to detect whether the concrete class directly uses the trait — children that inherit it behave as normal models

Extensions (Joined Tables)

Define extension tables that join to the base table:

Note: Extension table names include the schema prefix (e.g., R60FSDTA.VINITEMX). When using testing() scope, extension schemas are automatically converted (R→T).

Query with Extensions

Check Extension Records (Instance)

Load Extension Separately

Query Logging

Inline Logging (Recommended)

Enable logging for specific queries inline:

Global Logging

Enable logging for all subsequent queries:

Log channels:

• 'stderr' (default) - outputs to console/terminal
• null or 'default' - writes to Laravel's app log file
• ['stderr', 'default'] - logs to both

Custom SQL Formatter

Helper Methods

Configuration

Connection

By default, models use a connection named db2. Configure this in your config/database.php:

Override the connection in your model if needed:

Schema Configuration

Models generated with make:db2-model pull their schema from config, allowing you to manage schemas centrally. Add this to your config/database.php:

Generated models use the config with a fallback to the default:

This lets you switch schemas via environment variables without modifying model code.

Default Company

Override the default company filter:

Disable Features

Development

Requirements

• PHP 8.4+
• Composer
• For integration tests: IBM i Access ODBC Driver + pdo_odbc PHP extension

Setup

Testing

The test suite has two types of tests:

Unit Tests - Run without a database (uses SQLite in-memory):

Integration Tests - Tests against a real DB2 connection:

All Tests:

Test Structure

Unit tests run on CI (GitHub Actions) without DB2. Integration tests are skipped unless DB2 credentials are configured.

Environment Variables

For integration tests, create a .env file with:

License

MIT License. See LICENSE for details.