Model Manager Laravel Package

Getting Started

Before anything else, confirm what you're actually installing. Despite the "model" in the name, this is a Pomm package (a PostgreSQL object-mapper), not an Eloquent extension. It will not give you Model::find(), relationships, or migrations. Treat it as a query/mapping layer you bolt onto Laravel rather than a drop-in ORM.

1. Verify availability. With 0 stars and 0 dependents, check Packagist for the exact name first. If it isn't published, add a VCS repository entry to composer.json and require it by branch:

   "repositories": [{ "type": "vcs", "url": "https://github.com/Umanit-Pomm/ModelManager" }]
   

2. Read in this order: composer.json (what Pomm version it pins, PHP constraint, autoload namespace) → README → src/ for the manager class/trait → tests/ for real usage examples. The tests are usually the only trustworthy documentation on a zero-adoption package.
3. First use case: a read-heavy PostgreSQL endpoint (reporting, dashboards, complex joins, CTEs, window functions) where Eloquent gets awkward. Wrap a Pomm connection, run one hand-written query, and map rows into a plain PHP DTO.
4. Wire it up with a small service provider that builds the manager from your existing config/database.php PostgreSQL DSN and binds it as a singleton. Inject it into a repository class — do not call it from controllers directly.

You should have one query returning typed objects through Laravel's container before you consider using it anywhere else.

Implementation Patterns

Read models alongside Eloquent. The most defensible pattern: keep Eloquent for writes, CRUD, and anything touching relationships; use this package for read-only projections and reporting queries. You get PostgreSQL-specific SQL without fighting the query builder, and you don't rewrite your domain layer.

Repository wrapper, not direct use. Bind an interface in a service provider and implement it with the manager. This gives you one seam to swap the package out later — important given the adoption numbers.

interface ReportRepository { public function monthlyTotals(int $year): array; }

final class PommReportRepository implements ReportRepository
{
    public function __construct(private ModelManager $manager) {}

    public function monthlyTotals(int $year): array
    {
        // map rows to DTOs here, not in the controller
    }
}

Share the connection. Configure the manager to reuse the same PDO/DSN as Laravel's pgsql connection. If they diverge, DB::transaction() will not roll back Pomm writes, and you'll get phantom rows in tests and production.

DTO mapping over arrays. Have the manager return value objects or readonly DTOs. Arrays leak column names into Blade/JSON responses and make schema changes a breaking change.

Query objects for hard SQL. When a query needs LATERAL, recursive CTEs, jsonb_path_query, or window functions, put it in a dedicated class rather than scattering raw SQL through services.

Testing. Use RefreshDatabase to build schema (via Laravel migrations), then query through the bound manager — this validates the SQL against real PostgreSQL. For unit tests, bind a fake implementation of your repository interface; don't mock the manager itself.

Gotchas and Tips

• No package discovery. There is no extra.laravel provider, no facade, no config publish. You write the service provider and the config array yourself.
• Version pinning is mandatory. Zero dependents means no ecosystem pressure to keep it compatible. Pin an exact version or a commit hash, and commit composer.lock. Budget for forking if it breaks.
• Pomm-version coupling. Check which pomm-project/* version it requires. A stale Pomm pin can conflict with other Postgres tooling in a large app.
• Duplicate connections are the #1 bug. Two PDO handles = broken transactions, invisible uncommitted rows, and connection-pool exhaustion under load. Pass the existing PDO in rather than letting the package dial out.
• DB::listen() won't see these queries. Pomm bypasses Laravel's query event pipeline. If you rely on Telescope, query logging, or a slow-query listener for observability, add explicit logging inside your repository wrapper or you'll have a blind spot.
• No Eloquent features. No events, observers, soft deletes, accessors, casts, or with() eager loading. Don't try to bridge them — it becomes a half-ORM that pleases nobody.
• PostgreSQL only. No SQLite in tests unless you keep those tests off this code path; CI must run a real Postgres service.
• env() in bindings breaks under config:cache. Read the connection details from config('database.connections.pgsql'), never env() inside a service provider.
• Parameter binding differs. Pomm's placeholder/quoting conventions are not Laravel's ?/:name builder semantics. Review any query with LIKE, :: casts, or quoted identifiers for surprises.
• Debugging strategy: log the rendered SQL and bindings on exception, wrap calls in a try/catch that rethrows with the SQL attached, and write one integration test per query against a seeded schema.
• Extension point that matters: wrap the manager in your own thin class from day one. When (not if) you need to replace or fork the package, only that one file changes.
• Adoption risk is the real finding. With no stars, no dependents, and no ecosystem, this is effectively unmaintained third-party code in your critical path. Isolate it, test it hard, and keep the blast radius to read paths.