Vk Board Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/vk-board
   php artisan vendor:publish --provider="BaksDev\VkBoard\VkBoardServiceProvider" --tag="config"
   php artisan baks:assets:install
   

   • Verify config/vk-board.php exists and update API credentials (VK app ID, secret, etc.).

2. First Use Case: Fetching Board Data

   use BaksDev\VkBoard\Facades\VkBoard;
   
   $board = VkBoard::getBoard('your_board_id');
   dd($board->topics); // Returns a collection of topics
   

3. Key Files to Review

   • config/vk-board.php (API credentials, defaults)
   • app/Providers/VkBoardServiceProvider.php (Service binding)
   • routes/vk-board.php (Predefined routes, if any)

Implementation Patterns

Core Workflows

1. CRUD Operations

   // Create a topic
   $topic = VkBoard::createTopic([
       'title' => 'New Topic',
       'message' => 'Hello, world!',
       'board_id' => 'your_board_id'
   ]);
   
   // Update a topic
   $topic->update(['title' => 'Updated Title']);
   
   // Delete a topic
   $topic->delete();
   

2. Event-Driven Integration

   • Listen to board events via Laravel’s event system:

     use BaksDev\VkBoard\Events\TopicCreated;
     
     event(new TopicCreated($topic));
     

   • Publish custom events by extending the package’s event classes.

3. API Wrapper Abstraction

   • Use the facade for direct API calls:

     $response = VkBoard::api()->method('boards.getTopics', [
         'board_id' => 'your_board_id',
         'count' => 10
     ]);
     

4. Model Integration

   • Attach the package’s models to your Eloquent models:

     use BaksDev\VkBoard\Models\Topic;
     
     class MyTopic extends Topic {
         protected $table = 'my_topics';
     }
     

5. Middleware for Auth

   • Protect routes with VK OAuth middleware:

     Route::get('/board', function () {
         return VkBoard::getUserBoard();
     })->middleware('vk.auth');
     

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • VK’s API enforces strict rate limits. Cache responses aggressively:

     $topics = Cache::remember("vk_board_{$boardId}_topics", now()->addHours(1), function () use ($boardId) {
         return VkBoard::getBoard($boardId)->topics;
     });
     

2. Locale/Encoding Issues

   • VK returns data in UTF-8, but some legacy systems may misinterpret it. Use:

     mb_internal_encoding('UTF-8');
     

3. Webhook Delays

   • VK webhooks may have delays (up to 15 minutes). Use a queue job for critical updates:

     use BaksDev\VkBoard\Jobs\ProcessWebhook;
     
     ProcessWebhook::dispatch($payload)->onQueue('vk-webhooks');
     

4. Board Permissions

   • Ensure your VK app has the correct permissions (boards, messages, etc.) in the VK Developer Console.

Debugging

• Enable Debug Mode Add to config/vk-board.php:

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

  Logs API calls and responses to storage/logs/vk-board.log.

• Mock API Responses Use the VkBoardMock trait in tests:

  use BaksDev\VkBoard\Testing\VkBoardMock;
  
  public function testTopicCreation()
  {
      VkBoardMock::shouldReceive('createTopic')->once()->andReturn(new Topic());
      // ...
  }
  

Extension Points

1. Custom API Methods Extend the BaksDev\VkBoard\Api\Client class:

   namespace App\Services;
   
   use BaksDev\VkBoard\Api\Client;
   
   class CustomVkClient extends Client
   {
       public function customMethod(array $params)
       {
           return $this->call('custom.method', $params);
       }
   }
   

2. Model Observers Add observers to track changes:

   use BaksDev\VkBoard\Models\Topic;
   use Illuminate\Database\Eloquent\Builder;
   
   Topic::observe(TopicObserver::class);
   
   class TopicObserver
   {
       public function saved(Topic $topic)
       {
           // Log or notify on topic updates
       }
   }
   

3. Command-Line Tools Create custom Artisan commands:

   php artisan make:command SyncVkBoard
   

   Example:

   use BaksDev\VkBoard\Facades\VkBoard;
   
   class SyncVkBoard extends Command
   {
       protected $signature = 'vk:sync {board_id}';
       public function handle()
       {
           $board = VkBoard::getBoard($this->argument('board_id'));
           // Sync logic here
       }
   }
   

4. Webhook Handling Extend the BaksDev\VkBoard\WebhookHandler:

   namespace App\Services;
   
   use BaksDev\VkBoard\WebhookHandler;
   
   class CustomWebhookHandler extends WebhookHandler
   {
       protected function handleTopicCreate(array $payload)
       {
           // Custom logic for topic creation
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(
       \BaksDev\VkBoard\Contracts\WebhookHandler::class,
       \App\Services\CustomWebhookHandler::class
   );