Weave Code
Yasumi Laravel Package
azuyalabs/yasumi
Yasumi is a PHP library for retrieving holiday dates and names across many countries and regions. Calculation- and rule-driven, it needs no database and offers a simple API to query, list, and check holidays for any year.
Yasumi (Japanese for "holiday") is a rule-driven PHP library for retrieving the dates and names of holidays and special celebrations across many countries and states. Instead of relying on a database, it calculates holidays from their underlying rules, making it lightweight and easy to integrate into any PHP project. Install it via Composer with composer require azuyalabs/yasumi and start querying holidays immediately.
- Create a provider per country and year, e.g.
Yasumi::create('USA', 2026) - Iterate over all holidays or fetch a specific one by name
- Check whether a given date is a holiday
- Rule-based calculation—no database setup required
- Requires PHP 8.2+ (supports 8.2–8.5)
Frequently asked questions about Yasumi
- How do I install Yasumi in a Laravel application?
- Install Yasumi with Composer by running composer require azuyalabs/yasumi. It requires PHP 8.2 or higher and has no Laravel-specific dependencies, so you can use it directly in controllers, services, or jobs. There is no mandatory service provider; optionally bind a configured provider in Laravel's container for injection.
- Which Laravel versions are supported by Yasumi?
- Yasumi is framework-agnostic and works with Laravel 8 and newer as long as the app runs PHP 8.2 or higher. Because it has no Laravel dependencies, it does not track Laravel release cycles. Validate it in your app's test suite after Laravel upgrades.
- What are common use cases for Yasumi in Laravel?
- Yasumi fits payroll, leave management, scheduling, business-day calculations, and reminder logic that depends on public or regional holidays. It abstracts country and regional rules behind a clean API, reducing custom date logic in your Laravel services. It is especially useful for multi-country applications that need consistent holiday behavior.
- Does Yasumi require a database or external API?
- No, Yasumi is calculation and rule driven, so it does not require a database or external holiday API. It is stateless and can run in serverless or containerized Laravel deployments. You can still customize or extend providers if you need company-specific dates.
- How do I check if a date is a holiday with Yasumi?
- Create a provider for the country and year, such as Yasumi::create('USA', 2026), then call isHoliday(new DateTime('2026-07-04')) or getHoliday('independenceDay'). You can also iterate the provider to list all holidays with names and dates. Use the provider's localized name and date methods for display.
- Can I add custom or company-specific holidays to Yasumi?
- Yes, Yasumi supports custom holidays by extending providers or creating custom holiday classes for company-specific or floating dates. This requires more work than standard country holidays and should be covered by tests. Review the provider extension points and validate timezone and edge-case behavior for your use case.
- Is Yasumi suitable for high-volume production holiday calculations?
- Yasumi processes holidays in memory and is fast for typical request-level checks, but very high-throughput batch jobs may benefit from caching. Cache provider results per country and year, or precompute holiday sets if you perform many checks. Benchmark against your latency targets before rolling out at scale.
- How do I keep holiday data up to date in Laravel?
- Yasumi's rule-driven approach reduces static data maintenance, but holiday rules still change when governments add or move public holidays. Pin a known version, monitor releases and security notes, and add regression tests for the countries you support. For critical payroll or scheduling flows, include a periodic review or automated update check in CI/CD.
- What are alternatives to Yasumi for holiday calculations in PHP and Laravel?
- Alternatives include Carbon with custom holiday logic, Google's Holiday API, and older libraries such as PEAR Date_Holidays. Carbon gives full control but requires you to maintain rules yourself; APIs can add network and licensing constraints. Choose Yasumi when you want broad country coverage, offline calculation, and no database dependency.
- How should I test holiday logic when using Yasumi in Laravel?
- Unit test known holiday dates, leap years, timezone or DST transitions, and any custom holidays you add. In Laravel, use PHPUnit or Pest and freeze time where needed, then assert isHoliday() and getHoliday() results for representative countries and years. Include regression tests for country rule changes before upgrading Yasumi.
Weaver
How can I help you explore Laravel packages today?