Getting Started

Minimal Setup

Installation

composer require druidvav/essentials-bundle

Add to config/bundles.php:

return [
    // ...
    Druidvav\EssentialsBundle\DruidvavEssentialsBundle::class => ['all' => true],
];

First Use Case: Twig Extensions The bundle provides a TwigExtension for common utilities. Enable it in config/packages/twig.yaml:

twig:
    extensions:
        - Druidvav\EssentialsBundle\Twig\EssentialsExtension

Use in templates:

{{ 'hello world'|upper }}
{{ '2023-01-01'|relativeTime }}

First Use Case: Form Types Extend Symfony forms with custom types:

use Druidvav\EssentialsBundle\Form\Type\AutoCompleteType;

$builder->add('search', AutoCompleteType::class, [
    'choices' => $choices,
    'placeholder' => 'Search...',
]);

Implementation Patterns

Twig Utilities

Common Filters/Functions Leverage built-in Twig extensions for:
- String manipulation (upper, lower, slugify).
- Date formatting (relativeTime, formatDate).
- Array helpers (pluck, keyBy). Example:
```
{% set users = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}] %}
{{ users|pluck('name') }}  {# Output: ['Alice', 'Bob'] #}
```

Custom Extensions Extend the EssentialsExtension for project-specific needs:

namespace App\Twig;

use Druidvav\EssentialsBundle\Twig\EssentialsExtension as BaseExtension;

class AppExtension extends BaseExtension
{
    public function getFunctions()
    {
        return array_merge(parent::getFunctions(), [
            new \Twig\TwigFunction('appFunction', [$this, 'appFunction']),
        ]);
    }

    public function appFunction($input)
    {
        return "Processed: {$input}";
    }
}

twig:
    extensions:
        - App\Twig\AppExtension

Form Integration

AutoCompleteType Use for search-as-you-type inputs:

$builder->add('tags', AutoCompleteType::class, [
    'choices' => $tagRepository->findAll(),
    'choice_label' => 'name',
    'min_input_length' => 2,
    'placeholder' => 'Add tags...',
]);

Frontend: Requires JavaScript (e.g., Select2) for dynamic loading.

Custom Validation Extend form types with validation rules:

use Symfony\Component\Validator\Constraints as Assert;

$builder->add('email', TextType::class, [
    'constraints' => [
        new Assert\Email(),
        new Assert\NotBlank(),
    ],
]);

Dynamic Forms Use FormEvent listeners to modify forms dynamically:

$form->addEventListener(FormEvents::PRE_SET_DATA, function (FormEvent $event) {
    $data = $event->getData();
    $event->getForm()->add('dynamic_field', TextType::class, [
        'required' => $data->isRequired(),
    ]);
});

Event Listeners/Subscribers

Global Events Subscribe to Symfony events (e.g., kernel.request) for cross-cutting logic:

namespace App\EventListener;

use Druidvav\EssentialsBundle\Event\EssentialsEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class AppSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            EssentialsEvents::PRE_RENDER => 'onPreRender',
        ];
    }

    public function onPreRender()
    {
        // Modify response before rendering
    }
}

services:
    App\EventListener\AppSubscriber:
        tags: ['kernel.event_subscriber']

Dependency Injection

Service Integration Inject the bundle’s services into your controllers/services:

use Druidvav\EssentialsBundle\Service\EssentialsService;

class MyController extends AbstractController
{
    public function __construct(private EssentialsService $essentials)
    {
    }

    public function index()
    {
        $this->essentials->slugify('Hello World'); // Returns 'hello-world'
    }
}

Gotchas and Tips

Twig Pitfalls

Namespace Conflicts If extending EssentialsExtension, ensure your class name doesn’t conflict with existing Twig functions/filters. Prefix with your bundle name (e.g., AppEssentialsExtension).
Caching Twig extensions are cached. Clear the cache after adding new extensions:
```
php bin/console cache:clear
```
Deprecated Features The bundle is outdated (last release 2017). Some Symfony/Twig features may not be compatible. Test thoroughly in your environment.

Form Type Quirks

JavaScript Dependencies AutoCompleteType requires frontend libraries (e.g., Select2). Ensure they’re loaded:
```
{{ include('bundles/essentials/js/select2.html.twig') }}
```

Validation Groups Explicitly define validation groups for complex forms:

$builder->add('fields', CollectionType::class, [
    'entry_type' => TextType::class,
    'validation_groups' => ['Default', 'custom_group'],
]);

CSRF Protection Custom form types may bypass CSRF protection. Ensure _csrf_token is included:

$builder->add('hidden', HiddenType::class, [
    'mapped' => false,
    'data' => $form->getCsrfToken(),
]);

Debugging Tips

Twig Errors Enable Twig debug mode in config/packages/twig.yaml:
```
twig:
    debug: true
    strict_variables: true
```
Form Debugging Use Symfony’s form profiler:
```
php bin/console debug:form your_form_name
```
Or dump form data in a controller:
```
dump($form->getData());
```
Event Dispatcher Verify event subscribers are loaded:
```
php bin/console debug:event-dispatcher
```

Extension Points

Custom Twig Filters Add project-specific filters by extending EssentialsExtension:

class CustomExtension extends EssentialsExtension
{
    public function getFilters()
    {
        return array_merge(parent::getFilters(), [
            new \Twig\TwigFilter('customFilter', [$this, 'customFilterMethod']),
        ]);
    }
}

Override Form Types Replace default form types (e.g., AutoCompleteType) by creating a custom version:

namespace App\Form\Type;

use Druidvav\EssentialsBundle\Form\Type\AutoCompleteType as BaseType;

class AutoCompleteType extends BaseType
{
    public function configureOptions(OptionsResolver $resolver)
    {
        parent::configureOptions($resolver);
        $resolver->setDefaults([
            'custom_option' => true,
        ]);
    }
}

Update services.yaml to autowire your custom type.

Performance

Lazy-Loading Extensions For large projects, lazy-load Twig extensions:

twig:
    extensions:
        - '@app.twig.extension'  # Loaded on demand

Form Fragment Caching Cache form fragments to reduce overhead:

{% cache 'form_fragment' %}
    {{ form_start(form) }}
    {{ form_widget(form) }}
    {{ form_end(form) }}
{% endcache %}

Essentials Bundle Laravel Package