Business Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require florianv/business
   

   Add to config/app.php under providers:

   FlorianV\Business\BusinessServiceProvider::class,
   

2. Basic Configuration Publish the config file:

   php artisan vendor:publish --provider="FlorianV\Business\BusinessServiceProvider"
   

   Edit config/business.php to define your business hours (e.g., 9:00-17:00 Mon-Fri).

3. First Use Case Calculate the next business day from a given date:

   use FlorianV\Business\Facades\Business;
   
   $nextBusinessDay = Business::nextBusinessDay(now());
   

Implementation Patterns

Core Workflows

1. Business Hour Calculations

   • Add Business Hours:

     $newDate = Business::addHours(now(), 5); // Adds 5 business hours
     

   • Subtract Business Hours:

     $oldDate = Business::subtractHours(now(), 3);
     

2. Date Manipulation

   • Next/Previous Business Day:

     $next = Business::nextBusinessDay(now());
     $prev = Business::previousBusinessDay(now());
     

   • Business Days Between Dates:

     $days = Business::businessDaysBetween(now(), now()->addDays(10));
     

3. Holiday Handling

   • Define holidays in config/business.php:

     'holidays' => [
         '2023-12-25', // Christmas
         '2024-01-01', // New Year
     ],
     

   • Automatically excluded from calculations.

4. Time Zone Awareness

   • Set default timezone in config/business.php:

     'timezone' => 'America/New_York',
     

   • Override per calculation:

     Business::setTimezone('Europe/London')->nextBusinessDay(now());
     

5. Custom Business Rules

   • Extend with custom logic via service provider:

     Business::extend(function ($business) {
         $business->isBusinessHour = function (Carbon $date) {
             // Custom logic (e.g., exclude weekends + specific hours)
             return $date->isWeekday() && $date->hour >= 10 && $date->hour < 18;
         };
     });
     

Gotchas and Tips

Common Pitfalls

1. Time Zone Mismatches

   • Ensure config/business.php timezone matches your application’s default or the input Carbon instance.
   • Debug with:

     Business::setTimezone('UTC')->nextBusinessDay(now());
     

2. Holiday Overrides

   • Holidays defined in the config override business hours. Test edge cases like holidays falling on weekends:

     // Saturday holiday (should still skip)
     Business::nextBusinessDay(Carbon::parse('2023-12-23')); // Skips to Monday
     

3. Recurring Holidays

   • The package doesn’t natively support recurring holidays (e.g., "every 4th Thursday of November").
   • Workaround: Use a package like spatie/calendar to generate holidays dynamically and merge them into config/business.php.

4. Edge Cases in addHours/subtractHours

   • Adding/subtracting hours across business day boundaries may yield unexpected results:

     // Adding 10 hours at 5 PM (business hours end at 5 PM)
     Business::addHours(Carbon::parse('2023-01-01 17:00'), 10);
     // Result: 2023-01-02 09:00 (next business day)
     

   • Tip: Use addBusinessDays() for day-level adjustments instead.

5. Carbon Instance Mutability

   • Methods like addHours() mutate the Carbon instance by default. Use copy() to avoid side effects:

     $original = now();
     $adjusted = Business::addHours($original->copy(), 2);
     

Debugging Tips

1. Inspect Business Rules

   dd(Business::getBusinessRules()); // Shows parsed config
   

2. Check Business Day Status

   if (Business::isBusinessDay(now())) {
       // Logic for business days
   }
   

3. Log Calculations Enable debug mode in config/business.php:

   'debug' => env('APP_DEBUG', false),
   

   Logs will appear in Laravel’s log channel.

Extension Points

1. Custom Business Day Logic Override the isBusinessDay method in your service provider:

   Business::extend(function ($business) {
       $business->isBusinessDay = function (Carbon $date) {
           return parent::isBusinessDay($date) && $date->day === 15; // Only on the 15th
       };
   });
   

2. Dynamic Config Loading Load business hours from a database or API:

   $hours = Cache::remember('business_hours', now()->addHours(1), function () {
       return DB::table('business_hours')->first();
   });
   Business::setHours($hours['open'], $hours['close']);
   

3. Testing Use Business::fake() to mock business hours in tests:

   Business::fake()
       ->businessHours('00:00', '23:59') // 24/7 for tests
       ->holidays([]);
   
   // Test logic here
   Business::shouldReceive('nextBusinessDay')->andReturn(now()->addDay());