Kiwi Cloud Cms Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ara-solutions/kiwi-cloud-cms
   

   Ensure your project uses Symfony Flex or manually enable the bundle in config/bundles.php:

   AraSolutions\KiwiCloudCmsBundle\KiwiCloudCmsBundle::class => ['all' => true],
   

2. First Use Case

   • Purpose: The package provides tooltips for managing Kiwi Cloud CMS data (e.g., content, assets, or configurations).
   • Quick Test: Check if the bundle registers its services by running:

     php bin/console debug:container | grep kiwi
     

   • Expected Output: Confirm the bundle’s services (e.g., kiwi.cloud.cms.manager) are autowired.

3. Where to Look First

   • Documentation: The package lacks formal docs, so inspect:
     • src/ for core classes (e.g., KiwiCloudCmsManager).
     • Resources/config/services.yaml for service configurations.
   • Symfony Profiler: Use the Symfony Profiler to trace Kiwi CMS interactions (if integrated).

Implementation Patterns

Core Workflows

1. Data Management

   • Fetching Content: Use the manager service to retrieve Kiwi CMS data (e.g., pages, assets):

     $manager = $this->container->get('kiwi.cloud.cms.manager');
     $content = $manager->getContent('page-slug');
     

   • Updating Content: Push changes back to Kiwi CMS via the manager:

     $manager->updateContent('page-slug', ['title' => 'New Title']);
     

2. Integration with Laravel

   • Service Binding: Bind the Kiwi CMS manager to Laravel’s container in config/app.php:

     'bindings' => [
         AraSolutions\KiwiCloudCmsBundle\Manager\KiwiCloudCmsManager::class
             => AraSolutions\KiwiCloudCmsBundle\Manager\KiwiCloudCmsManager::class,
     ],
     

   • Facade (Optional): Create a facade for cleaner syntax:

     // app/Facades/KiwiCms.php
     namespace App\Facades;
     use Illuminate\Support\Facades\Facade;
     class KiwiCms extends Facade { protected static function getFacadeAccessor() { return 'kiwi.cloud.cms.manager'; } }
     

     Usage:

     KiwiCms::getContent('page-slug');
     

3. Event-Driven Updates

   • Listen for Kiwi CMS Changes: Subscribe to Kiwi CMS webhooks (if supported) to trigger Laravel events:

     // In a service provider
     $this->app['events']->listen(
         'kiwi.cms.content.updated',
         function ($content) { /* Sync with DB */ }
     );
     

4. Caching

   • Cache Kiwi CMS Responses: Use Laravel’s cache to reduce API calls:

     $content = Cache::remember("kiwi_cms_{$slug}", now()->addHours(1), function () use ($slug) {
         return $manager->getContent($slug);
     });
     

Gotchas and Tips

Pitfalls

1. No Official Docs

   • Workaround: Reverse-engineer the src/ directory. Key classes likely include:
     • KiwiCloudCmsManager (core logic).
     • KiwiCloudCmsClient (API wrapper).
   • Assumption: The package may rely on Kiwi Cloud’s undocumented API; test endpoints thoroughly.

2. Symfony vs. Laravel Compatibility

   • Issue: The bundle is Symfony-based. Laravel-specific quirks:
     • Service Container: Use Laravel’s app() helper or bind services manually.
     • Events: Laravel’s event system differs from Symfony’s; wrap calls in a service layer.
   • Fix: Create a Laravel-compatible adapter layer if needed.

3. Authentication

   • Problem: Kiwi CMS likely requires API keys. The package may not handle this out-of-the-box.
   • Solution: Configure credentials in .env:

     KIWI_CMS_API_KEY=your_key_here
     KIWI_CMS_API_SECRET=your_secret
     

     Pass these to the manager:

     $manager->setCredentials(env('KIWI_CMS_API_KEY'), env('KIWI_CMS_API_SECRET'));
     

4. Rate Limiting

   • Risk: Kiwi CMS may throttle requests. Implement exponential backoff:

     try {
         $content = $manager->getContent($slug);
     } catch (RateLimitException $e) {
         sleep(2 ** $attempt++);
         retry();
     }
     

Debugging Tips

1. Enable Debug Mode

   • Add to config/kiwi_cms.php (if config exists):

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

   • Log raw API responses for troubleshooting:

     $manager->setDebug(true);
     

2. Mocking for Tests

   • Use Laravel’s Mockery to stub the Kiwi CMS client:

     $mock = Mockery::mock(AraSolutions\KiwiCloudCmsBundle\Client\KiwiCloudCmsClient::class);
     $mock->shouldReceive('getContent')->andReturn(['title' => 'Test']);
     $this->app->instance('kiwi.cloud.cms.client', $mock);
     

3. Common Errors

   • 401 Unauthorized: Verify API credentials.
   • 404 Not Found: Check slugs/IDs against Kiwi CMS.
   • 500 Server Error: Kiwi CMS may be down; implement retry logic.

Extension Points

1. Custom Content Types

   • Extend the manager to support non-standard Kiwi CMS data:

     class ExtendedKiwiCmsManager extends AraSolutions\KiwiCloudCmsBundle\Manager\KiwiCloudCmsManager {
         public function getCustomData($type) { /* Custom logic */ }
     }
     

   • Bind the extended class in config/app.php.

2. Webhook Handlers

   • Add Laravel event listeners for Kiwi CMS webhooks:

     // routes/web.php
     Route::post('/kiwi-cms/webhook', [KiwiWebhookController::class, 'handle']);
     

     // app/Http/Controllers/KiwiWebhookController.php
     public function handle(Request $request) {
         event(new KiwiCmsWebhookReceived($request->all()));
     }
     

3. Local Overrides

   • Override bundle configurations in config/packages/ara_solutions_kiwi_cloud_cms.php:

     services:
         kiwi.cloud.cms.manager:
             arguments:
                 $baseUrl: '%env(KIWI_CMS_CUSTOM_URL)%'