Common Laravel Package

Product Decisions This Supports

• Decide whether to standardize Laravel services on an internal shared foundation. This package is best treated as internal platform infrastructure, not a customer-facing product. Adopting it supports a “build once, reuse across services” decision for branch models, repository contracts, primary-key traits, cache tagging, and domain exceptions.
• Roadmap acceleration for branch-aware features. The Branch model, HasBranch trait, and HasBranchInterface directly support products where data must be segmented by regional office, distribution channel, or organizational unit—common in zakat collection/distribution workflows, donor management, branch dashboards, and regional reporting.
• Build vs. adopt decision. If teams are repeatedly rebuilding repository abstractions, UUID/integer primary-key handling, branch relationships, and cache-aware repositories, this package is a candidate to adopt instead of maintaining parallel internal utilities. The decision should be “adopt and own” rather than “buy” in the commercial sense, because the package is proprietary and has minimal external adoption.
• Architecture standardization across teams. Contracts such as ResourceInterface, ModelRepositoryInterface, and EloquentAwareRepositoryInterface support a consistent repository/DDD-style approach. This is useful when multiple squads or services need a shared convention for data access and model behavior.
• Performance and caching strategy. TaggableCacheAware and the cache-aware repository contracts support decisions around read-heavy endpoints, dashboards, and branch listing caches. This can justify prioritizing cache-tagging work where repeated queries are costly.
• Risk and scope decisions. With 0 stars, 0 dependents, basic documentation, and a proprietary license, the PM should not position this as a community-validated dependency. The supported decision is a controlled internal pilot, with explicit ownership, migration scope, and exit criteria.

When to Consider This Package

• Consider adoption if:

  • Your organization is inside the Inisiatif Zakat ecosystem or is explicitly allowed to use a proprietary internal package.
  • You are building or maintaining Laravel 10–12 applications on PHP 8.2–8.4.
  • Your product needs branch/regional data segmentation and you do not already have a standard multi-tenancy or branch architecture.
  • You want a shared repository pattern, UUID/integer primary-key traits, cache-aware repositories, and domain exceptions across services.
  • You have an internal owner who can maintain the package, absorb breaking changes such as the v3 namespace migration, and support onboarding.
  • You can pilot it in one branch-heavy service—for example donor management or branch operations—before wider rollout.

• Look elsewhere if:

  • You need open-source licensing, community support, or predictable third-party maintenance.
  • Your application is small and does not justify repository abstractions, branch traits, or cache tagging.
  • You already standardize on another multi-tenancy or branch solution such as Spatie, Filament, Nova, or an internal platform layer.
  • You cannot tolerate proprietary licensing, thin documentation, low external adoption, or namespace-level breaking changes.
  • You need a customer-facing SDK or a package with broad ecosystem validation. This is not that package.

How to Pitch It (Stakeholders)

For executives: “This is an internal Laravel foundation package that can reduce duplicate work across branch-aware services. It gives us shared building blocks for regional/branch data, repository conventions, UUID handling, and caching, so teams do not rebuild the same plumbing in every application. The strategic value is standardization and faster delivery of branch-heavy features, not external market differentiation. The main risks are that it is proprietary, has very low external adoption, and needs an internal owner. I recommend a contained pilot in one service, with success measured by reduced boilerplate, faster feature delivery, and lower maintenance effort.”

For engineering: “The package provides concrete shared infrastructure: a Branch model and migration, HasBranch for branch relationships, UuidPrimaryKey and IntegerPrimaryKey traits, AbstractRepository plus repository contracts, TaggableCacheAware for tagged caching, and domain exceptions for consistent error handling. The tradeoffs are low community validation, limited documentation, proprietary licensing, and the v3 namespace migration from Inisiatif\Package\Contract\... to Inisiatif\Package\Common\Contracts\.... Next steps should be: pilot it in the most branch-heavy service, map existing models to ResourceInterface, validate repository overhead versus direct Eloquent, test cache tagging on a real dashboard endpoint, and assign a long-term owner before broader adoption.”

Call to action: “Approve a time-boxed pilot in donor management or branch operations, with a clear go/no-go review covering migration effort, developer experience, performance impact, and ownership. Do not position this as a general-purpose open-source dependency; position it as a controlled internal platform bet.”