Drom Board Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require baks-dev/drom-board
   

   Ensure your project meets the PHP 8.4+ requirement and has baks-dev/core (≥7.4) installed.

2. Publish Config: Publish the default configuration to config/drom-board.php:

   php artisan vendor:publish --provider="BaksDev\DromBoard\DromBoardServiceProvider"
   

3. Basic Usage: Register the board in your Laravel routes (routes/web.php):

   Route::prefix('drom')->group(function () {
       \BaksDev\DromBoard\Routes\DromBoardRoutes::register();
   });
   

   This auto-loads the default CRUD endpoints for listings, categories, and user interactions.

4. First Integration: Use the facade to fetch listings in a Blade template:

   use BaksDev\DromBoard\Facades\DromBoard;
   
   $listings = DromBoard::listings()->paginate(10);
   

   Render with:

   @foreach($listings as $listing)
       <div>{{ $listing->title }} ({{ $listing->category->name }})</div>
   @endforeach
   

Implementation Patterns

Core Workflows

1. Listing Management:

   • Create/Update: Use the DromBoard::listing() builder to define rules and store listings:

     $listing = DromBoard::listing()
         ->setTitle('Laravel Job')
         ->setCategoryId(1)
         ->setPrice(5000)
         ->save();
     

   • Validation: Leverage built-in rules (e.g., required, numeric) or extend via events:

     DromBoard::extendValidation(function ($validator) {
         $validator->addRule('custom', function ($attribute, $value) {
             return strlen($value) > 10;
         });
     });
     

2. Category Hierarchy:

   • Define categories recursively in config/drom-board.php:

     'categories' => [
         1 => ['name' => 'Jobs', 'parent_id' => null],
         2 => ['name' => 'Freelance', 'parent_id' => 1],
     ],
     

   • Fetch nested categories:

     $categories = DromBoard::categories()->with('children')->get();
     

3. Search & Filtering:

   • Use query scopes:

     $results = DromBoard::listings()
         ->where('title', 'like', '%Laravel%')
         ->where('price', '<', 10000)
         ->orderBy('created_at', 'desc')
         ->get();
     

   • Add custom filters via service providers:

     DromBoard::extendQuery(function ($query, $request) {
         if ($request->has('region')) {
             $query->where('region_id', $request->region);
         }
     });
     

4. User Interactions:

   • Handle favorites, reports, or messages via events:

     DromBoard::on('listing.favorited', function ($listing, $user) {
         // Log or notify
     });
     

Integration Tips

• API Endpoints: Use DromBoard::apiRoutes() for JSON responses:

  Route::prefix('api/drom')->group(function () {
      \BaksDev\DromBoard\Routes\DromBoardApiRoutes::register();
  });
  

• Blade Components: Include pre-built components:

  @component('drom-board::listing-card', ['listing' => $listing])
  @endcomponent
  

• Testing: Use the test group:

  php artisan test --group=drom-board
  

  Mock dependencies with:

  $this->partialMock(DromBoard::class, ['fetchCategories']);
  

Gotchas and Tips

Pitfalls

1. PHP Version Mismatch:

   • The package requires PHP 8.4+. Downgrading will break dependency resolution.
   • Fix: Update your project or use a compatibility layer like laravel-shift/laravel-shift.

2. Missing Core Dependency:

   • baks-dev/core (≥7.4) is mandatory. If omitted, the package throws ClassNotFoundException.
   • Fix: Run composer require baks-dev/core:^7.4 before installing drom-board.

3. Route Conflicts:

   • Default routes (/drom/listings, /drom/categories) may clash with existing routes.
   • Fix: Override the route prefix in config:

     'routes' => [
         'prefix' => 'marketplace',
     ],
     

4. Translation Strings:

   • The package uses drom-board:: namespace for translations. Missing keys will show raw strings.
   • Fix: Publish translations:

     php artisan vendor:publish --tag=drom-board-translations
     

5. Database Schema:

   • The package assumes tables like drom_listings, drom_categories, and drom_user_interactions exist.
   • Fix: Run migrations manually or extend the DromBoardServiceProvider:

     public function boot()
     {
         $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
     }
     

Debugging

• Query Logs: Enable Laravel’s query logging to inspect Eloquent queries:

  DB::enableQueryLog();
  $listings = DromBoard::listings()->get();
  dd(DB::getQueryLog());
  

• Event Debugging: Listen for events in AppServiceProvider@boot():

  DromBoard::on('*', function ($event) {
      \Log::debug("DromBoard event: {$event->getName()}", $event->getData());
  });
  

Extension Points

1. Custom Fields: Add fields to listings via model events:

   DromBoard::extendListingModel(function ($model) {
       $model->addFillable(['custom_field']);
   });
   

2. Payment Integration: Hook into the listing.paid event to sync with Stripe/PayPal:

   DromBoard::on('listing.paid', function ($listing, $user, $amount) {
       // Process payment
   });
   

3. SEO Meta Tags: Override the ListingResource to add OpenGraph tags:

   DromBoard::extendResource('listing', function ($resource) {
       $resource->meta = function () {
           return [
               'og:title' => $this->title,
               'og:description' => $this->description,
           ];
       };
   });
   

4. Localization: Extend translation keys dynamically:

   DromBoard::extendTranslations(function ($translator) {
       $translator->set('drom-board::listing.status.pending', 'Pending Review');
   });
   

Performance Tips

• Caching Categories: Cache the category tree for 1 hour:

  $categories = Cache::remember('drom.categories', 3600, function () {
      return DromBoard::categories()->with('children')->get();
  });
  

• Lazy-Loading Images: Use Laravel’s Storage facade to optimize image paths:

  $listing->image_url = Storage::url($listing->image_path);
  

• Pagination: Use cursor pagination for large datasets:

  $listings = DromBoard::listings()->cursorPaginate(20);