Vanilla Laravel Package

Getting Started

Minimal Steps to Integration

1. Installation via Composer

   composer require dimassrio/vanilla
   

   • Ensure you’re pulling from the 2.1 branch (stable) for production:

     git clone -b 2.1 https://github.com/dimassrio/vanilla.git
     

2. Publish Assets Run the package’s installer (if included) or manually publish:

   php artisan vendor:publish --provider="Vanilla\VanillaServiceProvider" --tag=public
   php artisan vendor:publish --provider="Vanilla\VanillaServiceProvider" --tag=migrations
   

   • Verify config/vanilla.php exists and update database credentials.

3. Run Migrations

   php artisan migrate
   

   • Check database/migrations/ for Vanilla-specific tables (e.g., Discussions, Comments).

4. First Use Case: Embedding a Forum Add the Vanilla widget to a Laravel Blade view:

   @vanilla('forum', ['id' => 'community-discussions', 'title' => 'Community Chat'])
   

   • Requires JavaScript initialization (see resources/js/vanilla.js).

Implementation Patterns

Core Workflows

1. Forum Embedding

   • Dynamic Integration: Use Laravel’s service container to inject Vanilla’s API client:

     $vanilla = app(\Vanilla\Contracts\VanillaClient::class);
     $discussions = $vanilla->getDiscussions(['limit' => 5]);
     

   • Blade Directives: Extend Blade with @vanilla directives for seamless rendering:

     // In AppServiceProvider::boot()
     Blade::directive('vanilla', function ($expression) {
         return "<?php echo app(\Vanilla\View\VanillaRenderer::class)->render($expression); ?>";
     });
     

2. Authentication Sync

   • SSO Integration: Use Laravel’s Auth facade to sync users:

     $vanillaUser = $vanilla->createUser([
         'Name' => auth()->user()->name,
         'Email' => auth()->user()->email,
         'Password' => Str::random(12),
     ]);
     

   • Middleware: Protect Vanilla routes with Laravel’s auth:

     Route::middleware(['auth'])->group(function () {
         Route::prefix('vanilla')->group(function () {
             // Vanilla routes here
         });
     });
     

3. Plugin/Theming

   • Custom Themes: Override Vanilla’s CSS/JS via Laravel Mix:

     // resources/js/app.js
     require('@vanilla/vanilla-theme');
     require('./custom-vanilla-theme');
     

   • Plugin Hooks: Extend Vanilla’s functionality via Laravel events:

     // Listen to Vanilla's 'DiscussionCreated' event
     event(new \Vanilla\Events\DiscussionCreated($discussion));
     

Gotchas and Tips

Pitfalls

1. Branch Dependency

   • Issue: Pulling master may introduce unstable features.
   • Fix: Always pin to 2.1 branch for production:

     composer require dimassrio/vanilla:2.1.*
     

2. Asset Conflicts

   • Issue: Vanilla’s JS/CSS may clash with Laravel’s.
   • Fix: Use Laravel Mix to combine assets:

     // webpack.mix.js
     mix.js('resources/js/vanilla.js', 'public/js')
          .sass('resources/scss/vanilla.scss', 'public/css');
     

3. Database Schema Mismatches

   • Issue: Vanilla migrations may conflict with existing Laravel tables.
   • Fix: Use a separate database or prefix tables:

     // config/vanilla.php
     'database' => [
         'prefix' => 'vanilla_',
     ];
     

Debugging Tips

1. Logging Enable Vanilla’s debug mode in config/vanilla.php:

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

   • Logs appear in storage/logs/vanilla.log.

2. API Rate Limiting

   • Vanilla’s API may throttle requests. Cache responses:

     $discussions = Cache::remember('vanilla_discussions', now()->addHours(1), function () {
         return $vanilla->getDiscussions();
     });
     

3. Plugin Development

   • Extension Point: Use Vanilla’s Hook system via Laravel’s service providers:

     // app/Providers/VanillaHookProvider.php
     public function register()
     {
         \Vanilla\Hook::add('DiscussionController_BeforeSave', function ($sender, $args) {
             // Modify discussion data
             $args['Discussion']['Tags'] = 'laravel';
         });
     }
     

Configuration Quirks

1. CORS Issues

   • If embedding Vanilla in an iframe, ensure CORS headers are set in config/vanilla.php:

     'cors' => [
         'allowed_origins' => ['https://your-laravel-app.com'],
     ],
     

2. Asset Versioning

   • Disable Vanilla’s default asset versioning to avoid conflicts:

     'assets' => [
         'versioning' => false,
     ],
     

3. Localization

   • Override Vanilla’s language files via Laravel’s lang directory:

     resources/lang/en/vanilla.php