Core Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require araise/core-bundle
   

   Register the bundle in config/bundles.php:

   Araise\CoreBundle\AraiseCoreBundle::class => ['all' => true],
   

2. First Use Case: Turbo Integration Enable Turbo in config/packages/araise_core.yaml:

   araise_core:
       enable_turbo: true
   

   Use Turbo event listeners in your JavaScript:

   document.addEventListener('turbo:load', () => {
       // Handle Turbo-loaded content
   });
   

3. Key Components

   • String Conversion: Replace __toString() with StringConverter:

     use Araise\CoreBundle\Utils\StringConverter;
     $converter = new StringConverter();
     $string = $converter->convert($object);
     

   • Flash Messages: Use FlashBagException for structured flash handling:

     throw new FlashBagException('success', 'Operation completed!');
     

Implementation Patterns

Common Workflows

1. Twig Extensions Use araise_core_to_string for seamless object-to-string conversion in templates:

   {{ someObject|araise_core_to_string }}
   

2. Stimulus Controllers Leverage pre-built controllers (e.g., combobox_controller.js for Tom Select):

   // assets/controllers/combobox_controller.js
   import { Controller } from '@hotwired/stimulus';
   export default class extends Controller {
       connect() { /* ... */ }
   }
   

   Attach to HTML:

   <input data-controller="combobox">
   

3. Date Handling Use datetime_controller.js for consistent date formatting:

   // assets/controllers/datetime_controller.js
   document.addEventListener('DOMContentLoaded', () => {
       const controller = new DatetimeController();
       controller.formatDate('2023-10-01', 'MM/DD/YYYY');
   });
   

4. Input Masks Apply masks (e.g., currency, security numbers) via input-mask_controller.js:

   <input data-controller="input-mask" data-input-mask-mask="money">
   

5. Badge Formatting Standardize badges with BadgeFormatter:

   $badge = (new BadgeFormatter())->format('warning', 'Alert');
   // Output: <span class="badge bg-warning">Alert</span>
   

Integration Tips

• Dependency Injection Autowire services like StringConverter or BadgeFormatter:

  public function __construct(private StringConverter $converter) {}
  

• Configuration Inheritance CoreBundle configs (e.g., enable_turbo) cascade to dependent bundles (e.g., CrudBundle). Centralize settings in araise_core.yaml.

• Command-Line Tools Extend BaseCommand for CLI tools (avoid deprecated getContainer()):

  use Araise\CoreBundle\Command\BaseCommand;
  class MyCommand extends BaseCommand {
      protected function execute(InputInterface $input, OutputInterface $output): int {
          // Use $this->getHelper('question') for interactive CLI.
      }
  }
  

Gotchas and Tips

Pitfalls

1. Turbo Configuration Conflicts

   • Issue: Forgetting to set enable_turbo: true may break Turbo-dependent bundles (e.g., CrudBundle).
   • Fix: Explicitly enable/disable Turbo in araise_core.yaml and test event listeners (turbo:load vs. DOMContentLoaded).

2. Deprecated Methods

   • Issue: BaseCommand::getContainer() and BaseCommand::get() are deprecated. Use Symfony’s DI or helpers instead.
   • Fix: Replace with:

     $this->getApplication()->getKernel()->getContainer()->get('service_id');
     

3. Stimulus Controller Renaming

   • Issue: select_controller.js was refactored to combobox_controller.js. Old references break.
   • Fix: Update HTML attributes and imports:

     <!-- Old (broken) -->
     <input data-controller="select">
     <!-- New -->
     <input data-controller="combobox">
     

4. Flash Message Handling

   • Issue: FlashBagException requires explicit handling in controllers.
   • Fix: Catch exceptions and redirect:

     try {
         // Risky operation
     } catch (FlashBagException $e) {
         $this->addFlash($e->getType(), $e->getMessage());
         return $this->redirectToRoute('home');
     }
     

5. BackedEnum Support

   • Issue: Older versions may not handle BackedEnum in StringConverter.
   • Fix: Upgrade to v1.0.6+ or manually implement __toString() for custom enums.

Debugging Tips

• Turbo Debugging Use browser DevTools to inspect Turbo events:

  document.addEventListener('turbo:load', (event) => {
      console.log('Turbo load event:', event);
  });
  

• String Conversion Issues Verify StringConverter supports your object type. Extend it for custom classes:

  $converter->addConverter(MyClass::class, fn(MyClass $obj) => $obj->getLabel());
  

• Stimulus Controller Errors Check the browser console for missing assets. Ensure controllers are compiled (e.g., via Vite/Webpack).

Extension Points

1. Custom String Conversion Extend StringConverter for domain-specific objects:

   $converter->addConverter(User::class, fn(User $user) => "User#{$user->id}");
   

2. Badge Customization Override BadgeFormatter templates:

   {% extends '@AraiseCore/Badge/badge.html.twig' %}
   {% block badge_content %}{{ content }} (Custom){% endblock %}
   

3. Turbo Event Extensions Add custom Turbo listeners in JavaScript:

   document.addEventListener('turbo:before-fetch', (event) => {
       // Modify requests globally
   });
   

4. Input Mask Patterns Define new masks in input-mask_controller.js:

   static get masks() {
       return {
           ...super.masks,
           'custom': { pattern: '[0-9]{3}-[0-9]{2}' }
       };
   }
   

5. Flash Message Types Extend FlashBagException for custom types:

   throw new FlashBagException('custom.type', 'Message', ['key' => 'value']);
   

   Handle in Twig:

   {% if app.flashes('custom.type') %}
       <div class="alert alert-custom">{{ app.flashes('custom.type')[0] }}</div>
   {% endif %}