Date Converter Laravel Package

Getting Started

Minimal Setup

1. Installation: Run composer require mr.incognito/date-converter in your Laravel project.
2. First Use Case: Convert today’s date to BS format:

   use MrIncognito\DateConverter\Facades\DateConverter;
   
   $bsDate = DateConverter::currentBsDate('Y-m-d'); // e.g., "2081-11-28"
   

3. Key Files:
   • config/date-converter.php (if published): Check for customizable settings like default formats.
   • app/Providers/AppServiceProvider.php: Verify facade binding (usually auto-registered).

Implementation Patterns

Core Workflows

1. Date Conversion:

   • AD → BS: Use fromAdToBs($adDate, $format) for explicit conversions.

     $bsDate = DateConverter::fromAdToBs('2025-03-12', 'Y-m-d'); // "2081-11-28"
     

   • BS → AD: Use fromBsToAd($bsDate, $format).

     $adDate = DateConverter::fromBsToAd('2081-11-28', 'Y-m-d'); // "2025-03-12"
     

   • Current Date: Use currentBsDate()/currentAdDate() for dynamic values.

2. Detailed Date Objects:

   • Fetch structured data (e.g., for UI/localization):

     $bsDetails = DateConverter::currentBsDateDetail();
     // Returns array with year, month, day, week_day (Nepali), month_name, etc.
     

3. Integration with Eloquent:

   • Accessors/Mutators: Add to models for automatic conversion:

     class Event extends Model {
         public function getBsDateAttribute() {
             return DateConverter::fromAdToBs($this->ad_date, 'Y-m-d');
         }
     }
     

   • Queries: Convert dates in scopes:

     public function scopeBsDateAfter($query, $date) {
         $adDate = DateConverter::fromBsToAd($date);
         return $query->where('ad_date', '>=', $adDate);
     }
     

4. Form Handling:

   • Validate and convert input dates:

     $validator = Validator::make($request->all(), [
         'bs_date' => 'required|date_format:Y-m-d',
     ]);
     $adDate = $validator->passes() ? DateConverter::fromBsToAd($request->bs_date) : null;
     

5. Localization:

   • Use month_name/week_day from *DateDetail() for Nepali labels in views:

     {{ DateConverter::currentBsDateDetail()['month_name'] }} {{ DateConverter::currentBsDateDetail()['year'] }}
     

Gotchas and Tips

Pitfalls

1. Date Format Strictness:

   • The package expects strict ISO-like formats (e.g., Y-m-d). Non-compliant formats (e.g., m/d/Y) may fail silently or return incorrect results.
   • Fix: Always validate input dates with DateTime::createFromFormat() before conversion.

2. Time Zone Sensitivity:

   • Conversions assume the server’s default time zone. Explicitly set date_default_timezone_set() if working across environments.
   • Tip: Use DateConverter::setTimeZone('Asia/Kathmandu') if available (check package docs for extension points).

3. Leap Year Quirks:

   • BS (Bikram Sambat) leap years differ from Gregorian. Edge cases (e.g., 2080-02-30 BS) may throw errors.
   • Debug: Log converted dates to verify:

     $bsDate = DateConverter::fromAdToBs('2023-02-28');
     logger($bsDate); // Should be "2079-11-15" (not 11-16)
     

4. Facade vs. Helper:

   • The package registers a facade (DateConverter), but may also expose static helpers. Prefer the facade for consistency and testability.

5. Database Storage:

   • Store AD dates in the DB (standard practice) and convert to BS only for display. Avoid storing BS dates directly to prevent sync issues.

Tips

1. Custom Formats:

   • Extend the package by publishing the config:

     php artisan vendor:publish --provider="MrIncognito\DateConverter\DateConverterServiceProvider"
     

   • Add default formats to config/date-converter.php:

     'defaults' => [
         'ad_format' => 'Y-m-d',
         'bs_format' => 'Y-m-d',
     ],
     

2. Testing:

   • Mock the facade in tests to avoid time-zone/date dependencies:

     $this->mock(DateConverter::class)->shouldReceive('currentBsDate')->andReturn('2081-11-28');
     

3. Performance:

   • Cache converted dates if used frequently (e.g., in loops):

     $cachedBsDate = Cache::remember('bs_today', now()->addDays(1), function() {
         return DateConverter::currentBsDate();
     });
     

4. Extending Functionality:

   • Add custom conversion logic by subclassing the core converter class (if the package allows it). Example:

     class CustomDateConverter extends \MrIncognito\DateConverter\DateConverter {
         public static function fromAdToBsWithEra($adDate) {
             $bsDate = parent::fromAdToBs($adDate);
             return "BS {$bsDate} (विसं)";
         }
     }
     

5. Fallback for Invalid Dates:

   • Handle exceptions gracefully:

     try {
         $bsDate = DateConverter::fromAdToBs('invalid-date');
     } catch (\Exception $e) {
         $bsDate = 'N/A';
     }
     

6. Documentation Gaps:

   • The package lacks examples for date ranges or arithmetic operations (e.g., adding days to BS dates). Implement these as utility methods if needed:

     function addBsDays($bsDate, $days) {
         $adDate = DateConverter::fromBsToAd($bsDate);
         $newAdDate = (new DateTime($adDate))->add(new DateInterval("P{$days}D"));
         return DateConverter::fromAdToBs($newAdDate->format('Y-m-d'));
     }