Bundles Cms Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require kunstmaan/bundles-cms
   

   Follow the official documentation for full setup instructions.

2. First Use Case:

   • Create a basic page type by extending Kunstmaan\NodeBundle\Entity\Node and configuring it in config.yml:

     kunstmaan_node:
         node_types:
             my_custom_type:
                 class: AppBundle\Entity\MyCustomNode
                 title: "My Custom Page"
     

   • Generate a CRUD controller for your entity using:

     php bin/console generate:crud
     

3. Where to Look First:

   • Admin Bundle: src/Kunstmaan/AdminBundle/ for core CMS functionality.
   • Node Bundle: src/Kunstmaan/NodeBundle/ for page management.
   • Media Bundle: src/Kunstmaan/MediaBundle/ for media handling.
   • Documentation: Kunstmaan CMS Docs for bundle-specific guides.

Implementation Patterns

Core Workflows

1. Page Management

• Creating a Page Type: Extend AbstractNode and configure in kunstmaan_node.node_types:

  kunstmaan_node:
      node_types:
          blog_post:
              class: AppBundle\Entity\BlogPost
              title: "Blog Post"
              icon: "fa fa-newspaper-o"
  

  • Use NodeTypeInterface to define custom fields and behaviors.

• Page Assembly: Use the Page Builder to assemble pages from components. Components are defined in YAML:

  kunstmaan_pagebuilder:
      components:
          my_custom_component:
              class: AppBundle\Component\MyCustomComponent
              title: "My Custom Component"
              icon: "fa fa-cog"
  

2. Media Handling

• Upload and manage media via the Media Manager:

  $media = $mediaManager->upload($file, 'my_media_folder');
  

• Embed media in pages using the MediaFieldType in your node entity.

3. Multi-Language Support

• Enable translations for nodes/components:

  kunstmaan_node:
      node_types:
          blog_post:
              translations: true
  

• Use TranslatableInterface for translatable entities.

4. Workflow Management

• Define workflows in config.yml:

  kunstmaan_workflow:
      workflows:
          page_workflow:
              type: state_machine
              supports: [AppBundle\Entity\Node]
              transitions:
                  draft:
                      from: draft
                      to: published
  

• Trigger transitions in controllers:

  $workflow->apply($node, 'draft');
  

5. Admin Menu Integration

• Simple Menu Item:

  kunstmaan_admin:
      menu_items:
          - route: app_my_custom_route
            label: "My Custom Module"
            parent: ~  # Attaches to "Modules" by default
  

• Custom Menu Adaptor (for complex logic):

  class MyMenuAdaptor implements MenuAdaptorInterface {
      public function adaptChildren(MenuBuilder $menu, array &$children, MenuItem $parent = null, Request $request = null) {
          if ($parent->getRoute() === 'KunstmaanAdminBundle_modules') {
              $children[] = new TopMenuItem($menu)
                  ->setRoute('app_my_route')
                  ->setLabel('Custom Menu Item');
          }
      }
  }
  

  Register the service in services.yml:

  services:
      my_menu_adaptor:
          class: AppBundle\Helper\Menu\MyMenuAdaptor
          tags:
              - { name: kunstmaan_admin.menu.adaptor }
  

6. Permissions and ACL

• Initialize ACL:

  php bin/console init:acl
  

• Grant permissions to an entity:

  $maskBuilder = new MaskBuilder();
  $maskBuilder->add('view')->add('edit');
  $aclProvider->createAcl($objectIdentity)->insertObjectAce($securityIdentity, $maskBuilder->get());
  

• Check permissions in Twig:

  {% if is_granted('EDIT', node) %}
      <button>Edit</button>
  {% endif %}
  

7. Querying with ACL

• Apply ACL filters in repositories:

  public function findAllWithPermission(AclHelper $aclHelper, PermissionDefinition $permissionDef) {
      $qb = $this->createQueryBuilder('n');
      return $aclHelper->apply($qb, $permissionDef)->getResult();
  }
  

Gotchas and Tips

Pitfalls

1. ACL Initialization:

   • Forgetting to run php bin/console init:acl will break permission checks. Always initialize ACLs in a post-install script or migration.

2. Node Type Configuration:

   • Misconfiguring kunstmaan_node.node_types can lead to runtime errors. Validate your YAML syntax and ensure the entity class exists.

3. Media Paths:

   • Hardcoding media paths in templates can break when moving environments. Use the kunstmaan_media service to resolve paths dynamically:

     $mediaPath = $this->get('kunstmaan_media.manager')->getWebPath($media);
     

4. Translation Handling:

   • Translatable entities must implement TranslatableInterface and be configured in orm/translatable.yml. Missing this will cause translation fields to be ignored.

5. Workflow Transitions:

   • Workflow transitions must be defined in the configuration before use. Undefined transitions will throw exceptions.

6. Menu Adaptor Order:

   • Menu adaptors are processed in the order they are tagged. Use priority in the tag to control execution order:

     tags:
         - { name: kunstmaan_admin.menu.adaptor, priority: 10 }
     

Debugging Tips

1. Enable Debug Mode:

   • Kunstmaan CMS provides detailed logs in var/log/dev.log. Enable debug mode in config.yml:

     framework:
         profiler: { only_exceptions: false }
     

2. Check ACL Permissions:

   • Use the kunstmaan_admin.acl.debug service to dump ACL rules:

     $aclDebug = $this->get('kunstmaan_admin.acl.debug');
     $aclDebug->dump($entity);
     

3. Validate Node Types:

   • Run php bin/console debug:kunstmaan-node-types to list and validate configured node types.

4. Media Upload Issues:

   • Verify kunstmaan_media.storage configuration in config.yml and ensure the storage directory is writable.

5. Workflow State:

   • Use php bin/console debug:kunstmaan-workflow to inspect workflow states and transitions.

Extension Points

1. Custom Components:

   • Extend AbstractComponent to create reusable UI elements. Register them in kunstmaan_pagebuilder.components.

2. Custom Media Providers:

   • Implement MediaProviderInterface to integrate with external storage (e.g., AWS S3):

     class S3MediaProvider implements MediaProviderInterface {
         public function upload(File $file, string $folder) { ... }
         public function getWebPath(Media $media) { ... }
     }
     

   • Register the provider in services.yml and configure it in kunstmaan_media.storage.

3. Custom Node Fields:

   • Create custom field types by extending AbstractFieldType. Example:

     class CustomFieldType extends AbstractFieldType {
         public function getName() { return 'custom_field'; }
         public function getType() { return 'text'; }
         public function getOptions() { return []; }
     }
     

   • Register the field in kunstmaan_node.field_types.

4. Event Listeners:

   • Listen to node events (e.g., node.publish) to trigger custom logic:

     $dispatcher->addListener(NodeEvents::NODE_PUBLISH, function(NodePublishEvent $event) {
         // Custom logic on publish
     });
     

5. Override Twig Templates:

   • Override default templates by copying them from vendor/kunstmaan/bundles-cms to templates/Kunstmaan/AdminBundle/ in your bundle.

Configuration Quirks

1. Caching:

   • Kunstmaan CMS caches node types, media, and ACLs aggressively. Clear caches after configuration changes:

     php bin/console cache:clear
     

2. Environment-Specific Config:

   • Use %kernel.environment% in config.yml to load environment-specific settings:

     kunstmaan_media:
         storage:
             default:
                 adapter: local
                 options:
                     directory: %kernel.root_dir%/../media/%kernel.environment%
     

3. Version Check:

   • Disable the bundle version check in config.yml:

     parameters:
         version_checker.enabled: false