Php Database Laravel Package

Getting Started

The v1.0 release notes are a single sentence — "first release of ORM based PHP database" — so treat the README and src/ as the actual specification. There is no migration guide, no documented API surface, and no prior assessment to diff against. Everything below is the discovery path you should follow before writing product code.

First 15 minutes:

1. composer require <vendor>/<package> (or dev-main if Packagist isn't live yet — check composer.json name and version).
2. Inspect the package's composer.json for extra.laravel.providers and extra.laravel.aliases — if present, the provider is auto-discovered and there is nothing to register in config/app.php. If absent on a Laravel 11+ app, register manually in bootstrap/providers.php.
3. Run php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" and diff what lands in config/ against the package defaults. Note the config key namespace — you'll reference it constantly.
4. Read src/ top-down: the service provider (what's bound into the container and under what keys), the connection/manager class, and the base model or query-builder entry point. Those three files define 80% of your day-to-day API.
5. Check tests/ for usage examples. On a v1.0 with thin docs, the test suite is usually the most accurate documentation you'll get.

First use case: point the package at a single throwaway SQLite database and run one select and one insert through its public API. Confirm you can get a connection, execute a query, and read a result before touching your real schema. If that path isn't obvious from the README, that itself is your signal about the package's maturity.

Implementation Patterns

Wrap it, don't sprinkle it. Whatever the package exposes — a manager, a connection factory, a base model — bind it behind your own interface and resolve that from the container. A first-release ORM with no stability guarantees is exactly the kind of dependency you want to be able to swap or pin without a repo-wide find-and-replace.

// app/Contracts/Records.php
interface Records { public function find(int $id): ?array; }

// app/Providers/AppServiceProvider.php
$this->app->bind(Records::class, PackageRecords::class);

Resolve connections per-tenant/per-connection, not globally. If the package lets you configure multiple connections, keep the config array as the single source of truth and resolve the connection name at call time rather than statically caching one instance.

Keep schema definition out of the ORM layer. Since the package is described as a database layer rather than a migration tool, assume Laravel migrations remain your schema owner. Let the package read and write; let php artisan migrate define. Mixing the two on a v1.0 is where you'll get bitten first.

Test against the real engine. Use RefreshDatabase with the package's connection configured in phpunit.xml so your tests exercise the same driver as production. An ORM released at v1.0 will have dialect-specific edge cases (identifier quoting, boolean handling, RETURNING support) that an in-memory SQLite run will hide.

Pin the version. "vendor/package": "1.0.*" in composer.json, not ^1.0, until you've watched a point release land and confirmed the changelog discipline.

Gotchas and Tips

• The release notes tell you nothing. No feature list, no breaking-change policy, no supported PHP/Laravel matrix in the notes. Verify the require block in composer.json covers your PHP and illuminate/* versions before you plan around it.
• "ORM based PHP database" is ambiguous. It may mean an ActiveRecord-style model layer, a query-builder wrapper, or a DBAL. Read the base class signature first — that single fact determines whether this replaces Eloquent or sits underneath it.
• Auto-discovery is not guaranteed. A first release often ships a provider without the extra.laravel block. If php artisan about doesn't show it and container resolution fails with a Target [...] is not instantiable error, register the provider by hand.
• Config caching bites on first install. After vendor:publish, run php artisan config:clear. A cached config from before the publish step is the single most common cause of "my settings are ignored."
• Debugging queries: check whether the package exposes a query log or toSql()-style method. If not, attach a DB::listen() in a service provider — assuming it routes through Laravel's connection factory, this will still catch it. If it opens PDO handles independently, you'll need the package's own logging hook, which may not exist yet.
• No documented extension points. Avoid subclassing internal classes to add behaviour; you'll be broken by the first patch release. Prefer decorator classes around your own interface.
• Treat it as pre-stable despite the 1.0 label. A "first release" versioned 1.0 has not earned semver trust — there is no 1.x history to demonstrate what the maintainers consider breaking. Keep the abstraction layer from the section above and you can absorb a rewrite in a single file.
• Watch the repo, not just the changelog. For a package this young, issue activity and commit cadence are better predictors of viability than any version number. If you're considering it for anything long-lived, make that check part of the adoption decision rather than a follow-up.