Malaysiaholiday Laravel Package

Product Decisions This Supports

• Malaysian market localization: Ships accurate public holiday data (via publicholidays.com.my) plus school holiday terms, making it a viable foundation for any product sold into Malaysia — HR/leave management, payroll, booking/scheduling, retail promotions, logistics SLAs, and education-adjacent apps.
• Roadmap planning for 2025+: The 4.2.1 fallback to calendarmalaysia.com for years not covered by the primary source removes the "data cliff" risk that previously made post-2024 roadmaps uncertain. You can now plan features into FY2025+ without a manual data-maintenance commitment.
• Build vs. buy: Avoids building and maintaining a holiday/calendar data pipeline (scraping, normalization, yearly updates, state-level edge cases) — a recurring cost most teams underestimate. Adopt and redirect engineering effort to core product.
• Use cases unlocked: Leave/attendance calculators, payroll and overtime rules, appointment and delivery scheduling, campaign calendars, academic-term planning, and "is it a working day?" logic — all with state-level granularity.
• New source key: Enables provenance-aware UX and support tooling (e.g., showing "data via calendarmalaysia.com" or logging source discrepancies) and supports auditability for compliance-sensitive customers.
• Malay state-note handling (sahaja/kecuali): Correctly interprets "only" and "except" qualifiers, which is the difference between a defensible payroll/leave calculation and a legal dispute. This de-risks compliance-heavy segments (HR, payroll, finance).

When to Consider This Package

Adopt when:

• You serve Malaysian users and need public and/or school holiday awareness.
• You need state-level precision (e.g., Sabah/Sarawak differences, sahaja/kecuali exceptions).
• You want a maintained data source rather than an in-house scraper, and you value the explicit fallback strategy for future years.
• Your stack is Laravel/PHP and you want first-class framework integration.
• You need provenance (source) for audit or support workflows.

Look elsewhere or supplement when:

• You need real-time or officially authoritative government data with SLAs — this wraps third-party community sources, so treat it as best-effort, not a system of record for regulated payroll.
• You operate outside Malaysia, or need multi-country coverage from one dependency.
• You require Islamic calendar calculations (Ramadan/Eid dates vary by moon sighting) beyond published holiday lists — validate with an authoritative source.
• Your architecture is not PHP/Laravel, or you cannot accept third-party data licensing/availability risk.
• You need guaranteed uptime; plan a caching/staleness strategy and monitor the source field for fallbacks.

How to Pitch It (Stakeholders)

To executives: This package gives us reliable Malaysian public and school holiday data — including state-level nuances — without building or maintaining a data pipeline ourselves. Release 4.2.1 closes the biggest risk we had (no data past 2024) by adding an automatic fallback source from 2025 onward, and it now tells us which source each date came from. Net effect: we can commit to Malaysian-market features on our roadmap with lower build cost and lower compliance risk, and we avoid a recurring engineering tax every holiday season.

To engineering: A Laravel/PHP package that returns Malaysian public holidays and school holidays, with state-level handling (sahaja/kecuali) and a new source key indicating where each entry came from. Primary data is publicholidays.com.my; from 2025 it falls back to calendarmalaysia.com where coverage is missing. Integrate behind our own abstraction layer, cache aggressively, persist the source field, and add a stale-data alert. Treat it as best-effort data, not a compliance system of record — validate payroll-critical dates against an authoritative source. No breaking changes noted in this release; effort to adopt is low, and it replaces maintenance work we would otherwise own.