Product Decisions This Supports
- Build vs. buy for shared domain logic. A package like
jn-devops/common ("Homeful Common Package") is the classic in-house answer to "should every product team re-implement our core models, enums, and business rules, or should we own a shared layer?" This package is the artifact of that decision — the assessment should confirm it is the decision, and whether it's still the right one.
- Service and surface consolidation. A commons package is what lets web, mobile API, back-office, and partner integrations speak the same domain language (same entities, same status enums, same validation rules). Adopting or extending it is a prerequisite for consistent behavior across surfaces.
- Monolith-to-services sequencing. If Homeful is extracting services or spinning up a second Laravel app, the commons package is the seam. Whether it's mature enough determines whether extraction is safe now or premature.
- Roadmap sequencing for platform work. Investment in commons (tests, docs, semver, release automation) is a platform bet. It should be justified against feature work by a measurable reduction in duplicated effort — otherwise it's a tax with no receipt.
- Make vs. reuse for adjacent capabilities. If the package already houses property/listing/eligibility logic, that changes "buy a SaaS for X" evaluations: the marginal cost of extending in-house drops, and vendor lock-in arguments get stronger.
- Onboarding and hiring leverage. A well-documented commons package compresses ramp-up for new engineers and new product lines. A poorly documented one increases ramp-up cost — this package's current signals (no description, zero stars, zero dependents) mean that benefit is currently unproven and must be validated, not assumed.
When to Consider This Package
Adopt / keep investing when:
- You operate two or more Laravel applications or services under the same org and are actively duplicating models, enums, traits, or business rules between them.
- You control the release cadence and versioning of every consumer — i.e., you can enforce semver, a changelog, and a deprecation policy. A commons package without governance becomes a coordination bottleneck within two release cycles.
- The package has a named owner, CI, and a test suite that runs on every consumer's PHP/Laravel matrix. Zero stars and zero dependents is expected for a private/internal package and is not a red flag by itself — the absence of an owner and tests is.
- The shared surface is domain contracts (entities, value objects, enums, DTOs, validation), not UI or framework glue. Contracts travel well; presentation code does not.
Look elsewhere / do not adopt when:
- You have one application. A commons package adds a version-bump, tag, and Composer-resolution step to every change for zero reuse benefit. Use plain classes in
app/ and revisit at app #2.
- The "common" content is a handful of helpers. A utility trait or two does not justify a package boundary — copy them or use an existing OSS helper library.
- There is no owner, no changelog, no tags, no tests. That is an unowned dependency with your business rules inside it; the risk is not that it breaks, it's that nobody is accountable when it does.
- Consumers need framework-agnostic code (queues outside Laravel, non-PHP services, data/ML pipelines). Coupling the domain layer to Laravel's container and Eloquent is a one-way door.
- You need external support, security advisories, or community maintenance. This is internal-only by construction; if that's a requirement, evaluate a maintained OSS domain library instead and accept the fit gap.
Due diligence before any commitment: confirm contents, license, PHP/Laravel version constraints, dependency footprint (a commons package that pulls in heavy transitive dependencies is a supply-chain and upgrade-cadence liability), test coverage, and who can merge to main.
How to Pitch It (Stakeholders)
To executives — one paragraph:
jn-devops/common is our internal shared library for the Homeful domain. Its value is not novelty; it's leverage: one place to define the business rules that would otherwise be reimplemented slightly differently in every product surface. That reduces rework, shortens time-to-market for new apps, and removes a class of "the app says X, the back office says Y" defects. The cost is governance — a package with no owner and no release discipline becomes a bottleneck, not an accelerant. The ask is small and specific: name an owner, require tests and a changelog, and enforce semantic versioning — then the package pays for itself across every subsequent build.
To engineering leads:
- Treat it as a product with users, not a folder of shared code. Users are consuming services; breaking changes are incidents.
- Publish via a private Composer registry with tagged releases and a CHANGELOG.
dev-main as a constraint is an incident waiting to happen.
- Draw a hard boundary: contracts and domain rules in, framework glue and presentation out. Anything requiring a service provider to bootstrap is a smell.
- Add a consumer matrix to CI (oldest and newest supported Laravel/PHP) so upgrades are boring.
- Track one metric: duplicate business rules removed per quarter. If it isn't falling, the package isn't doing its job.
To product and design:
A shared commons layer is what makes "consistent across web and mobile" cheap instead of a per-surface negotiation. It also means changes to core rules — eligibility, availability, pricing logic — ship everywhere at once, so rule changes require a coordinated release conversation with engineering, not a per-team ticket.