Articulate Laravel Package

Product Decisions This Supports

• Bounded-context ownership of shared tables. The package's core premise — many small entity classes over one physical table — is the technical enabler for a specific architectural decision: split the model, not the database. If we've decided to modularize a monolith without a data migration program, this is the persistence layer that decision needs.
• Build vs buy for an internal "context layer." Without this, teams hand-roll DTOs plus per-module query builders, or maintain a wrapper over Eloquent/Doctrine. That's typically weeks-to-months of engineering plus permanent upkeep. This is a credible buy candidate for that narrow need — not for general ORM replacement.
• Read/write segregation and least privilege. Read-only entities turn "reporting, public-API, and support tooling must not mutate this table" from a code-review convention into a thrown exception. That's a governance/security posture decision PMs can actually own.
• Performance roadmap sequencing. Three PSR-6 cache layers (L2 entity, query result, compiled statement) plus persistent PDO connections are DB-load levers available without re-architecture. They can defer read-replica or sharding investment by a phase — with the caveat that cache-coherence becomes an operational responsibility.
• Worker and batch-job reliability. Per-EntityManager identity maps and units of work give an explicit memory-safety story for long-running queue workers, which is usually tracked as a separate engineering initiative.
• Deployment standardization. The deliberate refusal to emit ENGINE/CHARSET/COLLATE on CREATE TABLE converts a hidden per-table drift problem into an explicit platform decision (set once at database/server level). Good — but it becomes a checklist item for ops, not an assumption.
• Schema shape decisions. First-class polymorphic many-to-many (MorphToMany/MorphedByMany) supports choosing a single taggables pivot over N per-type join tables — a decision that's expensive to reverse later.
• Index design discipline. #[Index(fields: [...])] takes PHP property names, so renames are caught by tooling. Supports a "indexes are part of the entity model" standard; the trade-off is that expression and prefix indexes are explicitly deferred — a real constraint for search-heavy workloads.

When to Consider This Package

Consider it when:

• PHP 8.4+ is an acceptable baseline (it is a hard requirement).
• You run a modular monolith where three or more contexts touch the same tables, and the shared entity class is a recognized coupling point — not a hypothetical one.
• A meaningful share of access is read-only or read-mostly (admin, reporting, public API projections).
• MySQL or PostgreSQL are the only targets.
• The team is comfortable owning persistence internals and can staff a named maintainer.
• You can pilot behind a single module boundary before any org-wide commitment.

Validate in a spike before committing: metadata merge/conflict behavior against a real, non-empty schema; sibling-entity write semantics and cache eviction; lazy-loading behavior inside long-running workers; migration generation round-tripping on a schema clone; locking and transaction behavior under the app's actual concurrency profile.

Look elsewhere when:

• You have one stable entity model per table. The README says this itself: it would fit, but wouldn't solve a meaningful problem. Don't pay the dependency cost for nothing.
• The team is standardized on Doctrine/Symfony or Eloquent/Laravel conventions and depends on that ecosystem (bundles, admin panels, profiling, community answers).
• You need vendor support contracts, procurement-friendly references, or an audited track record.
• Non-MySQL/PostgreSQL targets are on the roadmap (SQLite for tests, SQL Server, Oracle).
• You depend on expression/prefix/functional indexes, or column-name-level schema control. These are explicitly deferred, not just missing.
• You need CTEs, window functions, or advanced locking guarantees — verify, don't assume; "expected ORM foundations" is a claim, not a compatibility matrix.

Vendor risk, stated plainly: 3 stars, 0 dependents, effectively one maintainer, a 2.0.0 that already followed a breaking config change in 1.1.0. Apache-2.0 makes an internal fork viable, but "we can fork it" is a staffing commitment, not a risk mitigation. Mitigations: pin versions, forbid transitive reliance on undocumented behavior, and name an owner before the pilot starts.

How to Pitch It (Stakeholders)

For executives. We have shared tables that six teams read and write through one giant model. Every change to that model is a cross-team release risk, and every incident in it has an unclear owner. This package lets each module own only its slice of the same table — smaller blast radius, clearer ownership, no database split, no multi-quarter re-platforming. The software is free and permissively licensed; the real costs are a bounded pilot (one module, roughly two to four weeks) and a dependency we must own. The real risk is maturity: it's a young project with essentially one maintainer and no adoption footprint. That's exactly why the ask is a pilot with written success criteria and an exit path — fork or revert — not an org-wide mandate.

For engineering. It's a real ORM, not a wrapper: attributes, repositories, relations, migrations, type mapping, identity map, unit of work, lazy loading, three independent PSR-6 cache layers, and persistent connections. The differentiator is that the bounded context — not the table — is the modeling boundary, so LoginUser, AdminUser, and BillingCustomer can coexist over users with different fields, relations, and invariants. Read-only entities make "this context must not write" a ReadOnlyEntityException at persist()/remove() rather than a review comment. Per-EntityManager units of work give us a defensible answer to worker memory growth. What it does not give us: ecosystem breadth, expression indexes, MySQL table options, a compatibility matrix, or a support contract. Proposal: pilot behind the reporting or billing context. Success criteria: zero regressions on shared-entity behavior, measured query counts and L2 hit rate versus baseline, migrations round-tripping on a schema clone, and a signed-off fallback plan. If the pilot fails those, we keep the current ORM and we've spent two weeks learning something concrete about our own coupling.