Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dacorp/extra-bundle
   

   Ensure compatibility with your Symfony version (master branch for Symfony 5+ or 1.0 branch for Symfony 2.1–2.3).

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Dacorp\ExtraBundle\DacorpExtraBundle::class => ['all' => true],
   ];
   

3. First Use Case: Image Upload

   • Create a Media entity (or extend an existing one) with fields for file paths.
   • Use the Twig template in your form:

     {% include "DacorpExtraBundle:Common:file-upload-control.html.twig" %}
     

   • Configure punkave_image_uploader in config/packages/dacorp_extra.yaml (if using the legacy uploader).

Implementation Patterns

Image Uploader Workflow

1. Entity Setup Extend your entity with traits or fields for file storage (e.g., path, alt, mimeType). Example:

   use Dacorp\ExtraBundle\Model\MediaTrait;
   
   class Product {
       use MediaTrait;
   }
   

2. Form Integration Use the provided Twig snippet in your form type:

   $builder->add('image', FileType::class, [
       'mapped' => false,
       'template' => '@DacorpExtraBundle/Common/file-upload-control.html.twig',
   ]);
   

3. Handling Uploads Inject the ImageUploaderService to process files:

   public function __construct(private ImageUploaderService $uploader) {}
   
   public function uploadImage(File $file, string $entity): string {
       return $this->uploader->upload($file, $entity);
   }
   

Meta Tags Management

1. Twig Extension Use the dacorp_extra.twig.meta extension in templates:

   {% set meta = {
       'title': 'Page Title',
       'description': 'Meta description',
       'twitter_card': 'summary_large_image',
       'og_image': 'path/to/image.jpg'
   } %}
   {{ dacorp_extra.twig.meta(meta) }}
   

2. Dynamic Meta Data Pass variables from controllers:

   return $this->render('page.html.twig', [
       'meta' => [
           'og_title' => $product->getName(),
           'twitter_site' => '@your_handle',
       ],
   ]);
   

3. Configuration Define app-specific IDs in config/packages/dacorp_extra.yaml:

   dacorp_extra:
       facebook_app_id: '123456789'
       twitter_widget_id: 'abc123'
   

Language Switching

1. Routing Extend routes with language prefixes (e.g., /en/page, /fr/page) using the bundle’s LanguageAwareRouter.

2. KnpMenu Integration Use the KnpMenuBuilder with the LanguageSwitcher action:

   $menu->addChild('Languages', ['route' => 'language_switcher'])
        ->setAttribute('lang', 'en');
   

3. Handler Setup Configure the LanguageSwitcherHandler in services:

   services:
       App\EventListener\LanguageSwitcherListener:
           tags:
               - { name: 'kernel.event_listener', event: 'kernel.request', method: 'onKernelRequest' }
   

Gotchas and Tips

Pitfalls

1. Legacy Uploader Dependency The bundle defaults to punkave_image_uploader, which is deprecated. Migrate to oneup/uploader-bundle by:

   • Replacing the Twig template with oneup_uploader.
   • Updating service configurations.

2. Symfony Version Mismatch

   • Master branch requires Symfony 5+ and FOSUserBundle/PUGXMultiUserBundle master.
   • Branch 1.0 is for Symfony 2.1–2.3. Avoid mixing branches.

3. README Rendering The README feature is dev-only. Exclude from production by:

   # config/packages/dacorp_extra.yaml
   dacorp_extra:
       readme:
           enabled: '%kernel.debug%'
   

Debugging Tips

1. Image Upload Issues

   • Check var/log/dev.log for ImageUploaderService errors.
   • Verify file permissions in public/uploads/.

2. Meta Tags Not Rendering

   • Ensure the Twig extension is loaded (check config/packages/twig.yaml for DacorpExtraBundle).
   • Validate facebook_app_id and twitter_widget_id in parameters.yml.

3. Language Switcher Failing

   • Confirm the LanguageSwitcherHandler is registered as a service.
   • Verify route names match (e.g., language_switcher).

Extension Points

1. Custom Media Model Extend MediaTrait to add fields like size or thumbnail:

   use Dacorp\ExtraBundle\Model\MediaTrait;
   
   class CustomMedia {
       use MediaTrait;
   
       #[ORM\Column]
       private ?string $thumbnailPath = null;
   }
   

2. Override Twig Templates Copy file-upload-control.html.twig to templates/bundles/DacorpExtra/Common/ for customization.

3. Add New Meta Types Extend the MetaTagExtension to support additional platforms (e.g., LinkedIn):

   // src/Twig/Extension/CustomMetaExtension.php
   class CustomMetaExtension extends \Dacorp\ExtraBundle\Twig\MetaTagExtension {
       public function getLinkedInTags(array $meta): string {
           // ...
       }
   }
   

   Register it in services.yaml:

   services:
       App\Twig\Extension\CustomMetaExtension:
           tags: ['twig.extension']