Help Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer (note: package is outdated; verify compatibility with your Laravel version):

   composer require antwebes/help-bundle
   

   Register the bundle in config/app.php under providers (if using Symfony-style bundles) or manually bootstrap in bootstrap/app.php (if adapted for Laravel).

2. Configuration Publish the bundle’s config (if available) via:

   php artisan vendor:publish --provider="Antwebes\HelpBundle\HelpBundle"
   

   Check config/help.php for default settings (e.g., help storage paths, default templates).

3. First Use Case Display help content for a route/controller:

   // In a controller or Blade template
   use Antwebes\HelpBundle\HelpManager;
   
   $helpManager = app(HelpManager::class);
   $helpContent = $helpManager->getHelp('dashboard'); // 'dashboard' = route/controller name
   return view('dashboard', ['help' => $helpContent]);
   

   Render in Blade:

   @if($help)
       <div class="help-content">{{ $help }}</div>
   @endif
   

Implementation Patterns

Workflows

1. Help Content Management

   • Static Helps: Store help text in YAML/JSON files (e.g., resources/help/dashboard.yml). Example dashboard.yml:

     title: "Dashboard Overview"
     content: "This section shows your analytics..."
     

   • Dynamic Helps: Fetch from a database (extend the bundle or use a service layer to bridge with Laravel’s Eloquent).

2. Integration with Routes/Controllers

   • Route-Based Helps: Use middleware to attach help data to requests:

     // app/Http/Middleware/AttachHelpMiddleware.php
     public function handle($request, Closure $next) {
         $help = app(HelpManager::class)->getHelp($request->route()->getName());
         $request->merge(['help' => $help]);
         return $next($request);
     }
     

   • Controller Methods: Inject help via constructor or resolve in methods:

     public function __construct(private HelpManager $helpManager) {}
     public function show() {
         $help = $this->helpManager->getHelp('user.profile');
         return view('profile', compact('help'));
     }
     

3. Template Patterns

   • Partial Helps: Use Blade components for reusable help UI:

     @component('help::partial', ['content' => $help->content])
     @endcomponent
     

   • Contextual Helps: Show helps conditionally (e.g., user role):

     @auth
         @if(auth()->user()->isAdmin())
             {{ $help }}
         @endif
     @endauth
     

4. Localization

   • Override help files per locale (e.g., resources/help/en/dashboard.yml, resources/help/fr/dashboard.yml).
   • Use Laravel’s localization helpers to switch dynamically:

     $help = $helpManager->getHelp('dashboard', app()->getLocale());
     

Gotchas and Tips

Pitfalls

1. Outdated Package

   • The bundle is last updated in 2015 and lacks Laravel-specific features (e.g., no service provider registration for Laravel’s container).
   • Workaround: Extend the bundle or rewrite core logic (e.g., HelpManager) as a standalone Laravel package.

2. No Built-in Storage

   • Assumes help files are manually placed in resources/help/. For dynamic content, you’ll need to:
     • Create a custom storage adapter (e.g., database, API).
     • Example: Override Antwebes\HelpBundle\Storage\FileStorage to use Eloquent.

3. Route Naming Assumptions

   • The bundle expects help keys to match route names exactly. Mismatches (e.g., user.create vs. user.create.index) will return null.
   • Fix: Normalize route names in HelpManager:

     $routeName = Str::slug($request->route()->getName());
     

4. No Caching Layer

   • Help files are read on every request. Cache results in Laravel’s cache:

     $help = Cache::remember("help_{$routeName}", now()->addHours(1), function() use ($routeName) {
         return $this->helpManager->getHelp($routeName);
     });
     

Debugging

• Missing Helps: Verify:
  • Files exist in resources/help/ (case-sensitive).
  • Route names match filenames (e.g., dashboard route → dashboard.yml).
  • Permissions allow file reads (set storage/ and resources/ to 755).
• Blank Content: Check for YAML/JSON syntax errors in help files (use yaml-lint or jsonlint.com).

Extension Points

1. Custom Storage Implement Antwebes\HelpBundle\Storage\StorageInterface:

   class DatabaseStorage implements StorageInterface {
       public function getHelp(string $key): ?string {
           return HelpModel::where('key', $key)->value('content');
       }
   }
   

   Bind it in config/help.php:

   'storage' => \App\Services\DatabaseStorage::class,
   

2. Help Events Listen for help retrieval events (if the bundle supports them) or create your own:

   event(new HelpRetrieved($routeName, $helpContent));
   

3. Blade Directives Add a @help directive for concise templates:

   // app/Providers/BladeServiceProvider.php
   Blade::directive('help', function ($routeName) {
       return "<?php echo app(\Antwebes\HelpBundle\HelpManager::class)->getHelp({$routeName}); ?>";
   });
   

   Usage:

   @help('dashboard')
   

4. API Integration Expose helps via API routes:

   Route::get('/help/{key}', function ($key) {
       return response()->json(['help' => app(HelpManager::class)->getHelp($key)]);
   });