Jalali Laravel Package

Technical Evaluation

Architecture Fit

• Core Use Case Alignment: Remains unchanged—morilog/jalali v3.5.0 is still a lightweight utility for Jalali date/time handling, ideal for Laravel apps targeting Persian-speaking regions. No architectural conflicts introduced.
• Laravel Compatibility: Continues to integrate seamlessly with Carbon and Eloquent, though the new release’s explicit nullable type hints (e.g., DateTimeZone parameters) align better with PHP 8.1+ strict typing, reducing potential runtime warnings.
• Isolation: Still stateless and dependency-light, with no breaking changes to the package’s core functionality.

Integration Feasibility

• Improved Type Safety: The fixes for explicit nullable parameters (PR #188, #200) reduce risk of TypeError in strict PHP environments, making integration smoother in Laravel’s typed contexts (e.g., dependency injection, method signatures).
• Carbon Synergy: No changes to the API surface, so existing Carbon macro integrations remain valid. The package still mirrors Carbon’s API where possible.
• Database Layer: Unchanged—custom casting for Eloquent remains necessary for Jalali ↔ Gregorian conversions.

Technical Risk

• Reduced Type-Related Bugs: The nullable parameter fixes mitigate PHP 8.1+ strict mode issues, but timezone ambiguity and date logic complexity risks persist (see original assessment).
• Minimal Breaking Changes: The release is backward-compatible, but the explicit nullability may expose latent type issues in existing codebases using loose type hints.
• Testing Gaps: While the README was updated (PR #191), no new features or breaking changes were introduced, so edge-case testing (e.g., invalid dates, timezones) remains critical.

Key Questions

1. Type Safety Impact:
   • Does your Laravel app use PHP 8.1+ strict typing? If so, audit existing Jalali usage for implicit null assumptions that may now trigger warnings/errors.
2. Testing Coverage:
   • Have the nullable parameter fixes been regression-tested with Carbon/Eloquent integrations?
   • Are there new test cases for DateTimeZone-related edge cases (e.g., null timezones, invalid offsets)?
3. Documentation:
   • Does the updated README clarify timezone handling or nullable parameter usage for Laravel developers?
4. Performance:
   • Could the explicit null checks introduce micro-optimization overhead? Benchmark if critical.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Carbon Integration: Leverage Carbon::macro() to alias Jalali methods (unchanged). The nullable fixes may simplify type hints in custom macros.
  • Eloquent: Continue using accessors/mutators or global scopes for conversions. The fixes reduce risk of TypeError in custom casting logic.
  • Blade: Custom directives (e.g., @jalali) remain unaffected.
• Database:
  • No changes to storage strategy. Still recommend Gregorian storage with presentation-layer conversion.

Migration Path

1. Phase 0: Pre-Integration Audit (NEW)
   • Scan codebase for loose type hints (e.g., DateTimeZone $tz without ?) that may now fail in PHP 8.1+.
   • Use phpstan or psalm to detect potential issues.
2. Phase 1: Proof of Concept (Unchanged)
   • Test parsing/formatting with strict typing enabled.
3. Phase 2–4 (Unchanged)
   • Proceed with selective integration, Carbon macros, Eloquent casting, and optional DB sync.

Compatibility

• PHP Version: Now explicitly supports PHP 8.1+ strict typing without warnings. Test with Laravel’s PHP 8.2+ support.
• Carbon Version: No changes—still compatible with Laravel’s bundled Carbon (v2.x+).
• Dependencies: Unchanged—zero conflict risk.

Sequencing (Updated)

Operational Impact

Maintenance

• Proactive Monitoring:
  • Add PHPStan/Psalm rules to catch nullable parameter misuse (e.g., @param DateTimeZone|null $tz).
  • Monitor for new TypeError in logs post-upgrade.
• Dependency Updates:
  • The package is now more type-safe, reducing maintenance burden for PHP 8.1+ apps.
  • Consider vendoring if long-term stability is critical (unchanged).

Support

• Documentation Gaps:
  • The README update (PR #191) may clarify usage, but Laravel-specific guidance (e.g., Eloquent, timezones) is still lacking.
  • Internal docs should now include:
    • Examples of strictly typed Carbon/Jalali integration.
    • Debugging nullable parameter issues (e.g., Argument 1 passed to Jalali::parse() must be null|string).
• Community Support:
  • Unchanged—GitHub issues remain moderated. Contributor growth (2 new PRs) is positive but niche.

Scaling

• Performance:
  • Nullable checks may add minimal overhead (benchmarks recommended for high-throughput apps).
  • Caching strategies (e.g., timezone offsets) remain valid.
• Database:
  • Unchanged—hybrid storage risks and indexing needs persist.

Failure Modes (Updated)

Ramp-Up

• Developer Onboarding:
  • Updated Cheat Sheet: Include strict typing examples (e.g., Jalali::parse(string|null $date)).
  • Pair Programming: Demo debugging nullable parameter issues.
• Testing Strategy:
  • Property-Based Tests: Add tests for null inputs in DateTimeZone parameters.
  • Snapshot Testing: Capture outputs for edge cases (e.g., null timezone).
• Training:
  • Workshop: Cover PHP 8.1+ strict mode implications for Jalali usage.
  • Code Reviews: Enforce nullable parameter validation in PRs.