Ezpublish Kernel Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   Add the package via Composer in your Laravel project (ensure compatibility with v7.5.31):
   ```bash
   composer require ezsystems/ezpublish-kernel:^7.5.31 ezsystems/ezplatform-repository ezsystems/ezplatform-admin-ui

2. Service Provider Register the EzSystems\EzPublishKernel\EzPublishKernelServiceProvider in config/app.php under providers:

   'providers' => [
       // ...
       EzSystems\EzPublishKernel\EzPublishKernelServiceProvider::class,
   ],
   

3. Configuration Publish the default config:

   php artisan vendor:publish --provider="EzSystems\EzPublishKernel\EzPublishKernelServiceProvider" --tag="config"
   

   Update config/ezpublish-kernel.php with your eZ Platform credentials (e.g., siteaccess, connection). Note: Verify upload_blocklist in ezpublish-kernel.php if using file uploads, as v7.5.31 adds more PHP file types to the default blocklist.

4. First Use Case: Fetching Content Inject the EzSystems\EzPublishKernel\API\Repository\Repository into a Laravel service:

   use EzSystems\EzPublishKernel\API\Repository\Repository;
   
   class ContentService {
       protected $repository;
   
       public function __construct(Repository $repository) {
           $this->repository = $repository;
       }
   
       public function getContentById($contentId) {
           return $this->repository->getContentService()->loadContent($contentId);
       }
   }
   

Implementation Patterns

Core Workflows

1. Content Management

   • CRUD Operations: Use ContentService for create/read/update/delete:

     $contentService = $repository->getContentService();
     $content = $contentService->createContent($contentType, $parentLocationId);
     $contentService->publishVersion($content->versionInfo);
     

   • Location Handling: Manage content hierarchy with LocationService:

     $locationService = $repository->getLocationService();
     $location = $locationService->createLocation($parentLocation, $content);
     

2. File Upload Security New in v7.5.31: The default upload_blocklist now includes additional PHP file types (e.g., .phar, .phtml). If customizing uploads:

   // Override blocklist in config/ezpublish-kernel.php
   'upload_blocklist' => [
       '*.php', '*.phar', '*.phtml', // Default extended list
       '*.exe', // Additional custom blocks
   ],
   

   Validate against this list in Laravel middleware or services:

   use EzSystems\EzPublishKernel\API\Repository\Values\Content\FieldValue\Asset;
   
   public function validateUpload(Asset $asset) {
       $fileExt = strtolower(pathinfo($asset->getFile()->getUri(), PATHINFO_EXTENSION));
       $blocked = in_array("*.{$fileExt}", config('ezpublish-kernel.upload_blocklist'));
       if ($blocked) {
           throw new \Exception("File type blocked: {$fileExt}");
       }
   }
   

3. Search and Filtering Leveraging SearchService for advanced queries:

   $searchService = $repository->getSearchService();
   $query = new \eZ\Publish\API\Repository\Values\Content\Query\Query();
   $query->query = new \eZ\Publish\API\Repository\Values\Content\Query\Criterion\LogicalAnd([
       new \eZ\Publish\API\Repository\Values\Content\Query\Criterion\ContentId($contentId),
   ]);
   $searchResults = $searchService->findContent($query);
   

4. REST API Integration Use Rest\Client for external API calls (if enabled):

   $restClient = $repository->getRestClient();
   $response = $restClient->get('/api/ezp/v2/content/full/{contentId}');
   

Laravel Integration Tips

• Service Container Binding: Bind custom repositories or services to Laravel’s container:

  $this->app->bind('custom.content.service', function ($app) {
      return new CustomContentService($app->make(Repository::class));
  });
  

• Middleware for Authentication: Protect routes using eZ Platform’s authentication:

  Route::middleware(['ezpublish.auth'])->group(function () {
      Route::get('/admin', 'AdminController@index');
  });
  

• Event Listeners: Listen to eZ Platform events (e.g., ContentPublishedEvent):

  Event::listen('ezpublish.content.published', function ($event) {
      // Trigger Laravel logic on content publish
  });
  

Gotchas and Tips

Common Pitfalls

1. Siteaccess Configuration

   • Issue: Forgetting to configure the correct siteaccess in ezpublish-kernel.php can lead to silent failures or unexpected behavior.
   • Fix: Always validate the siteaccess matches your environment (e.g., dev, prod).

2. Caching Quirks

   • Issue: eZ Platform caches content and locations aggressively. Changes may not reflect immediately in Laravel.
   • Fix: Clear caches explicitly:

     $repository->getCacheManager()->clearAll();
     

     Or use php artisan ezplatform:clear-cache (if the artisan commands are set up).

3. File Upload Restrictions (New in v7.5.31)

   • Issue: Uploads of PHP-related files (e.g., .phar, .phtml) may fail silently if not explicitly allowed in upload_blocklist.
   • Fix: Review and update config/ezpublish-kernel.php:

     'upload_blocklist' => [
         // Customize as needed (default now includes more PHP types)
     ],
     

   • Debugging: Log blocked uploads:

     \Log::warning("Blocked upload attempt: {$fileExt}", ['blocklist' => config('ezpublish-kernel.upload_blocklist')]);
     

4. Field Type Mismatches

   • Issue: Laravel’s type system may not align with eZ Platform’s field types (e.g., ezstring vs. string).
   • Fix: Use type casting or custom accessors:

     $fieldValue = $content->getField('title')->value;
     $castValue = is_array($fieldValue) ? $fieldValue['value'] : $fieldValue;
     

5. Transaction Handling

   • Issue: Mixing Laravel transactions with eZ Platform’s repository transactions can cause deadlocks or rollback conflicts.
   • Fix: Avoid nested transactions or use explicit commit/rollback:

     $repository->beginTransaction();
     try {
         // Operations
         $repository->commit();
     } catch (\Exception $e) {
         $repository->rollback();
         throw $e;
     }
     

Debugging Tips

• Enable Debug Mode: Set debug: true in ezpublish-kernel.php to log API calls.
• Log Repository Events: Use Laravel’s logging to track repository interactions:

  \Log::info('Content loaded:', ['content' => $content->getId()]);
  

• Validate API Responses: Always check for null or NotFoundException when loading content/locations:

  try {
      $content = $repository->getContentService()->loadContent($contentId);
  } catch (\eZ\Publish\API\Repository\Exceptions\NotFoundException $e) {
      \Log::warning("Content not found: {$contentId}");
  }
  

• Upload Validation: Log blocked file types for debugging:

  \Log::debug("File extension check", ['extension' => $fileExt, 'blocklist' => config('ezpublish-kernel.upload_blocklist')]);
  

Extension Points

1. Custom Content Services Extend EzSystems\EzPublishKernel\API\Repository\Values\Content\Content to add Laravel-specific methods:

   class CustomContent extends \EzSystems\EzPublishKernel\API\Repository\Values\Content\Content {
       public function getLaravelMetadata() {
           return $this->getField('laravel_meta')->value ?? null;
       }
   }
   

   Bind it in a service provider:

   $this->app->bind(\EzSystems\EzPublishKernel\API\Repository\Values\Content\Content::class, CustomContent::class);
   

2. Event Subscribers Create Laravel event listeners for eZ Platform events:

   class ContentPublishedListener {
       public function handle(\EzSystems\EzPublishKernel\Event\ContentPublishedEvent $event) {
           // Trigger Laravel notifications, queues, etc.
           event(new \App\Events\ContentPublished($event->getContent()));
       }
   }