Jalali Date Time Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Specific: The bundle is tightly coupled to Symfony’s architecture (e.g., AppKernel, service container), making it only viable for Symfony applications. For non-Symfony PHP projects, this would require significant refactoring or a custom wrapper.
• Jalali DateTime Focus: Aligns well with applications requiring Persian (Jalali) calendar support (e.g., Iran-based systems, Farsi-language apps, or compliance with local regulations).
• Limited Abstraction: The bundle does not abstract date-time logic beyond Symfony’s ecosystem, which could complicate future migrations to non-Symfony frameworks.

Integration Feasibility

• Low Barrier for Symfony: Installation and basic usage are straightforward (Composer + AppKernel registration). However, Symfony 5.4+ may require adjustments due to deprecated AppKernel in favor of Kernel.
• Form Integration: Requires dependency on bootstrap-persian-datetimepicker, adding frontend complexity (JavaScript/CSS) and potential versioning risks.
• Database/ORM Considerations: No built-in support for Doctrine ORM or database schema migrations for Jalali dates, requiring manual handling (e.g., storing Unix timestamps + conversion logic).

Technical Risk

• Stale Maintenance: Last release in 2020 raises concerns about:
  • Compatibility with modern Symfony (6.x/7.x).
  • Security patches (though BSD-3-Clause is permissive).
  • Deprecated Symfony APIs (e.g., get() container access).
• Testing Gaps: No visible tests or CI/CD in the repo, increasing risk of edge-case failures.
• Timezone Handling: The bundle supports timezones, but edge cases (e.g., daylight saving transitions) may need manual validation.
• Performance: No benchmarks; repeated conversions between Gregorian/Jalali could impact latency in high-throughput apps.

Key Questions

1. Symfony Version Compatibility:
   • Does the bundle work with Symfony 6.x/7.x? If not, what’s the migration effort?
   • Are there plans for updates, or should we fork/maintain it?
2. Database Strategy:
   • How will Jalali dates be stored? (Unix timestamps? Dual columns? Custom types?)
   • Does the team need Doctrine DBAL types or QueryBuilder support?
3. Frontend Dependencies:
   • Is bootstrap-persian-datetimepicker acceptable, or should we evaluate alternatives (e.g., custom Vue/React components)?
4. Testing:
   • Are there plans to add unit/integration tests for critical paths (e.g., timezone conversions)?
5. Fallbacks:
   • How will the system handle invalid Jalali dates (e.g., February 30)?
   • Are there graceful degradation paths for unsupported environments?

Integration Approach

Stack Fit

• Symfony Ecosystem: Ideal for Symfony-based apps needing Persian calendar support. Poor fit for:
  • Non-Symfony PHP (Laravel, Slim, etc.).
  • Headless APIs or microservices without a Symfony frontend.
• Frontend Stack:
  • Requires Bootstrap + JavaScript for form inputs. Conflicts with modern SPAs (React/Vue) unless wrapped in a custom component.
  • Consider API-first design: Expose Jalali conversions via a separate service layer to decouple frontend/backend.

Migration Path

1. Symfony 5.x/6.x Adaptation:
   • Replace AppKernel registration with config/bundles.php (Symfony 5+).
   • Replace $this->container->get() with dependency injection (constructor injection).
   • Example:

     use Borsaco\JalaliDateTimeBundle\Service\JalaliDateTime;
     class MyService {
         public function __construct(private JalaliDateTime $jalaliDateTime) {}
     }
     

2. Database Layer:
   • Option A: Store Unix timestamps + convert on read/write.
   • Option B: Use Doctrine extensions (e.g., gedmo/doctrine-extensions) for custom types.
   • Option C: Add a migration to backfill existing data.
3. Frontend Integration:
   • For Symfony forms: Replace DateType with JalaliDateType + bootstrap-persian-datetimepicker.
   • For SPAs: Create a custom API endpoint to return Jalali-formatted dates.

Compatibility

• Symfony Versions:
  • Test against Symfony 5.4–6.4 (latest LTS). Avoid 7.x until confirmed.
• PHP Versions:
  • Bundle targets PHP 7.2+ (check composer.json). Ensure alignment with your stack.
• Dependencies:
  • bootstrap-persian-datetimepicker may require jQuery or Bootstrap 4/5. Audit conflicts.

Sequencing

1. Phase 1: Core Integration
   • Install bundle + update bundles.php.
   • Replace hardcoded dates in services with JalaliDateTime.
   • Test basic conversions (Gregorian ↔ Jalali).
2. Phase 2: Database Layer
   • Design storage strategy (timestamps vs. custom types).
   • Write migrations if backfilling data.
3. Phase 3: Frontend
   • Integrate JalaliDateType + bootstrap-persian-datetimepicker.
   • Or build a custom API wrapper for SPAs.
4. Phase 4: Validation
   • Edge cases: Invalid dates, timezones, DST transitions.
   • Performance testing for high-traffic endpoints.

Operational Impact

Maintenance

• Bundle Risks:
  • No active maintenance: Fork the repo or assign a team member to triage issues.
  • Symfony Updates: Monitor for breaking changes (e.g., service container deprecations).
• Dependency Risks:
  • bootstrap-persian-datetimepicker may stagnate. Consider vendor-locking or forking.
• Documentation:
  • Internal docs needed for:
    • Date storage strategies.
    • Frontend integration quirks.
    • Debugging Jalali ↔ Gregorian mismatches.

Support

• Debugging Challenges:
  • Timezone bugs may be hard to reproduce (e.g., Tehran vs. UTC offsets).
  • Frontend JS errors could obscure backend issues.
• User Training:
  • Developers must understand:
    • When to use JalaliDateTime vs. native DateTime.
    • How to handle date inputs/outputs consistently.
• Fallback Plan:
  • Maintain a Gregorian fallback mode for unsupported environments.

Scaling

• Performance:
  • Conversion overhead: If converting dates on every request, cache frequently used timestamps.
  • Database: Avoid storing redundant Jalali/Gregorian columns; normalize to one format.
• Distributed Systems:
  • Ensure timezone consistency across microservices (e.g., use UTC internally).
  • Document clock skew risks in multi-region deployments.

Failure Modes

Ramp-Up

• Onboarding Time:
  • Developers: 1–2 days to integrate core bundle; 3–5 days for full frontend/database sync.
  • QA: 1 week for edge-case testing (timezones, invalid dates).
• Key Learning Curves:
  • Understanding Jalali calendar rules (e.g., variable month lengths).
  • Debugging Symfony service container issues if migrating from get() to DI.
• Recommended Roles:
  • Backend: TPM + 1 backend engineer (for Symfony/DI).
  • Frontend: 1 developer (for bootstrap-persian-datetimepicker or custom UI).
  • DevOps: 1 engineer (for database migrations/caching).