Ezobjectwrapperbundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require datafactory/ezobjectwrapperbundle
   

   Add to config/bundles.php:

   Datafactory\EzObjectWrapperBundle\DatafactoryEzObjectWrapperBundle::class => ['all' => true],
   

2. First Use Case: Wrap a content object for easier access to fields:

   use Datafactory\EzObjectWrapperBundle\Wrapper\ContentWrapper;
   
   $content = $repository->getContentById($contentId);
   $wrapper = new ContentWrapper($content);
   
   // Access fields by name (case-insensitive)
   $title = $wrapper->getField('title')->value;
   $image = $wrapper->getField('image')->value->getFileUri();
   

3. Key Files:

   • src/Wrapper/ContentWrapper.php (core wrapper logic)
   • src/Wrapper/LocationWrapper.php (location-specific methods)
   • src/Service/EzObjectWrapperService.php (service container integration)

Implementation Patterns

Common Workflows

1. Field Access Patterns

// Basic field retrieval
$wrapper->getField('field_identifier')->value;

// With fallback
$wrapper->getField('optional_field')->value ?? 'default';

// Field metadata
$field = $wrapper->getField('field_name');
$field->identifier;  // 'field_name'
$field->typeString;  // 'ezstring'
$field->isRequired;   // bool

2. Location Hierarchy Traversal

$locationWrapper = new LocationWrapper($location);
$parent = $locationWrapper->getParent();
$children = $locationWrapper->getChildren();

// Get path as array of locations
$path = $locationWrapper->getPath();

3. Service Container Integration

# services.yaml
services:
    App\Service\ContentService:
        arguments:
            $wrapperService: '@datafactory_ez_object_wrapper.service'

// In your service
public function __construct(
    private EzObjectWrapperService $wrapperService
) {}

public function processContent($content) {
    $wrapper = $this->wrapperService->wrapContent($content);
    // ...
}

4. Custom Field Types

Extend for custom field types (e.g., ezrichtext):

use Datafactory\EzObjectWrapperBundle\Wrapper\FieldWrapper;

class RichTextWrapper extends FieldWrapper {
    public function getHtml() {
        return $this->value->html;
    }
}

Register in services.yaml:

services:
    Datafactory\EzObjectWrapperBundle\Wrapper\FieldWrapper:
        arguments:
            $customTypes:
                ezrichtext: App\Wrapper\RichTextWrapper

Gotchas and Tips

Pitfalls

1. Deprecated eZ Platform 5:

   • The package targets eZ Publish 5 (pre-Platform UI). Test thoroughly with eZ Platform 6+ if migrating.
   • Symfony 3.x compatibility assumed; may need adjustments for Symfony 4/5.

2. Field Identifier Sensitivity:

   • Field names are case-insensitive in wrappers, but underlying eZ field identifiers are case-sensitive.
   • Debug with:

     $wrapper->getFieldNames(); // List all available field identifiers
     

3. Circular References:

   • Wrapping nested content/locations (e.g., ezobjectrelation) may cause infinite loops.
   • Mitigate with lazy-loading or depth limits:

     $wrapper->setMaxDepth(3); // Limit recursion
     

4. Service Container Overhead:

   • The EzObjectWrapperService adds minimal overhead but may conflict with existing eZ services.
   • Tip: Use manually instantiated wrappers (new ContentWrapper($content)) for performance-critical paths.

Debugging Tips

• Enable Debug Mode:

  $wrapper->setDebug(true);
  // Logs field access to Symfony's logger
  

• Field Validation:

  if (!$wrapper->hasField('field_name')) {
      throw new \RuntimeException("Field 'field_name' not found");
  }
  

• Performance Profiling: Wrap only the fields you need:

  $wrapper = new ContentWrapper($content, ['title', 'image']);
  

Extension Points

1. Custom Wrappers: Extend Datafactory\EzObjectWrapperBundle\Wrapper\AbstractWrapper for domain-specific logic.

2. Field Type Overrides: Override default field type handlers in services.yaml (see Implementation Patterns).

3. Event Listeners: Hook into ezpublish.api.service.content to auto-wrap content in repositories:

   // config/services.yaml
   App\EventListener\ContentWrapperListener:
       tags:
           - { name: kernel.event_listener, event: ezpublish.api.service.content.get, method: onContentGet }
   

Configuration Quirks

• Default Field Types: The bundle ships with basic type handlers (ezstring, ezrichtext, ezimage). Add custom types via DI.

• Language Handling: Wrappers default to the current siteaccess language. Override with:

  $wrapper = new ContentWrapper($content, [], 'eng-GB');
  

• Legacy eZ Platform: If using eZ Platform Enterprise, ensure ezpublish-kernel is pinned to ^5.4 to avoid conflicts.