Download the PHP package simba-jirira-source/laravel-schema-contract without Composer

Purpose

Laravel Schema Contract is developer tooling for Laravel applications. It answers a focused question for v0.1.x:

Do my database columns and Eloquent model casts describe compatible data types?

The package discovers Eloquent models, reads live schema metadata from each model's effective connection and table, normalizes database and cast types, and reports contract violations with CI-friendly exit codes.

v0.1.x scope: Database Schema ↔ Eloquent Model only.

The analyzer is read-only. It never mutates schema, models, or application data.

Requirements

• PHP 8.3+
• Laravel 13.x
• Composer 2+
• A reachable database connection for the models being analyzed

Installation

Install the package as a development dependency:

Laravel auto-discovery registers the service provider and Artisan command.

Publish the configuration file when you need custom discovery or ignore rules:

Quick start

1. Ensure your application database schema is migrated.

2. Run the check against all discovered models:

3. Fix reported ERROR rows before merging. Treat WARNING rows as recommended improvements; they do not fail CI by default.

Analyze one model:

Short class names work when they resolve to exactly one discovered model.

Example output

Given a users table with a boolean active column, a decimal credit_limit, and a JSON preferences column, and a model that casts credit_limit to integer while leaving preferences uncast:

Severity meanings:

Commands

Exit codes

Examples of exit code 2: unresolvable model argument, ambiguous short class name, missing database table for a targeted model.

When no models are discovered, the command exits 0 and prints a warning.

Configuration

Configuration lives in config/schema-contract.php after publishing.

Supported databases and types

Database drivers

See docs/DATABASE_SUPPORT.md for driver-specific metadata behavior, verified type mappings, and known limitations.

Normalized database types

The package maps raw driver metadata to internal database types:

boolean, integer, big_integer, small_integer, decimal, float, double, string, text, date, datetime, timestamp, json, uuid, enum, binary, unknown

Unknown or incomplete metadata maps to unknown and produces conservative warnings rather than crashing analysis.

Normalized cast types

Built-in and class-based casts normalize to:

boolean, integer, float, double, decimal, string, array, object, collection, date, datetime, timestamp, enum, custom, unknown

Custom cast classes are recognized without being misclassified as enums. Expressions such as decimal:2 retain scale metadata.

Contract rules (v0.1.x)

• Cast matches column type
• Decimal scale matches (when precision/scale metadata is available)
• JSON columns require a compatible cast (missing cast is a warning)
• Date/time columns require compatible casts (standard Laravel timestamp columns are excluded from noisy warnings)

CI usage

Add the check to your pipeline after migrations are available (or against a migrated test database):

The command exits 1 when contract errors exist, so a failing step blocks the pipeline without extra flags.

Warnings alone do not fail the command.

This repository validates the package itself with GitHub Actions:

Forks and consuming applications can mirror the same quality commands during development:

Limitations

Not implemented in v0.1.x (planned for later releases):

• Database ↔ Validation (FormRequest validation analysis)
• API Resource analysis
• Livewire analysis
• Baseline generation and suppressions
• JSON or GitHub annotation output formats
• Automatic fixes

Current analysis limits:

• Driver metadata varies; missing precision/scale never produces false-positive decimal errors
• PostgreSQL native enums and extension types may map to unknown
• SQLite does not distinguish integer column sizes in schema metadata
• The package reports structural contract metadata only; it does not dump row data
• Ignored models are skipped during bulk checks but can still be analyzed when targeted explicitly

Roadmap

Each release is intended to be independently useful. See the product specification for the full scope and roadmap.

Testing

Package development

Clone the repository and install dependencies:

Run the full quality suite:

Individual commands:

composer test runs the release gate with serial Pest for reliable Testbench bootstrapping.

Driver integration tests

SQLite tests run in the default suite. MySQL and PostgreSQL grouped tests require environment configuration. See docs/DATABASE_SUPPORT.md.

Contributing

Please see CONTRIBUTING.md. For significant changes, open an issue first.

Security

The analyzer may include model names, table names, column names, and type metadata in output. It does not dump application records.

Please review SECURITY.md for vulnerability reporting.

License

Laravel Schema Contract is open-source software licensed under the MIT license.

Changelog

Please see CHANGELOG.md for release notes.