Common Laravel Package

Technical Evaluation

Architecture fit. eclipsephp/common is a horizontal foundation layer, not a feature package. Its job is to supply shared src/Foundation base classes and common implementation classes that every other Eclipse plugin package depends on. Structurally this is idiomatic Laravel: a package service provider, PSR-4 autoloading under src/, workbench app under workbench/, and Testbench for package-level testing. It targets Laravel 12's streamlined structure and PHP 8.3+, which aligns with a modern Laravel baseline. The one architectural caveat is that "non-opinionated" is aspirational rather than literal — a hard dependency on Filament is a significant opinion, because it pulls an entire admin-panel framework into your dependency graph whether or not you build admin UI.

Integration feasibility. Installation is trivial (composer require, service provider auto-discovery under Laravel 12). The real cost is comprehension, not wiring. The published documentation surface is a README plus AI-agent guidance (AGENTS.md, .ai/rules), which tells you how the maintainers work on the package but not what its public API is. There is no API reference, no migration guide, no versioned changelog (it is auto-generated by a GitHub Action), and no example consumer repository. You will be reverse-engineering Foundation semantics from source.

Technical risk. This is the dominant concern and it is high relative to the package's apparent value:

• Zero external validation. 0 stars, 0 dependents, score 0.26, opportunity 26.21. There is no evidence anyone outside the maintainer's own ecosystem has installed this from Packagist. That means installability, Laravel minor-version compatibility, and Filament version compatibility are all unproven by third parties.
• Bus factor of roughly one. A single-maintainer internal library published publicly. No security response process, no stated support window, no deprecation policy.
• Filament coupling. Filament ships breaking majors on a fast cadence. A foundation package pinned against it will gate your own Filament upgrade timeline on the maintainer's release cadence.
• No contracts. "Non-opinionated" implies stability, but with no semver statement you cannot reason about upgrade blast radius.
• Agent-oriented docs are not user docs. The provided material is instructions for AI contributors, which is a maintenance-burden optimization for the maintainer — not a signal of product maturity.

Key questions to put to the maintainer or resolve in a spike:

1. What exactly is the public API surface of src/Foundation, and which classes are intended for downstream extension vs. internal use?
2. What is the versioning and breaking-change policy, and is there a support/LTS commitment?
3. Which Filament major(s) are supported, and how are Filament upgrades sequenced?
4. Is there a reference implementation or consuming application we can inspect?
5. What is the test coverage and CI matrix (PHP versions × Laravel versions × Filament versions)?
6. Is the package intended for third-party adoption at all, or is it an internal artifact published for convenience?
7. Who is the named maintainer, and what is the escalation path for a security issue?

Integration Approach

Stack fit. Good, if and only if you are already committed to the Eclipse plugin suite and to Filament. On Laravel 12 / PHP 8.3 the package is aligned by construction. If you are not adopting Filament, treat this package as a non-starter — the dependency is not optional and the value proposition collapses without sibling Eclipse packages consuming the same Foundation classes.

Migration path. Greenfield: straightforward, add the dependency before any Foundation-dependent code exists. Brownfield: there is no migration guide, so do not attempt to retrofit existing base classes onto src/Foundation. The correct brownfield move is a strangler pattern — introduce the package behind your own thin abstraction and move one bounded context at a time.

Compatibility. Pin to an exact version, not a caret range. Given the absence of dependents, an unpinned constraint is an unhedged bet on a changelog you don't control. Verify the Filament constraint in composer.json explicitly against your installed Filament major before committing. Consider a Composer path or VCS repository pointing at a fork you control, so you retain the ability to patch a Foundation class without waiting on upstream.

Sequencing.

1. Spike (1–2 days): clone, read src/Foundation end to end, run the Testbench suite locally, and inventory the public API. Output: a written API summary and a list of classes you would actually inherit from.
2. Decision gate: confirm the foundation classes save more code than the abstraction costs. If the answer is "we'd use two of twelve classes," stop.
3. Wrap, don't inherit broadly. Define your own base classes or interfaces that compose the Foundation classes, so an upstream break is a one-file fix rather than a codebase-wide edit.
4. Pilot in one bounded context — a single resource, a single admin module — with the dependency pinned and a fork ready.
5. Ratchet forward only after the maintainer has demonstrated at least one clean minor-version upgrade.

Operational Impact

Maintenance. Low line-count, high cognitive load. You are not maintaining much code, but you are inheriting an unversioned external contract. Budget recurring time to diff upstream releases, since the auto-generated CHANGELOG.md will not tell you what actually changed in a human-readable way. If your fork diverges, you own merge reconciliation indefinitely.

Support. Effectively self-support. There is no vendor, no SLA, no visible issue triage history to gauge responsiveness. Plan for the realistic case where a question goes unanswered and your team reads the source. This is acceptable for internal tooling with a known maintainer relationship; it is not acceptable for anything on a regulated or customer-facing critical path without a fork-and-own arrangement.

Scaling. Technically a non-issue — it is a library, it adds no runtime service, no queue, no storage. The scaling concern is organizational: every additional team or repository that adopts it multiplies the coordination cost of a Filament or Laravel upgrade, because the package becomes a shared chokepoint in your upgrade graph. Keep adoption count deliberately small until versioning discipline is proven.

Failure modes to plan for.

• Upstream abandonment. Most likely failure. Mitigation: fork on day one, keep it in your VCS, and treat upstream as a patch source rather than a dependency.
• Filament major bump blocking your upgrade. Mitigation: verify the Filament constraint before you need to move; be prepared to carry a local patch.
• Silent breaking change under a minor version. Mitigation: exact pin plus a lockfile-diff review on every composer update.
• Foundation class semantics diverging from your assumptions. Mitigation: wrap, don't inherit; write characterization tests against the behavior you depend on.
• PHP minor-version floor creep (8.3+ today, 8.4 tomorrow) forcing your runtime forward. Mitigation: track the CI matrix before it tracks you.

Ramp-up. Engineers need three things the docs do not currently supply: an API map of src/Foundation, a worked example of a consuming package, and the Eclipse naming and structural conventions. The AGENTS.md material helps AI-assisted contributors conform to style but does not onboard a human to the domain model. Expect 1–2 days of source reading for a senior Laravel engineer, plus ongoing context-holding cost because there is no external community to offload questions to.

Bottom line. This is an internal shared library that happens to be public, not a community package. Its 0.26 score and zero dependents accurately reflect that. Adopt it only as part of a deliberate commitment to the Eclipse plugin suite, pinned and forked, with a wrapper layer and a named internal owner. Absent that commitment, the correct decision is to decline.