Booking Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require comsa/booking-bundle
   

   Publish the bundle’s assets and configuration:

   php artisan vendor:publish --provider="Comsa\BookingBundle\BookingServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Comsa\BookingBundle\BookingServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="Comsa\BookingBundle\BookingServiceProvider" --tag="public"
   php artisan migrate
   

2. Service Provider & Routes Ensure the BookingServiceProvider is registered in config/app.php under providers. Add the bundle’s routes in routes/web.php:

   Route::prefix('admin')->middleware(['auth', 'admin'])->group(function () {
       require __DIR__.'/booking/routes.php';
   });
   

3. First Use Case: Basic Booking Create a model extending Comsa\BookingBundle\Model\Booking (e.g., App\Models\MyBooking):

   use Comsa\BookingBundle\Model\Booking;
   
   class MyBooking extends Booking
   {
       protected $table = 'my_bookings';
   }
   

   Define a booking type in config/booking.php:

   'types' => [
       'my_booking' => [
           'label' => 'My Booking',
           'model' => \App\Models\MyBooking::class,
           'fields' => [
               'title' => 'string',
               'start_at' => 'datetime',
               'end_at' => 'datetime',
           ],
       ],
   ],
   

4. Admin Panel Access Log in as an admin and navigate to /admin/bookings to manage bookings via the built-in admin panel.

Implementation Patterns

Core Workflows

1. Booking Creation & Management

• Programmatic Creation:

  use Comsa\BookingBundle\Services\BookingService;
  
  $booking = app(BookingService::class)->create('my_booking', [
      'title' => 'Team Offsite',
      'start_at' => now()->addDays(7),
      'end_at' => now()->addDays(10),
      'user_id' => auth()->id(),
  ]);
  

• Validation: Leverage the bundle’s built-in validation (e.g., end_at must be after start_at).

2. Customizing Booking Types

• Extend the Booking model or override fields in config/booking.php:

  'types' => [
      'custom_type' => [
          'fields' => [
              'custom_field' => [
                  'type' => 'string',
                  'label' => 'Custom Label',
                  'rules' => 'required|max:255',
              ],
          ],
      ],
  ],
  

• Use events to hook into lifecycle methods:

  // In EventServiceProvider
  public function boot()
  {
      Booking::created(function ($booking) {
          // Send notification, log, etc.
      });
  }
  

3. Admin Panel Customization

• Override Views: Publish and extend the admin panel templates:

  php artisan vendor:publish --tag="booking-views"
  

  Copy resources/views/vendor/booking/ to your project’s resources/views/booking/.
• Add Columns to Listings:

  // In a service provider
  Event::listen('booking.admin.list.columns', function ($columns) {
      $columns[] = ['label' => 'Custom Column', 'field' => 'custom_field'];
  });
  

4. API Integration

• Use the BookingService to fetch bookings for APIs:

  $bookings = app(BookingService::class)->all('my_booking', [
      'with' => ['user', 'events'],
      'filter' => ['start_at' => 'this_week'],
  ]);
  

• Expose endpoints via Laravel’s API resources:

  Route::apiResource('bookings', BookingApiController::class);
  

5. Recurring Bookings

• Configure recurring rules in config/booking.php:

  'types' => [
      'recurring' => [
          'recurrence_rule' => 'FREQ=WEEKLY;BYDAY=MO,WE',
      ],
  ],
  

• Generate instances programmatically:

  $recurringBooking = $booking->generateNextInstance();
  

Integration Tips

Database & Eloquent

• Use the bundle’s scopes for querying:

  $bookings = MyBooking::query()
      ->available()
      ->forUser(auth()->id())
      ->get();
  

• Polymorphic Relationships: Attach bookings to other models:

  class Event extends Model
  {
      public function bookings()
      {
          return $this->morphMany(MyBooking::class, 'bookable');
      }
  }
  

Frontend Integration

• JavaScript API: Use the bundle’s included JS for calendar integration:

  const calendar = new BookingCalendar('#calendar', {
      bookingType: 'my_booking',
      apiEndpoint: '/api/bookings',
  });
  

• Blade Directives: Display bookings in views:

  @booking('my_booking', $booking->id)
      <div class="booking-details">
          {{ $booking->title }}
      </div>
  @endbooking
  

Testing

• Use the BookingService in tests:

  public function test_booking_creation()
  {
      $booking = app(BookingService::class)->create('my_booking', [...]);
      $this->assertDatabaseHas('my_bookings', [...]);
  }
  

• Mock the admin panel for feature tests:

  $this->actingAs($admin)
       ->get('/admin/bookings')
       ->assertSee('My Booking');
  

Gotchas and Tips

Pitfalls

1. Configuration Overrides

   • Issue: Custom fields in config/booking.php may not reflect in the admin panel if the view cache isn’t cleared.
   • Fix: Run php artisan view:clear or php artisan config:clear.

2. Migration Conflicts

   • Issue: Publishing migrations might conflict with existing tables.
   • Fix: Manually merge migrations or use --force:

     php artisan migrate --force
     

3. Recurrence Rule Parsing

   • Issue: Invalid recurrence_rule formats (e.g., FREQ=DAILY;INTERVAL=2) may silently fail.
   • Fix: Validate rules using the RRule library:

     use Sabberworm\PHP-RRule\RRule;
     $rule = new RRule($booking->recurrence_rule);
     

4. Admin Middleware

   • Issue: Forgetting to add admin middleware to routes may expose the panel.
   • Fix: Always wrap admin routes:

     Route::middleware(['auth', 'admin'])->group(...);
     

5. Timezone Handling

   • Issue: Bookings may display incorrectly if the app’s timezone (config/app.php) doesn’t match the database’s.
   • Fix: Set consistent timezones:

     config(['app.timezone' => 'UTC']);
     

Debugging Tips

1. Log Events Enable booking-related logging in config/booking.php:

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

   Check logs at storage/logs/laravel.log.

2. Query Logging Enable Eloquent logging to debug queries:

   DB::enableQueryLog();
   $bookings = MyBooking::all();
   dd(DB::getQueryLog());
   

3. Admin Panel Debugging

   • Dump the admin panel’s data sources:

     Event::listen('booking.admin.list.data', function ($data) {
         dd($data);
     });
     

Extension Points

1. Custom Services Extend the BookingService by binding your own:

   $this->app->bind(BookingService::class, function ($app) {
       return new CustomBookingService($app->make('booking'));
   });
   

2. Webhooks Trigger actions via events:

   // In a listener
   public function handle(BookingCreated $event)
   {
       Http::post('https://your-webhook-url', $event->booking->toArray());
   }
   

3. Multi-Tenancy Scope bookings by tenant:

   class MyBooking extends Booking
   {
       public function scopeForTenant($query, $tenant)
       {
           return $query->where('tenant_id', $tenant->id);
       }
   }
   

4. Localization Override labels/translations:

   'labels' => [