Wire Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require aequation/wire
   

   Ensure your project is using Symfony 7.2 (verified via php bin/console --version).

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

   return [
       // ...
       Aequation\WireBundle\AequationWireBundle::class => ['all' => true],
   ];
   

3. First Use Case:

   • Dependency Injection: Leverage the bundle’s base services (e.g., Aequation\WireBundle\Service\BaseService) for common logic like logging, configuration, or utility methods.
   • Configuration: Check config/packages/aequation_wire.yaml (auto-generated) for default settings. Override as needed:

     aequation_wire:
         debug: '%kernel.debug%'
         default_locale: 'en'
     

4. Key Entry Points:

   • Services: Browse src/Service/ in the bundle for reusable components.
   • Commands: Run php bin/console list aequation to see available CLI tools (e.g., aequation:debug:config).
   • Twig Extensions: Use {{ aequation_wire_utility() }} in templates for helper functions.

Implementation Patterns

Core Workflows

1. Service Integration:

   • Autowiring: Inject BaseService or domain-specific services (e.g., LoggerService) into controllers/services:

     use Aequation\WireBundle\Service\LoggerService;
     
     class MyController extends AbstractController {
         public function __construct(private LoggerService $logger) {}
     }
     

   • Extending Services: Override bundle services via compiler passes or custom bundles. Example:

     # config/services.yaml
     services:
         Aequation\WireBundle\Service\LoggerService:
             arguments:
                 $logPath: '%kernel.project_dir%/var/log/custom.log'
     

2. Configuration Management:

   • Dynamic Config: Use Aequation\WireBundle\DependencyInjection\Configuration to merge custom settings:

     $config = $this->container->getParameter('aequation_wire.config');
     

   • Environment-Specific: Override config per environment (e.g., config/packages/dev/aequation_wire.yaml).

3. CLI Automation:

   • Debugging: Run php bin/console aequation:debug:config to inspect loaded configurations.
   • Custom Commands: Extend the bundle’s command structure by creating a new command in src/Command/ and tagging it:

     // src/Command/MyCommand.php
     class MyCommand extends Command {
         protected static $defaultName = 'aequation:my:command';
     }
     

4. Twig Utilities:

   • Filters/Functions: Use built-in Twig helpers (e.g., aequation_wire_date_format) or add custom ones by extending the bundle’s TwigExtension:

     // src/Twig/AppExtension.php
     class AppExtension extends AbstractExtension {
         public function getFunctions(): array {
             return [
                 new TwigFunction('my_custom_function', [$this, 'customLogic']),
             ];
         }
     }
     

     Register in services.yaml:

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

5. Event Listeners:

   • Hook into Bundle Events: Subscribe to events like aequation.wire.init (check EventDispatcher in the bundle’s Resources/config/services.xml):

     // src/EventListener/MyListener.php
     class MyListener {
         public function onInitEvent(InitEvent $event) {
             // Custom logic
         }
     }
     

     Tag in services.yaml:

     services:
         App\EventListener\MyListener:
             tags:
                 - { name: 'kernel.event_listener', event: 'aequation.wire.init' }
     

Integration Tips

• Symfony Flex: The bundle uses Flex recipes for auto-configuration. Verify composer.json for recipe compatibility.
• Monorepos: If using a monorepo, ensure the bundle’s vendor/ path is correctly symlinked or published.
• Testing: Mock bundle services in tests by overriding container definitions:

  $container->set('Aequation\WireBundle\Service\LoggerService', $this->createMock(LoggerService::class));
  

Gotchas and Tips

Pitfalls

1. Symfony Version Mismatch:

   • The bundle is Symfony 7.2-specific. Using it with older/new versions may break autowiring or configuration.
   • Fix: Pin Symfony to 7.2.* in composer.json or fork the bundle for compatibility.

2. Configuration Overrides:

   • Silent Failures: If aequation_wire.yaml is missing, the bundle uses defaults but may log warnings. Always check var/log/dev.log.
   • Debug Mode: Set debug: true in config to enable verbose logging for troubleshooting.

3. Service Autowiring:

   • Circular Dependencies: The bundle’s BaseService may conflict with custom services of the same name. Use fully qualified names:

     use Aequation\WireBundle\Service\BaseService as WireBaseService;
     

4. Twig Extensions:

   • Namespace Collisions: If you add a Twig function with the same name as the bundle’s, the last registered one wins. Prefix custom functions (e.g., app_my_function).

5. Commands:

   • Namespace Conflicts: Ensure custom commands don’t clash with the bundle’s (e.g., avoid aequation:my:command if the bundle adds aequation:my:task).

Debugging

1. Log Inspection:

   • Enable debug mode and check var/log/dev.log for bundle-related entries. Use:

     php bin/console debug:container | grep aequation
     

   • For configuration dumps:

     php bin/console debug:config aequation_wire
     

2. Dependency Graph:

   • Visualize service dependencies with:

     php bin/console debug:container --parameters --env=dev | grep -A5 "Aequation"
     

3. Event Debugging:

   • List all dispatched events:

     php bin/console debug:event-dispatcher
     

   • Filter for bundle events:

     php bin/console debug:event-dispatcher | grep "aequation.wire"
     

Extension Points

1. Custom Services:

   • Extend the bundle’s services by creating a child class and overriding methods. Example:

     // src/Service/CustomLoggerService.php
     class CustomLoggerService extends \Aequation\WireBundle\Service\LoggerService {
         public function logCustom(string $message) {
             $this->log($message, 'custom');
         }
     }
     

   • Register in services.yaml:

     services:
         App\Service\CustomLoggerService:
             decorates: 'Aequation\WireBundle\Service\LoggerService'
             arguments: ['@App\Service\CustomLoggerService.inner']
     

2. Compiler Passes:

   • Modify the bundle’s service container at compile time by creating a pass:

     // src/DependencyInjection/Compiler/MyPass.php
     class MyPass implements CompilerPassInterface {
         public function process(ContainerBuilder $container) {
             $definition = $container->findDefinition('Aequation\WireBundle\Service\BaseService');
             $definition->addMethodCall('setCustomOption', ['value']);
         }
     }
     

   • Tag in services.yaml:

     services:
         App\DependencyInjection\Compiler\MyPass:
             tags: [{ name: 'compiler.pass' }]
     

3. Configuration Schema:

   • Extend the bundle’s configuration schema by overriding the Configuration class:

     // config/packages/aequation_wire.yaml
     imports:
         - { resource: '@AequationWireBundle/Resources/config/config.yaml' }
     aequation_wire:
         custom_option: 'value' # New key
     

   • Update the Configuration class in a custom bundle to include custom_option.

4. Twig Globals:

   • Add global variables to Twig by extending the bundle’s TwigExtension:

     // src/Twig/AppExtension.php
     class AppExtension extends \Aequation\WireBundle\Twig\BaseExtension {
         public function getGlobals(): array {
             return [
                 'app_custom_var' => 'value',
             ];
         }
     }
     

Performance Tips

1. Caching:

   • The bundle’s configuration is cached like Symfony’s. Clear cache after changes:

     php bin/console cache:clear
     

   • For dev environments, use cache:pool:clear to avoid full cache rebuilds.

2. Lazy Loading:

   • Defer non-critical bundle services until they’re first used by marking