- How do I install afiqiqmal/malaysiaholiday in a Laravel application?
- Install it with Composer using composer require afiqiqmal/malaysiaholiday. Laravel package discovery registers the service provider and facade automatically, so you can call the facade without editing config/app.php. There are no infrastructure prerequisites such as a database, queue worker, or cache service. Pin the major version you have validated against, for example ^4.2, so upstream data-source changes do not land silently in production.
- Which PHP and Laravel versions does this Malaysia holiday package support?
- The package targets PHP 8.x and Laravel 9 through 11 and is delivered as a standard Composer package. Check the require block in composer.json for the exact constraints before adopting it in a legacy application. Because it is a data-provisioning package with no framework-internal coupling, it sits cleanly alongside an existing calendar or scheduling layer. No infrastructure prerequisites are needed to get a first call working.
- How do I query Malaysian public holidays by state and year?
- The package exposes a facade for retrieving holiday dates, so you supply a state and a year and receive the matching holidays. Always pass an explicit state rather than assuming a single national list, since several Malaysian holidays apply only to specific states. Confirm the package pins Asia/Kuala_Lumpur for date handling instead of inheriting the server timezone. Coverage is intended for all states and federal territories, but verify the ones you actually operate in.
- Does the package make HTTP requests at runtime or ship a bundled holiday dataset?
- Version 4.2.1 adds a second upstream source, calendarmalaysia.com, used for 2025 onwards alongside the original source. Whether that fetch happens at release/build time or on demand at runtime is the single most important thing to verify for your deployment, because runtime egress adds a latency and availability dependency on a site you do not control. If it fetches at runtime, review the timeout, retry, cache TTL, and negative-caching behaviour before putting it in a request path. If it ships a dataset, regeneration and release cadence become the thing to track.
- Why did my tests break after upgrading to malaysiaholiday 4.2.1?
- The 4.2.1 release is additive: it introduces a new source key on holiday records plus a fallback data path. Consumers reading name and date are unaffected, but strict shape assertions break, including DTO constructors with fixed arguments, assertSame on arrays, JSON-schema validation, and snapshot tests. The fix is mechanical: loosen the assertion, allow the extra key, or map the payload into your own DTO. It is not a design problem in the package.
- What is the source key in MalaysiaHoliday 4.2.1 and can I rely on it?
- The source key records which upstream a holiday record came from, which is useful for auditing and for spotting the 2024 to 2025 boundary where the two sources overlap. Whether it is always populated for older or bundled data, and whether its enumerated values are stable enough to key on, are open questions you should verify against real output for your states. Treat it as diagnostic metadata for an audit trail rather than as the basis for business logic. If you persist holidays locally, store it alongside the record so you can explain a disputed date later.
- Should I call the MalaysiaHoliday facade directly inside payroll or SLA business logic?
- Not directly. The package is correctness-critical rather than infrastructure-critical, so a wrong answer silently corrupts downstream calculations instead of throwing an exception. Wrap it behind an internal HolidayCalendar interface with methods such as isHoliday(CarbonInterface $date, ?string $state): bool and have that implementation use the package as the fetch or seed mechanism, not the query mechanism. Persist resolved holidays into your own table with date, name, states, is_observed, source, fetched_at, and package_version so business logic reads stable local data with an audit trail.
- How does the package interpret sahaja and kecuali state notes on Malaysian holidays?
- Those Malay notes are semantically load-bearing: sahaja means only and kecuali means except, so the parsing decides whether a holiday is restricted to particular states or excluded from them. A misparse flips a state-restricted holiday into a national one or the reverse, which is exactly the failure mode that breaks statutory holiday pay. Check whether the parsing is covered by unit tests with fixtures per state from real page variants. If it is not, validate the output for your own states before trusting it.
- Does the package distinguish observed holidays from gazetted holidays and handle amendments?
- That distinction is not guaranteed by the package overview and is worth confirming before you depend on it, since observed versus gazetted dates shift payroll and overtime calculations. Post-publication amendments such as replacement holidays and one-off election or coronation days are another gap to test explicitly. If your domain needs those cases, treat package output as seed data and layer your own overrides on top. Record what you override so a later package update does not silently reintroduce a wrong date.
- What happens if calendarmalaysia.com changes its markup or blocks automated access?
- The 2025-and-later data path depends on parsing a third-party site you do not control, so a markup change or an access block is a real availability risk. Check that site's terms of service for automated access and confirm whether the package ships a bundled dataset or fetches live. Mitigate by caching resolved holidays in your own table and by alerting on empty or unexpectedly short holiday lists rather than trusting a silent partial result. Also ask how the 2024 to 2025 transition is reconciled: deduplicated, preferred-source-wins, or naive concatenation, since naive concatenation produces visible discontinuities.