Shtumi Useful Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json (preferred over deps for modern Laravel/Symfony projects):

   composer require addiks/shtumi-useful-bundle
   

   Register in config/bundles.php (Symfony) or manually in Laravel via service provider (if adapted).

2. First Use Case: Ajax Autocomplete

   // In a Symfony FormBuilder
   $builder->add('user', AjaxAutocompleteType::class, [
       'entity' => User::class,
       'property' => 'email',
       'route' => 'app_user_autocomplete',
   ]);
   

   • Laravel Adaptation: Use a custom form builder (e.g., collective/html) or wrap in a Laravel-specific trait.

3. DQL Functions Enable in Doctrine via config/packages/doctrine.yaml:

   dql:
       string_functions:
           IF: Shtumi\UsefulBundle\Doctrine\DQL\IF
           IFNULL: Shtumi\UsefulBundle\Doctrine\DQL\IFNULL
   

Implementation Patterns

Form Integration

1. Ajax Autocomplete

   • Workflow:
     1. Define a route (app_user_autocomplete) returning JSON:

        // Symfony Controller
        public function autocomplete(Request $request)
        {
            return $this->get('shtumi_useful.ajax_autocomplete')->getResults(
                User::class,
                $request->query->get('q'),
                'email'
            );
        }
        

     2. Use in forms/twig:

        {{ form_widget(form.user, {'attr': {'data-autocomplete-url': path('app_user_autocomplete')}}) }}
        

   • Laravel: Replace Symfony’s FormBuilder with Laravel’s Form facade or a custom wrapper.

2. Dependent Filtered Entity

   • Example: Country → Region dropdowns.
   • Symfony:

     $builder->add('country', EntityType::class, ['class' => Country::class])
             ->add('region', DependentFilteredEntityType::class, [
                 'entity' => Region::class,
                 'property' => 'name',
                 'dependent_property' => 'country',
                 'dependent_entity' => Country::class,
             ]);
     

   • Laravel: Use a similar pattern with collective/html or a custom form component.

3. Date Range

   • Symfony:

     $builder->add('dateRange', DateRangeType::class, [
         'widget' => 'single_text', // or 'split'
         'format' => 'yyyy-MM-dd',
     ]);
     

   • Validation: Access via $form->getData() as a DateRange object.

DQL Functions

• Usage in Repositories:

  $query = $entityManager->createQuery(
      'SELECT u FROM App\Entity\User u WHERE IF(u.isActive = 1, u.name, "Inactive") = :name'
  );
  $query->setParameter('name', 'John');
  

• Laravel: Use raw DQL in Model::query() or adapt via a custom query builder trait.

Gotchas and Tips

Pitfalls

1. Symfony-Specific Assumptions

   • Form Types: Designed for Symfony’s FormBuilder. Laravel users must:
     • Extend AbstractType or wrap in a Laravel-specific form builder.
     • Manually handle route generation (e.g., path() → route()).
   • Example Fix:

     // Laravel Form Component (Blade)
     <input type="text" data-autocomplete-url="{{ route('user.autocomplete') }}">
     

2. DQL Function Registration

   • Error: Unknown DQL function 'IF'.
   • Fix: Ensure Shtumi\UsefulBundle\Doctrine\DQL classes are autoloaded and registered in Doctrine’s string_functions.

3. Ajax Autocomplete Performance

   • Issue: Slow responses with large datasets.
   • Tip:
     • Add pagination to the autocomplete route.
     • Cache results (e.g., Redis or Symfony Cache).

4. Dependent Filtered Entity

   • Issue: Blank dropdowns if dependent entity isn’t selected.
   • Fix: Use required: false and handle empty states in JS:

     $('#form_country').change(function() {
         if (!this.value) $('#form_region').empty();
     });
     

Debugging

1. Form Type Errors

   • Check if the bundle is registered in Kernel.php (Symfony) or AppServiceProvider (Laravel).
   • Verify entity classes are fully qualified (e.g., App\Entity\User).

2. DQL Errors

   • Test functions in a raw query first:

     $query = $entityManager->createNativeQuery('SELECT IF(1=1, "Yes", "No")');
     

Extension Points

1. Custom Autocomplete Sources

   • Extend Shtumi\UsefulBundle\Form\Type\AjaxAutocompleteType to support non-entity data (e.g., API responses).

2. Date Range Widgets

   • Override Twig templates in templates/ShtumiUsefulBundle/Form/date_range.html.twig.

3. DQL Functions

   • Add new functions by extending Shtumi\UsefulBundle\Doctrine\DQL\AbstractFunction and registering them in the bundle’s Resources/config/doctrine.yaml.

Laravel-Specific Tips

• Service Provider: Create a provider to bridge Symfony components:

  public function register()
  {
      $this->app->singleton('shtumi.useful.ajax_autocomplete', function ($app) {
          return new \Shtumi\UsefulBundle\Service\AjaxAutocompleteService(
              $app['doctrine.orm.entity_manager']
          );
      });
  }
  

• Blade Integration: Use @stack('scripts') to load JS dependencies for autocomplete.