Yasumi Laravel Package

Technical Evaluation

Architecture Fit

• Domain Alignment: Yasumi is a lightweight, domain-specific library for holiday calculations, making it a strong fit for applications requiring date-based business logic (e.g., payroll, leave management, scheduling). It abstracts complex holiday rules (e.g., country/region-specific holidays, custom exceptions) into a clean API, reducing custom logic in the application layer.
• Separation of Concerns: Ideal for microservices or modular monoliths where holiday logic is decoupled from core business logic. Can be injected as a dependency (e.g., via Laravel’s service container) without tight coupling.
• Stateless Design: Since Yasumi relies on configuration (e.g., JSON/YAML holiday definitions), it avoids persistent storage dependencies, aligning with serverless or stateless architectures.

Integration Feasibility

• Laravel Native Support: Built for PHP, with no Laravel-specific dependencies (unlike some packages). Can be integrated via Composer with minimal boilerplate. Works seamlessly with Laravel’s facades, service providers, or dependency injection.
• Configuration Flexibility: Supports JSON/YAML holiday definitions, enabling dynamic updates (e.g., fetching from a database or API at runtime). Can be pre-loaded during bootstrapping or lazily loaded as needed.
• Localization: Out-of-the-box support for multi-country/region holidays, reducing the need for custom implementations in global applications.

Technical Risk

• Holiday Data Maintenance: Holiday rules change frequently (e.g., new public holidays, regional variations). Risk of stale data if not automated (e.g., periodic updates via API or CI/CD). Mitigation: Implement a data refresh pipeline (e.g., cron job + GitHub Actions).
• Performance Overhead: For applications processing high-volume date calculations (e.g., batch payroll), Yasumi’s in-memory processing may become a bottleneck. Benchmark against alternatives like Carbon + custom logic if latency is critical.
• Edge Cases: Limited documentation on handling custom holiday exceptions (e.g., company-specific holidays) or timezone-aware calculations. Requires upfront validation of use cases.
• Deprecation Risk: Last release in 2026 suggests potential stagnation. Monitor for security updates (though MIT license reduces legal risk).

Key Questions

1. Data Source Strategy:
   • Will holiday data be statically defined (e.g., in config/) or dynamically fetched (e.g., from a database/API)?
   • How will updates be managed (manual, automated, vendor-provided)?
2. Performance Requirements:
   • Are there throughput constraints (e.g., 10K+ holiday checks/sec)? If so, consider caching (e.g., Redis) or a lighter alternative.
3. Customization Needs:
   • Does the application require beyond-standard holidays (e.g., floating holidays, team-specific days)? If yes, assess Yasumi’s extensibility.
4. Testing Coverage:
   • Are there regression risks for edge cases (e.g., leap years, DST transitions)? Plan automated tests for holiday logic.
5. Alternatives:
   • Compare with Carbon + custom logic or Google’s Holiday API if Yasumi’s abstraction is overkill.

Integration Approach

Stack Fit

• PHP/Laravel Ecosystem: Native PHP package with zero Laravel dependencies, ensuring backward compatibility and minimal friction. Works with:
  • Laravel 8+: Leverage service providers for dependency injection.
  • Symfony: Compatible via Composer.
  • Legacy PHP: No framework required (pure PHP).
• Database Agnostic: No ORM or SQL dependencies, making it schema-agnostic.
• Tooling Compatibility:
  • Laravel Mix/Vite: No build step required.
  • Docker: Easy to containerize with PHP runtime.

Migration Path

1. Discovery Phase:
   • Audit existing holiday logic (e.g., custom functions, spreadsheets).
   • Map use cases to Yasumi’s features (e.g., Yasumi\Yasumi::load() for static data, Yasumi\Holiday::isHoliday() for checks).
2. Pilot Integration:
   • Replace a single module (e.g., leave balance calculator) with Yasumi.
   • Use feature flags to toggle between old/new logic during testing.
3. Full Rollout:
   • Migrate holiday configurations to Yasumi’s format (JSON/YAML).
   • Update date calculations (e.g., Carbon instances) to use Yasumi’s API.
   • Deprecate legacy holiday logic via deprecated methods or abstract classes.

Compatibility

• PHP Version: Supports PHP 8.0+ (check Laravel version compatibility).
• Dependency Conflicts: Minimal risk due to lightweight design. Verify with composer why-not or composer validate.
• Timezone Handling: Yasumi uses PHP’s DateTime, so ensure your app’s timezone settings (e.g., config/app.php) align with holiday definitions.
• Localization: If using multi-language apps, ensure holiday names/localized data align with UI requirements.

Sequencing

1. Configuration Setup:
   • Define holiday rules in config/holidays.php or external files.
   • Example:

     Yasumi::load('path/to/holidays.json');
     

2. API Integration:
   • Inject Yasumi into services via Laravel’s container:

     public function __construct(private Yasumi $yasumi) {}
     

   • Replace direct date checks (e.g., if ($date->isHoliday())) with:

     $this->yasumi->isHoliday($date, 'US');
     

3. Testing:
   • Write unit tests for holiday edge cases (e.g., weekends, custom exceptions).
   • Use PHPUnit or Pest to validate:

     public function test_holiday_detection() {
         $this->assertTrue(Yasumi::isHoliday('2023-12-25', 'US')); // Christmas
     }
     

4. Monitoring:
   • Log holiday calculation failures (e.g., invalid dates, missing regions).
   • Set up health checks for critical paths (e.g., payroll processing).

Operational Impact

Maintenance

• Holiday Data Updates:
  • Proactive: Schedule quarterly reviews to update holiday rules (e.g., new public holidays).
  • Automated: Use GitHub Actions or cron jobs to pull updates from a trusted source (e.g., government APIs).
  • Fallback: Maintain a backup of legacy logic during transitions.
• Configuration Drift:
  • Version-control holiday files (e.g., holidays/US.json) to track changes.
  • Use environment variables for dynamic overrides (e.g., APP_HOLIDAY_REGION).
• Dependency Updates:
  • Monitor for Yasumi updates (even if minor) via Dependabot or Laravel Forge.
  • Pin versions in composer.json if stability is critical.

Support

• Troubleshooting:
  • Common issues:
    • Invalid dates: Validate input with Yasumi::isValidDate().
    • Region mismatches: Ensure load() is called with the correct locale.
    • Performance: Profile with Xdebug if calculations are slow.
  • Debugging Tools:
    • Enable Yasumi’s verbose logging for holiday lookups.
    • Use dd(Yasumi::holidays()) to inspect loaded data.
• Documentation:
  • Create an internal runbook for:
    • Holiday data structure (e.g., JSON schema).
    • API usage patterns (e.g., caching strategies).
  • Link to upstream docs (e.g., Yasumi’s GitHub README).

Scaling

• Horizontal Scaling:
  • Yasumi is stateless, so it scales horizontally with Laravel’s queue workers or microservices.
  • For high-throughput apps, cache holiday data in Redis:

    $cacheKey = "holidays:US:{$date->format('Y-m-d')}";
    return Cache::remember($cacheKey, now()->addDay(), fn() => $this->yasumi->isHoliday($date, 'US'));
    

• Database Load:
  • No direct DB queries, but dynamic holiday data (e.g., fetched from a DB) may require indexing.
  • Example: If holidays are stored in holidays table, add:

    CREATE INDEX idx_holiday_date_region ON holidays(date, region);
    

• Cold Starts:
  • If using serverless (e.g., Laravel Vapor), pre-load holidays during bootstrap to avoid latency.

Failure Modes