Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your Symfony project via Composer:

   composer require akyos/core-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Akyos\CoreBundle\AkyosCoreBundle::class => ['all' => true],
   ];
   

2. First Use Case: Pagination The bundle integrates knp-paginator-bundle. Use it in a controller:

   use Knp\Component\Pager\PaginatorInterface;
   
   class ProductController extends AbstractController
   {
       public function list(PaginatorInterface $paginator, EntityManagerInterface $em): Response
       {
           $products = $em->getRepository(Product::class)->findAll();
           $pagination = $paginator->paginate(
               $products,
               $this->getPageParameter(),
               10 // items per page
           );
           return $this->render('product/list.html.twig', ['pagination' => $pagination]);
       }
   }
   

   Render in Twig:

   {% for product in pagination %}
       {{ product.name }}
   {% endfor %}
   {{ knp_pagination_render(pagination) }}
   

3. Recaptcha3 Integration Configure in config/packages/karser_recaptcha3.yaml:

   karser_recaptcha3:
       site_key: '%env(RECAPTCHA_SITE_KEY)%'
       secret_key: '%env(RECAPTCHA_SECRET_KEY)%'
   

   Use in a form type:

   use Karser\Recaptcha3Bundle\Form\Type\Recaptcha3Type;
   
   $builder->add('recaptcha', Recaptcha3Type::class);
   

Implementation Patterns

Common Workflows

1. Doctrine Extensions Leverage beberlei/doctrineextensions and stof/doctrine-extensions-bundle for behaviors like:

   • Sluggable entities:

     use Gedmo\Mapping\Annotation as Gedmo;
     
     /**
      * @Gedmo\Slug(fields={"name"})
      */
     private $slug;
     

   • Timestampable entities (automatic createdAt/updatedAt):

     use Gedmo\Mapping\Annotation as Gedmo;
     
     /**
      * @Gedmo\Timestampable(on="create")
      */
     private $createdAt;
     

2. CSV Handling Use league/csv for imports/exports:

   use League\Csv\Writer;
   
   $csv = Writer::createFromString('');
   $csv->insertOne(['id', 'name']);
   $csv->output('data.csv');
   

3. CKEditor Integration Configure in config/packages/fos_ckeditor.yaml:

   fos_ck_editor:
       base_path: /bundles/akyoscore
       config: []
       file_converter:
           enabled: true
           allowed_extensions: ['pdf']
           allowed_mime_types: ['application/pdf']
   

   Use in a form:

   $builder->add('content', CKEditorType::class);
   

4. Email Templates Use Symfony Mailer with Twig templates:

   $email = (new Email())
       ->from(new Address('contact@example.com', 'Contact'))
       ->to($user->getEmail())
       ->subject('Welcome!')
       ->html($this->renderView('emails/welcome.html.twig', ['user' => $user]));
   $mailer->send($email);
   

Integration Tips

• Fixtures: Use doctrine/doctrine-fixtures-bundle for testing:

  php bin/console doctrine:fixtures:load
  

• Webpack Encore: Configure assets in assets/app.js:

  import './styles/app.scss';
  Encore
      .enableSassLoader()
      .enablePostCssLoader()
      .addEntry('app', './assets/app.js')
      .splitEntry('app')
      .configureBabel(() => {})
      .configureBabelPresetEnv((config) => {
          config.useBuiltIns = 'usage';
          config.corejs = 3;
      })
      .enableSingleRuntimeChunk()
      .cleanupOutputBeforeBuild()
      .enableSourceMaps(!Encore.isProduction())
      .enableVersioning(Encore.isProduction())
      .enableVertexAIPlugin();
  

  Build assets:

  npm run dev
  

Gotchas and Tips

Pitfalls

1. Recaptcha3 Validation Ensure karser_recaptcha3 is properly configured in .env:

   RECAPTCHA_SITE_KEY=your_site_key
   RECAPTCHA_SECRET_KEY=your_secret_key
   

   Debug failed validations with:

   $recaptcha = $form->get('recaptcha')->getData();
   if (!$recaptcha->isValid()) {
       $this->addFlash('error', 'Recaptcha failed: ' . $recaptcha->getError());
   }
   

2. Doctrine Extensions Conflicts If Sluggable or Timestampable behaviors don’t work:

   • Ensure stof/doctrine-extensions-bundle is loaded after DoctrineBundle in bundles.php.
   • Clear cache:

     php bin/console cache:clear
     

3. CSV Encoding Issues Use UTF-8 encoding explicitly:

   $csv->setDelimiter(';')
       ->setEnclosure('"')
       ->setLineEnding("\n")
       ->setOutputEncoding('UTF-8');
   

4. CKEditor File Uploads Configure fos_ck_editor file converter paths:

   fos_ck_editor:
       file_converter:
           directory: '%kernel.project_dir%/public/uploads/ckeditor'
           url: '/uploads/ckeditor'
   

   Ensure the directory is writable:

   chmod -R 775 public/uploads/ckeditor
   

Debugging Tips

• Paginator Debugging Dump pagination data in Twig:

  {{ dump(pagination) }}
  

  Or in a controller:

  $this->addFlash('debug', print_r($pagination->getItems(), true));
  

• Doctrine Events Listen for lifecycle events (e.g., prePersist) to debug extensions:

  use Doctrine\ORM\Event\LifecycleEventArgs;
  
  $entity->addLifecycleListener(function ($entity, LifecycleEventArgs $args) {
      $this->logger->debug('Event: ' . $args->getEventName(), ['entity' => $entity]);
  });
  

Extension Points

1. Custom Paginator Twig Extensions Extend knp_pagination in Twig:

   {% macro render(pagination, template='KnpPaginatorBundle:Pagination:sliding.html.twig') %}
       {% set pagination = knp_paginator_render(pagination, template) %}
       {{ pagination|replace({'class="pagination"': 'class="custom-pagination"'}) }}
   {% endmacro %}
   

2. Recaptcha3 Custom Logic Override validation in a form type:

   use Karser\Recaptcha3Bundle\Validator\Constraints as RecaptchaAssert;
   
   $builder->add('recaptcha', Recaptcha3Type::class, [
       'constraints' => [
           new RecaptchaAssert\ValidRecaptcha3([
               'message' => 'Custom error message',
           ]),
       ],
   ]);
   

3. Doctrine Extensions Custom Behaviors Create a custom behavior (e.g., SoftDeletable):

   use Gedmo\Mapping\Annotation as Gedmo;
   
   /**
    * @Gedmo\SoftDeleteable(fieldName="deletedAt")
    */
   private $deletedAt;
   

   Register in config/packages/doctrine.yaml:

   gedmo_listenable:
       entity_manager: ~
   

4. CSV Custom Writers Extend league/csv for domain-specific formats:

   class ProductCsvWriter extends Writer
   {
       public function writeProduct(Product $product)
       {
           $this->insertOne([
               'id' => $product->getId(),
               'name' => $product->getName(),
               'price' => $product->getPrice(),
           ]);
       }
   }