Verta Laravel Package

Technical Evaluation

Architecture Fit

• Strong Alignment with Laravel Ecosystem: The package is designed for Laravel, leveraging Carbon’s API while adding Jalali-specific functionality. This ensures minimal disruption to existing date/time logic (e.g., now(), Carbon instances).
• Domain-Specific Value: Addresses critical gaps in Laravel for Persian-speaking markets, including:
  • Date Validation: Built-in rules like jdate_valid or jdate_before_equal for form handling.
  • Localization: Persian/Arabic month/day names and formatting (e.g., formatWord()).
  • Business Logic: Methods like isLeapYear(), diffMonths(), and addWeeks() tailored for Jalali calendars.
• Extensibility: Supports custom formats, time modifications, and boundary calculations (e.g., week start days), making it adaptable to niche use cases (e.g., fiscal year calculations).
• Carbon Synergy: The bidirectional conversion (toCarbon()/toJalali()) allows gradual adoption—teams can migrate features incrementally without rewriting date logic.

Integration Feasibility

• Seamless Composer Integration: Single-line install (composer require hekmatinasser/verta) with auto-registration via Laravel’s service provider.
• Minimal Configuration: Defaults work out-of-the-box; customization (e.g., locale, Carbon integration) is optional.
• Backward Compatibility: Supports Laravel 8–12 with versioned releases, ensuring stability. No breaking changes in recent updates (e.g., v8.x).
• Database Agnostic: While the package doesn’t handle storage, it pairs well with:
  • Eloquent Casts: Store Jalali dates as Gregorian strings (e.g., protected $casts = ['birthday' => 'date:Y-m-d'];).
  • Mutators/Accessors: Convert between formats on-the-fly (e.g., getJalaliBirthdayAttribute()).
• Testing Support: Includes unit tests, but TPM should validate:
  • Edge cases (e.g., Jalali leap years like ۱۳۹۶/۱۴۰۴).
  • Timezone interactions (if applicable).

Technical Risk

• Timezone Limitations:
  • Risk: Jalali dates ignore timezones by default, which could cause issues in apps relying on Carbon’s timezone-aware logic.
  • Mitigation: Document timezone expectations (e.g., "assume Tehran time") and use Carbon for timezone-sensitive operations.
• Carbon Version Conflicts:
  • Risk: If the app uses an older Carbon version, compatibility may break.
  • Mitigation: Pin Carbon to a supported version (e.g., ^2.65) in composer.json.
• Localization Gaps:
  • Risk: Custom date formats (e.g., fiscal years) may require extensions.
  • Mitigation: Plan for custom formatters or fork the package if needed.
• Performance Overhead:
  • Risk: Bulk date operations (e.g., parsing 10K records) could slow down.
  • Mitigation: Benchmark with production-scale data if applicable.
• Database Schema Impact:
  • Risk: Storing Jalali dates as strings may complicate queries.
  • Mitigation: Use Gregorian storage with accessors or a dedicated jalali column type (e.g., via Laravel extensions).

Key Questions for the TPM

1. Regional Requirements:
   • Are Jalali dates mandatory for legal/compliance reasons (e.g., contracts, tax filings)?
   • Are there additional localization needs (e.g., Urdu, Kurdish) beyond Persian/Arabic?
2. Data Storage Strategy:
   • Should Jalali dates be stored as Gregorian strings (simpler queries) or native Jalali (consistency)?
   • Will the app need timezone-aware Jalali dates (e.g., "1401-05-24 14:00 in Tehran")?
3. Migration Path:
   • Which features will prioritize Jalali support (e.g., forms, reports, APIs)?
   • How will legacy Carbon code transition to verta() (e.g., search/replace, wrapper classes)?
4. Testing Scope:
   • Should leap years, negative dates, and boundary conditions (e.g., week start days) be tested?
   • Are there third-party integrations (e.g., payment gateways, APIs) that expect Gregorian dates?
5. Long-Term Maintenance:
   • Will the team contribute to Verta (e.g., custom formats, bug fixes) or rely on upstream updates?
   • Are there alternatives (e.g., spatie/calendar) for broader calendar support if needed?

Integration Approach

Stack Fit

• Laravel-Centric: Designed for Laravel’s Carbon-based ecosystem, with zero framework conflicts.
• PHP 8+ Compatible: Works with modern PHP features (e.g., named arguments, attributes).
• Composer-Friendly: No global overrides; isolated to the app’s vendor directory.
• Tooling Integration:
  • Laravel Mix/Webpack: Can extend date formatting for frontend templates (e.g., Vue/React).
  • Artisan Commands: Supports custom date parsing in CLI tools.
  • Queues/Jobs: Safe for delayed jobs (e.g., scheduled Jalali reminders).

Migration Path

1. Phase 1: Pilot Feature

   • Scope: Start with a non-critical feature (e.g., Persian-language blog, internal reporting).
   • Actions:
     • Install Verta (composer require hekmatinasser/verta).
     • Replace Carbon with verta() in date-heavy methods (e.g., now()->toJalali()).
     • Update validation rules (e.g., 'date' => 'jdate_valid').
   • Validation: Test edge cases (e.g., leap years, negative dates).

2. Phase 2: Core Integration

   • Scope: Expand to user-facing forms, APIs, and database interactions.
   • Actions:
     • Add Eloquent accessors/mutators for Jalali fields.
     • Configure default locale (e.g., Verta::setLocale('fa')).
     • Update frontend templates to use Jalali formats (e.g., {{ verta()->formatJalaliDatetime() }}).
   • Validation: Load-test with high-volume date operations.

3. Phase 3: Full Rollout

   • Scope: Replace all Carbon instances with Verta where Jalali support is needed.
   • Actions:
     • Refactor legacy date logic (e.g., Carbon::parse() → Verta::parse()).
     • Update third-party libraries (if they use Carbon internally).
     • Document dual-mode usage (e.g., "Use verta() for Jalali, Carbon for Gregorian").

Compatibility

• Carbon: Fully compatible; all Carbon methods work on Verta instances (e.g., addDays(), diffInMonths()).
• Laravel Validation: Built-in rules like jdate_valid, jdate_after, and jdate_before_equal.
• Localization: Supports Persian/Arabic out-of-the-box; extendable for other languages.
• Database: Works with any storage backend (MySQL, PostgreSQL, etc.) via string conversion.
• Testing: Integrates with PHPUnit and Laravel’s testing helpers (e.g., refreshDatabase()).

Sequencing