Common Laravel Package

Getting Started

eclipsephp/common is not a package you evaluate in isolation — it is the shared floor under every Eclipse PHP package. The practical starting point is therefore usually transitive: you add a Filament/Eclipse plugin, Composer pulls in eclipsephp/common, and your job becomes conforming to it rather than wiring it up.

Minimal steps:

1. Confirm what you actually have. Run composer show eclipsephp/common (or lando composer show eclipsephp/common) and note the resolved version and its Filament constraint. Because every Eclipse package requires it, all of them will share one resolved version — that version is effectively your platform baseline.
2. Read the source before the docs. Start at vendor/eclipsephp/common/src/Foundation. That directory is the intended public surface: the base classes that Eclipse plugins extend. The README covers project-specific documentation, but for a package this small and this internal, the Foundation classes are the documentation.
3. Check for auto-discovery. Look at the package composer.json for a laravel.providers entry. If a service provider is listed, it is already registered; if not, you will need to register it yourself in your plugin's provider. Do not run vendor:publish speculatively — the guidelines explicitly say not to publish config, migrations, or assets unless the package's own behaviour requires it.
4. Set up a reproduction harness. Because this is a Testbench package, the fastest way to understand a Foundation class is to exercise it in the workbench app: lando testbench migrate, then a scratch test in tests/Feature. Do not try to reason about it from static reading alone.

First real use case: you are building a Filament resource and are about to write a base class, a table configuration helper, or a layout scaffold. Stop and check src/Foundation first. If something comparable exists, extend it — the value of this package is precisely that all Eclipse plugins behave identically, and a divergent local base class silently breaks that.

Implementation Patterns

Foundation-first, then local. Treat src/Foundation as a contract, not a utility drawer. The intended pattern is class MyResource extends FoundationResource with thin additions, not copy-paste-and-modify. When a Foundation class almost fits, subclass and override the narrowest method rather than reimplementing the class.

Filament table convention is enforced by consensus, not by code. The project rule is that resource tables use toggleable(), searchable() and sortable() on all columns:

TextColumn::make('name')
    ->toggleable()
    ->searchable()
    ->sortable(),

Apply this uniformly across every resource, including ones that do not extend a Foundation class. Consistency here is what makes the shared base classes worth having — if half your tables are searchable and half are not, users experience the package boundary as a bug.

Extend, register, don't fork. Integration happens at three points:

• Inheritance — subclass a Foundation class for plugin-specific behaviour.
• Container bindings — bind interfaces to implementations in your plugin's service provider when the base package leaves a choice open (expected, given the "non-opinionated" framing).
• Filament plugin registration — register your plugin's panels/resources through the standard Filament plugin mechanism; the common package supplies foundations, not registrations.

Keep the workbench as a real harness. Package code lives in src/, tests in tests/, workbench-only code in workbench/. When you need to prove a Foundation change is safe, reproduce the consuming behaviour in the workbench rather than reasoning about downstream plugins. Feature tests go in tests/Feature, unit tests in tests/Unit, support classes in tests/Support.

Respect the ripple radius. Every Eclipse package depends on this one. A change to a Foundation method signature is a breaking change for N consumers simultaneously — there is no version window in which half the ecosystem is on the old API, because Composer resolves them all to one version. Prefer additive changes: new methods, new optional parameters, new subclasses. Document any unavoidable break in the README, and rely on the auto-generated CHANGELOG.md rather than hand-editing it.

Verify with the project's own loop. This repo runs in Docker via Lando: lando test for Pest, lando format for Pint (pass flags after --, e.g. lando format -- --dirty). Run both before calling anything done. For artisan against the workbench app, lando testbench <command> — not lando artisan.

Gotchas and Tips

• Zero stars and zero dependents is a signal, not a verdict. This is an internal package with no community footprint, which means no Stack Overflow answers, no blog posts, and no third-party examples. Your only reliable sources are the source code, the README, and the commit history. Budget for reading rather than searching.

• "Non-opinionated" means the wiring is yours. When something does not work, the first hypothesis should be missing registration, not a package bug. Check the service provider, the Filament plugin registration, and any container bindings before diving into vendor code.

• Foundation classes are public API by definition. Even though they live in src/Foundation and look like internal scaffolding, downstream plugins extend them directly. A "harmless refactor" — renaming a protected method, tightening a parameter type, adding an abstract method — will break consumers at class-load time. Check the abstract/interface surface before editing.

• Watch the Filament version boundary. Filament has moved namespaces, column APIs, and plugin contracts across major versions. Before relying on any Foundation class that touches Filament, confirm which Filament major the package targets and that your consuming plugin matches. A mismatch typically surfaces as a confusing Class not found or a method that silently no-ops, not as a clean Composer conflict.

• Deep inheritance chains are the main fragility risk. If a Foundation class is three levels deep and you need to change behaviour at level two, prefer overriding at the level you own. Reaching past your immediate parent couples you to internals that may shift.

• Do not publish what you were not told to publish. No config, migrations, or assets are expected to be publishable here. If a vendor:publish tag happens to exist, treat it as an escape hatch, not a setup step — published copies stop receiving upstream fixes.

• Debug inside vendor code deliberately. dump() in a Foundation method plus a workbench reproduction is the fastest path when a base class behaves unexpectedly. Remove the instrumentation before finishing; do not commit vendor edits (patch them via a fork or an override instead).

• Do not add dependencies here without asking. This is load-bearing for the whole ecosystem; a new transitive dependency propagates to every Eclipse plugin. The project rules call this out explicitly, and it is one of the few places where the answer is genuinely "ask first."

• The CHANGELOG is generated. Read it to learn what changed between versions, but never edit it — a GitHub Action owns that file and your edit will be clobbered or conflict.