Symfonyjdate Laravel Package

Getting Started

1. Install and pin. composer require symfony_persia/symfonyjdate in a Symfony 2.x project, but commit the exact version and check composer.lock. The last release is March 2015 — treat it as a fixed dependency, not something you'll get patches for.
2. Register the bundle. In app/AppKernel.php, add the bundle to $bundles (the class name follows the SymfonyJDate naming — confirm against SymfonyJDateBundle.php at the repo root). There is no Flex recipe, no autowiring, and no services.yaml; this is the old Resources/config/services.yml style.
3. Find the moving parts first. Open, in order: README.md, *Bundle.php, Resources/config/services.yml (gives you the service id), DependencyInjection/, and any Twig/ or Form/ directory. Those three files tell you whether you get a Twig filter, a form type, a service, or just a static utility class. Don't guess the API from the README alone — 2015-era READMEs are usually out of sync with the code.
4. First use case. The realistic day-one use is: you have a DateTime stored in Gregorian (which you should keep doing) and you want to render it as Shamsi. Wire it up once in a controller or a Twig template and verify the output against a known pair, e.g. 2015-03-21 → 1394/01/01. If that one conversion is correct, the rest of the library is usually fine.
5. Check your PHP platform. The "> 2038" selling point only holds on 64-bit PHP with DateTime/DateTimeImmutable. Run php -r 'echo PHP_INT_SIZE;' — if it prints 4, the whole reason to pick this package evaporates.

Implementation Patterns

• Keep Gregorian in the database, convert at the edges. Store DATETIME/TIMESTAMP (or UTC ISO strings) as usual and only convert for display and form input. This keeps your queries, sorting, and comparisons sane and makes it trivial to swap the library out later.
• Wrap it in one adapter service. Create AppBundle\Dates\JalaliConverter that injects the bundle service (or calls the static helper) and exposes exactly two methods: toJalali(DateTimeInterface $dt, string $format): string and fromJalali(string $s): DateTime. Every call site goes through this class. Given the package is unmaintained, this is the single most valuable thing you can do — it makes replacement a one-file change.
• Twig display filter. If the bundle ships a Twig extension, register/verify it and use it for read-only rendering: {{ invoice.createdAt|jdate('Y/m/d H:i') }}. If it doesn't, add your own extension that delegates to the adapter — 15 lines and you control the filter name and defaults.
• Form input via a data transformer. Users type 1394/12/29; the entity expects a DateTime. Implement a DataTransformerInterface on top of fromJalali() / toJalali() and attach it to a normal DateType with a 'widget' => 'single_text' and a dd/MM/yyyy-style format. This is cleaner than trying to bend the bundle's own form type, which is likely tied to Symfony 2 form internals.
• Long-range dates are the actual differentiator. Use it for contract maturities, retirement dates, warranty end dates, or anything that can plausibly exceed 2038. The value here is not Jalali conversion per se (plenty of libs do that) but doing it without 32-bit timestamp overflow.
• Import path. When ingesting CSVs or legacy dumps with Shamsi strings, funnel them through fromJalali() and reject anything that doesn't round-trip: convert back and compare strings. Cheap validation that catches malformed input and off-by-one leap-year bugs in one shot.
• Testing pattern. Maintain a small fixture table of known Gregorian/Jalali pairs — at minimum one date in each of the 12 months, plus 1394/12/29, 1395/12/30, and a far-future date like 1450/01/01 — and assert both directions in a unit test. This is your regression net against PHP version changes and accidental library swaps.

Gotchas and Tips

• It is abandoned and Symfony 2-only. No Symfony 3/4/5/6/7 support, no PSR-4 guarantee, no maintained autoload config, no security patches. Do not introduce it into a new project; if you must keep it, budget for a fork or migration.
• The >2038 claim is platform-dependent. It depends on 64-bit PHP and on the library consistently using DateTime rather than falling back to date()/mktime() internally. Grep the source for mktime, date(, and strtotime before trusting it with post-2038 dates.
• Leap-year and year-boundary bugs. Persian leap years are computed, not tabular in the obvious way; the 29/30 Esfand boundary is where these libraries historically break. Always test the last day of Esfand for 1394, 1395, and 1399 and the first day of Farvardin on both sides.
• Timezone and DST shifts. Convert with an explicit timezone, and do the Gregorian→Jalali conversion after normalizing to the display timezone. A date stored at 23:30 UTC becomes the next day in Asia/Tehran, and a conversion done in the wrong order will silently show the wrong day.
• Static helpers are tempting and painful. If the API is static (JDate::...), you cannot inject or mock it. That's another reason to keep the adapter wrapper — it's the only seam you'll have.
• Twig filter name collisions. If you also load another Jalali/jDate library (common in Iranian projects), both may register jdate or jalali. Check getFilters() and rename yours if needed.
• No composer.json constraints to lean on. Old bundles often declare symfony/symfony: ~2.x loosely or not at all, so Composer may happily install it alongside incompatible packages. Add an explicit conflict or platform constraint in your root composer.json.
• Extension points are limited to replacement, not extension. There's no event system or interface worth implementing. The practical escape hatches are: (a) your adapter class, (b) your own Twig extension, (c) your own form data transformer. Treat the bundle's own Twig/Form integrations as optional conveniences you can drop.
• Migration target worth knowing. For display-only formatting you can often skip a library entirely: PHP's intl extension supports the Persian calendar natively via IntlDateFormatter with locale fa_IR@calendar=persian, and it handles far-future years on 64-bit builds. For parsing/arithmetic, a maintained Jalali date library is the safer long-term bet. Either way, the adapter wrapper from the patterns section makes that migration a same-day change rather than a refactor.