Utility Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require contextualcode/utility-bundle
   

   Register it in config/bundles.php (if not auto-discovered):

   return [
       // ...
       ContextualCode\UtilityBundle\ContextualCodeUtilityBundle::class => ['all' => true],
   ];
   

2. First Use Case The bundle provides utilities for eZ Publish (now eZ Platform). Start with the ContextualCodeUtilityBundle core utilities:

   use ContextualCode\UtilityBundle\Utility\EzPlatformUtility;
   
   class MyService
   {
       private $ezPlatformUtility;
   
       public function __construct(EzPlatformUtility $ezPlatformUtility)
       {
           $this->ezPlatformUtility = $ezPlatformUtility;
       }
   
       public function getCurrentUserLocation()
       {
           return $this->ezPlatformUtility->getCurrentUserLocation();
       }
   }
   

3. Key Entry Points

   • EzPlatformUtility: Core utilities for eZ Platform (e.g., user, content, siteaccess).
   • ContentUtility: Simplified content operations (e.g., fetching, updating).
   • SiteAccessUtility: Siteaccess-aware logic (e.g., switching contexts).
   • LoggerUtility: Structured logging helpers.

   Check the GitLab repository for the latest API docs.

Implementation Patterns

Common Workflows

1. Content Operations Use ContentUtility to abstract eZ Platform content API calls:

   $content = $this->contentUtility->loadContent($contentId);
   $this->contentUtility->updateContent($content, ['fields' => ['title' => 'New Title']]);
   

2. Siteaccess-Aware Logic Leverage SiteAccessUtility to handle multi-site logic:

   $currentSiteaccess = $this->siteAccessUtility->getCurrentSiteaccess();
   $this->siteAccessUtility->switchSiteaccess('custom_siteaccess');
   

3. User Context Fetch user data or permissions via EzPlatformUtility:

   $user = $this->ezPlatformUtility->getCurrentUser();
   if ($this->ezPlatformUtility->hasPermission('content_edit', $user)) {
       // Allow edit
   }
   

4. Dependency Injection Prefer constructor injection for utilities:

   public function __construct(
       EzPlatformUtility $ezPlatformUtility,
       ContentUtility $contentUtility
   ) {
       $this->ezPlatformUtility = $ezPlatformUtility;
       $this->contentUtility = $contentUtility;
   }
   

Integration Tips

• Symfony Events: Extend the bundle by subscribing to eZ Platform events (e.g., ContentPublishEvent).
• Custom Utilities: Create your own utility classes extending ContextualCode\UtilityBundle\BaseUtility.
• Configuration: Override default behavior via config/packages/contextualcode_utility.yaml:

  contextualcode_utility:
      default_siteaccess: 'main'
      content_cache_lifetime: 3600
  

Gotchas and Tips

Pitfalls

1. eZ Platform Dependency

   • The bundle is eZ Platform-specific. Avoid using it in non-eZ projects.
   • Ensure your ezplatform package is installed and configured.

2. Siteaccess Context

   • Methods like getCurrentSiteaccess() rely on Symfony’s RequestStack. Test in a non-CLI environment (e.g., HTTP kernel).
   • Cache invalidation may be needed after siteaccess switches.

3. Content Loading

   • ContentUtility::loadContent() may return null if the content doesn’t exist. Always check:

     $content = $this->contentUtility->loadContent($id);
     if (!$content) {
         throw new \RuntimeException('Content not found');
     }
     

4. Permission Checks

   • hasPermission() uses eZ Platform’s permission system. Ensure your roles and policy definitions are correctly set up.

Debugging Tips

• Enable Debug Mode: Set ezplatform.debug: true in config/packages/ezplatform.yaml for detailed logs.
• Utility Tracing: Use LoggerUtility to trace utility calls:

  $this->loggerUtility->debug('Content loaded', ['content_id' => $content->id]);
  

• Event Listeners: Debug event subscribers with Symfony’s debug:event-dispatcher command.

Extension Points

1. Custom Utilities Extend BaseUtility to add project-specific helpers:

   namespace App\Utility;
   
   use ContextualCode\UtilityBundle\BaseUtility;
   
   class AppUtility extends BaseUtility
   {
       public function customLogic()
       {
           // ...
       }
   }
   

2. Override Services Replace bundle services in config/services.yaml:

   services:
       ContextualCode\UtilityBundle\Utility\ContentUtility:
           class: App\Utility\CustomContentUtility
   

3. Add Twig Extensions Register custom Twig functions/filters in services.yaml:

   services:
       app.twig.content_extension:
           class: App\Twig\ContentExtension
           tags: ['twig.extension']