Wikibundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Laravel project via Composer:

   composer require masando/edemy-wikibundle
   

   Register the bundle in config/app.php under providers:

   Masando\WikiBundle\WikiServiceProvider::class,
   

   Publish the migration and config files:

   php artisan vendor:publish --provider="Masando\WikiBundle\WikiServiceProvider"
   

   Run the migrations:

   php artisan migrate
   

2. First Use Case Create a wiki page via Tinker or a controller:

   use Masando\WikiBundle\Models\WikiPage;
   
   $page = WikiPage::create([
       'title' => 'Getting Started',
       'content' => '# Welcome to the Wiki!',
       'slug' => 'getting-started',
   ]);
   

   Access the page via a route (ensure WikiController is registered):

   Route::get('/wiki/{slug}', [\Masando\WikiBundle\Http\Controllers\WikiController::class, 'show']);
   

Implementation Patterns

Core Workflows

1. Page Management

   • Create/Edit: Use the WikiPage model or the provided form requests (StoreWikiPageRequest, UpdateWikiPageRequest).

     $page = WikiPage::updateOrCreate(
         ['slug' => 'new-page'],
         ['title' => 'Updated Title', 'content' => '# New Content']
     );
     

   • Versioning: Leverage the versions() relationship to track changes:

     $page->versions()->latest()->first();
     

2. Routing & Controllers

   • Extend the default WikiController or create custom routes:

     Route::prefix('wiki')->group(function () {
         Route::get('/search', [\App\Http\Controllers\WikiController::class, 'search']);
     });
     

   • Use the WikiService for business logic:

     $this->wikiService->renderPage($slug); // Hypothetical method
     

3. Markdown Support

   • Parse content with a library like commonmark/commonmark:

     use CommonMark\CommonMarkConverter;
     $converter = new CommonMarkConverter();
     $html = $converter->convert($page->content);
     

4. Access Control

   • Attach policies or middleware to restrict page access:

     // app/Policies/WikiPagePolicy.php
     public function view(User $user, WikiPage $page) {
         return $user->isAdmin || $page->isPublic();
     }
     

Gotchas and Tips

Pitfalls

1. Missing Dependencies

   • The bundle assumes masando/edemy-framework is installed. If not, expect undefined class/method errors. Verify compatibility with your Laravel version (likely 8.x+).

2. Slug Conflicts

   • Slugs are auto-generated from titles but may collide. Override the generateSlug() method in WikiPage if needed:

     protected static function generateSlug($title) {
         return Str::slug($title . '-' . uniqid());
     }
     

3. Versioning Overhead

   • Each edit creates a new version. For high-traffic wikis, consider:
     • Soft-deleting old versions.
     • Using a queue for version creation.

4. No Built-in Search

   • The bundle lacks search functionality. Integrate with Laravel Scout or Algolia:

     use Masando\WikiBundle\Scout\WikiPageScout;
     
     // In WikiPage model
     public function shouldSearchable() { return true; }
     

Debugging Tips

• Check Routes: Run php artisan route:list to verify wiki routes are registered.
• Log Content: Debug markdown parsing issues by logging raw content:

  \Log::debug('Wiki content:', ['content' => $page->content]);
  

• Database Schema: Inspect the wiki_pages and wiki_page_versions tables for unexpected data.

Extension Points

1. Custom Fields Extend the WikiPage model to add metadata:

   // app/Models/WikiPage.php
   protected $casts = [
       'is_featured' => 'boolean',
       'publish_date' => 'datetime',
   ];
   

2. Event Listeners Hook into wiki events (e.g., WikiPageCreated) in EventServiceProvider:

   protected $listen = [
       \Masando\WikiBundle\Events\WikiPageCreated::class => [
           \App\Listeners\NotifyWikiEdit::class,
       ],
   ];
   

3. API Endpoints Use Laravel API Resources to expose wiki data:

   // app/Http/Resources/WikiPageResource.php
   public function toArray($request) {
       return [
           'title' => $this->title,
           'url' => route('wiki.show', $this->slug),
       ];
   }