Ezplatform Admin Ui Laravel Package

Getting Started

First Steps

1. Installation Add the bundle to your Laravel-based eZ Platform project via Composer:

   composer require ezsystems/ezplatform-admin-ui
   

   Ensure EzSystems\EzPlatformAdminUiBundle\EzPlatformAdminUiBundle is enabled in config/bundles.php.

2. Basic Setup

   • Run migrations (if applicable) and clear caches:

     php bin/console doctrine:migrations:migrate
     php bin/console cache:clear
     

   • Configure the bundle in config/packages/ez_platform_admin_ui.yaml (default config is minimal; extend as needed).

3. First Use Case Access the admin UI at /admin (or your configured route). Verify the dashboard loads and test basic CRUD operations (e.g., creating a content type or content item).

Implementation Patterns

Core Workflows

1. Content Management

   • Create/Edit Content: Use the built-in form builder to define fields for content types. Leverage the ezplatform-admin-ui templates to customize the UI (e.g., override content/edit.html.twig).
   • Workflows: Configure workflows in config/packages/ez_platform_admin_ui.yaml to manage content states (e.g., draft → published).

2. Content Type Customization

   • Extend default content types via YAML/PHP definitions (e.g., config/content_types/my_custom_type.yaml).
   • Use the ezplatform-admin-ui field types (e.g., ezrichtext, ezimage) or create custom ones by implementing EzSystems\EzPlatformAdminUi\FieldType\FieldTypeInterface.

3. Permissions & Roles

   • Define roles/permissions in config/packages/security.yaml to restrict access to admin features (e.g., ROLE_ADMIN for full access).
   • Use the ezplatform-admin-ui permission system to scope actions (e.g., ezpublish.siteaccess.group.edit).

4. API Integration

   • Use the underlying eZ Platform API (ezpublish-api) for custom logic. Example:

     use EzSystems\EzPlatformAdminUi\API\Repository\ContentService;
     $content = $contentService->createContent($contentType, $parentLocation);
     

5. Theming & Assets

   • Override Twig templates in templates/bundles/EzSystemsEzPlatformAdminUi/ to modify the UI.
   • Customize CSS/JS by extending the bundle’s asset pipeline (e.g., add a custom_admin.css to assets/admin/).

Gotchas and Tips

Common Pitfalls

1. Cache Issues

   • Clear caches aggressively after config changes:

     php bin/console cache:clear --env=prod
     php bin/console ezplatform:cache:clear
     

   • Use --no-debug flag in development to avoid cache conflicts.

2. Field Type Mismatches

   • Ensure field definitions in content types match the available ezplatform-admin-ui field types. Example error:

     [Ez\Publish\API\Repository\Exceptions\InvalidArgumentException] Field type "ezcustom" is not supported.
     

   • Solution: Implement a custom field type or use an existing one (e.g., ezstring for text).

3. Permission Denied

   • Double-check security.yaml and ez_platform_admin_ui.yaml for correct role mappings. Example:

     # security.yaml
     role_hierarchy:
         ROLE_ADMIN: [ROLE_EZPUBLISH_ADMIN]
     

4. Database Schema Conflicts

   • Run php bin/console doctrine:schema:validate to check for schema issues after migrations.
   • Use ezplatform-admin-ui’s schema updates sparingly; prefer manual migrations for complex changes.

Pro Tips

1. Debugging

   • Enable debug mode in config/packages/dev/ez_platform_admin_ui.yaml:

     debug: true
     

   • Use the ezplatform-admin-ui profiler toolbar (enabled by default in dev) to inspect API calls and performance.

2. Custom Field Types

   • Extend EzSystems\EzPlatformAdminUi\FieldType\AbstractFieldType for reusable field logic. Example:

     namespace App\FieldType;
     use EzSystems\EzPlatformAdminUi\FieldType\AbstractFieldType;
     
     class CustomFieldType extends AbstractFieldType {
         public function getName() { return 'ezcustom'; }
         // Implement render(), validate(), etc.
     }
     

   • Register in services.yaml:

     services:
         App\FieldType\CustomFieldType:
             tags: ['ezplatform_admin_ui.field_type']
     

3. Performance

   • Limit loaded content in lists via ez_platform_admin_ui.yaml:

     list:
         max_items: 50
     

   • Use lazy-loading for large content trees.

4. Localization

   • Override translations in translations/messages.en.yaml:

     ezplatform_admin_ui:
         content:
             create: "Create New Item (Custom)"
     

5. Testing

   • Use ezplatform-admin-ui’s functional tests as a baseline. Example:

     $this->client->request('GET', '/admin/content/create');
     $this->assertResponseIsSuccessful();
     

   • Mock the API repository for unit tests:

     $repository = $this->createMock(ContentService::class);
     $this->container->set('ezpublish.api.repository', $repository);