Laravel Help Center Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require algowrite/laravel-help-center
   php artisan vendor:publish --provider="Algowrite\HelpCenter\HelpCenterServiceProvider"
   php artisan migrate
   

   • Publishes migrations, config, and views to config/help-center.php and resources/views/vendor/help-center/.

2. Configuration

   • Update config/help-center.php with your preferred:
     • categories (default: ['General', 'Technical', 'Billing'])
     • per_page (default: 10)
     • enable_comments (default: true)
     • moderation_required (default: false)

3. First Use Case: Displaying Help Articles

   • Add a route in routes/web.php:

     use Algowrite\HelpCenter\Facades\HelpCenter;
     
     Route::get('/help', [HelpCenter::class, 'index']);
     

   • Seed initial articles (optional):

     php artisan help-center:seed
     

Implementation Patterns

Core Workflows

1. Managing Articles

   • CRUD via Facade:

     // Create
     HelpCenter::create(['title' => 'FAQ', 'content' => '...', 'category' => 'General']);
     
     // Update
     $article = HelpCenter::find(1);
     $article->update(['content' => 'Updated...']);
     
     // Delete
     HelpCenter::destroy(1);
     

   • Mass Actions:

     HelpCenter::where('category', 'Technical')->update(['is_published' => true]);
     

2. Displaying Data

   • Blade Integration:

     @foreach(HelpCenter::published()->latest()->paginate(5) as $article)
         <h3>{{ $article->title }}</h3>
         <p>{{ Str::limit($article->content, 100) }}</p>
     @endforeach
     

   • API Endpoints (if using api routes):

     Route::apiResource('help-articles', \Algowrite\HelpCenter\Http\Controllers\HelpArticleController::class);
     

3. Comments System

   • Enable in config (enable_comments: true).
   • Use the hasMany relationship:

     $article = HelpCenter::find(1);
     $comments = $article->comments; // Polymorphic relationship
     

4. Search Functionality

   • Use Laravel Scout (if configured):

     HelpCenter::search('laravel')->get();
     

   • Fallback to query builder:

     HelpCenter::where('content', 'like', '%laravel%')->get();
     

Integration Tips

• Authentication: Restrict article creation/editing to admins:

  Route::middleware(['auth', 'admin'])->group(function () {
      Route::resource('admin/articles', \Algowrite\HelpCenter\Http\Controllers\Admin\HelpArticleController::class);
  });
  

• Localization: Override views in resources/views/vendor/help-center/ and translate strings via Laravel’s localization.
• Frontend Frameworks: Use the facade in Vue/React via Inertia.js or fetch data via API routes.

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If you modify the articles table manually, reset migrations:

     php artisan migrate:fresh --seed
     

   • Tip: Use php artisan help-center:seed to repopulate data after resets.

2. Polymorphic Comments

   • Comments are tied to commentable (articles, FAQs, etc.). Ensure your models use:

     public function comments()
     {
         return $this->morphMany(\Algowrite\HelpCenter\Models\Comment::class, 'commentable');
     }
     

   • Gotcha: Forgetting to add the commentable_id and commentable_type columns to the comments table will break polymorphic relationships.

3. Caching Headaches

   • Scout or simple cache may interfere with real-time updates. Clear cache after bulk actions:

     php artisan cache:clear
     php artisan scout:flush "Algowrite\HelpCenter\Models\Article"
     

4. Route Caching

   • If using php artisan route:cache, ensure your help center routes are included in the cache or exclude them:

     php artisan route:cache --exclude="help-center"
     

Debugging Tips

• Log Queries: Enable Laravel’s query log in .env:

  DB_LOG_QUERIES=true
  

• Check Published Views: Override resources/views/vendor/help-center/ to debug rendering issues.
• Validate Input: Use Laravel’s validation for article creation:

  use Algowrite\HelpCenter\Rules\ValidCategory;
  
  $request->validate([
      'title' => 'required|max:255',
      'content' => 'required',
      'category' => ['required', new ValidCategory],
  ]);
  

Extension Points

1. Custom Fields

   • Extend the Article model to add custom attributes:

     class Article extends \Algowrite\HelpCenter\Models\Article
     {
         protected $casts = [
             'is_featured' => 'boolean',
         ];
     }
     

   • Add a migration for new columns.

2. Event Listeners

   • Listen for article events (e.g., ArticleCreated):

     namespace Algowrite\HelpCenter\Events;
     
     class ArticleCreated
     {
         public $article;
     }
     

   • Register in EventServiceProvider:

     protected $listen = [
         ArticleCreated::class => [
             \App\Listeners\NotifyAdmins::class,
         ],
     ];
     

3. API Resources

   • Customize API responses by extending the default resource:

     namespace App\Http\Resources;
     
     use Algowrite\HelpCenter\Models\Article;
     use Illuminate\Http\Resources\Json\JsonResource;
     
     class HelpArticleResource extends JsonResource
     {
         public function toArray($request)
         {
             return [
                 'title' => $this->title,
                 'slug' => $this->slug,
                 'read_time' => $this->estimateReadTime(), // Custom method
             ];
         }
     }
     

4. Middleware

   • Add custom middleware to the help center routes:

     Route::middleware(['auth', 'verified'])->group(function () {
         Route::resource('help', \Algowrite\HelpCenter\Http\Controllers\HelpController::class);
     });