Tools Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer require austral/tools-bundle
   

   Ensure your config/bundles.php includes:

   Austral\ToolsBundle\AustralToolsBundle::class => ['all' => true],
   

2. First Use Case:

   • Twig Extensions: Access helper functions in Twig templates:

     {{ dump(austral_tools.uuid()) }}  {# Generates a UUID #}
     {{ austral_tools.dot_notation('user.address.city') }}  {# Dot notation parsing #}
     

   • Console Commands: Run built-in commands:

     php bin/console austral:tools:generate-uuid
     

3. Where to Look First:

   • Documentation: Check the GitHub README for quick-start guides.
   • Twig Extensions: Explore Austral\ToolsBundle\Twig\AustralToolsExtension for available filters/functions.
   • Abstract Classes: Review Austral\ToolsBundle\Abstracts\AbstractTool for reusable logic patterns.

Implementation Patterns

Common Workflows

1. Reusable Tool Logic: Extend AbstractTool to create domain-specific utilities:

   namespace App\Tools;
   
   use Austral\ToolsBundle\Abstracts\AbstractTool;
   
   class UserTool extends AbstractTool
   {
       public function formatName(string $firstName, string $lastName): string
       {
           return ucfirst($firstName) . ' ' . strtoupper($lastName);
       }
   }
   

   Register in services.yaml:

   services:
       App\Tools\UserTool: ~
   

2. Twig Integration: Use the bundle’s Twig extensions for frontend logic:

   {# Format a date with custom rules #}
   {{ austral_tools.format_date('2024-07-24', 'Y-m-d H:i') }}
   
   {# Serialize complex objects #}
   {{ austral_tools.serialize(user) | raw }}
   

3. Dot Notation Parsing: Parse nested arrays/objects dynamically:

   $value = austral_tools.dot_notation('user.profile.settings.notifications', $data);
   

4. UUID Generation: Generate UUIDs in controllers or services:

   use Austral\ToolsBundle\Services\UuidService;
   
   class UserController extends Controller
   {
       public function __construct(private UuidService $uuidService) {}
   
       public function create()
       {
           $uuid = $this->uuidService->generate();
           // Use $uuid in your logic
       }
   }
   

5. Console Automation: Leverage built-in commands for repetitive tasks:

   # Generate UUIDs in bulk
   php bin/console austral:tools:generate-uuid --count=10
   
   # Validate YAML files
   php bin/console austral:tools:validate-yaml path/to/file.yaml
   

Integration Tips

• Symfony Events: Bind tool methods to Symfony events (e.g., KernelEvents::TERMINATE) for post-processing.
• Dependency Injection: Prefer constructor injection for AustralToolsExtension or UuidService in services/controllers.
• Custom Twig Filters: Extend AustralToolsExtension to add project-specific Twig functions:

  public function getFunctions()
  {
      return [
          new \Twig\TwigFunction('custom_function', [$this, 'customFunction']),
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Collisions: The bundle’s AbstractTool may conflict with existing Tool classes. Rename or alias if needed:

   services:
       Austral\ToolsBundle\Abstracts\AbstractTool: alias: austral.tools.abstract_tool
   

2. Twig Auto-Reloading: Clear Twig cache after adding new extensions:

   php bin/console cache:clear
   

3. UUID Generation:

   • The UuidService uses ramsey/uuid. Ensure your PHP version (8.0+) supports it.
   • Avoid generating UUIDs in loops without batching (performance impact).

4. Dot Notation Edge Cases:

   • Nested keys with null values may throw exceptions. Validate input:

     if (empty($data['user']['profile'])) {
         return null;
     }
     

5. Doctrine Extensions: The bundle requires gedmo/doctrine-extensions. Install separately if missing:

   composer require gedmo/doctrine-extensions
   

Debugging

• Twig Errors: Enable Twig debug mode in config/packages/twig.yaml:

  twig:
      debug: '%kernel.debug%'
      strict_variables: '%kernel.debug%'
  

  Check var/log/dev.log for Twig-specific errors.

• Console Command Issues: Use --verbose for detailed output:

  php bin/console austral:tools:generate-uuid --verbose
  

Configuration Quirks

1. Environment Variables: The bundle uses symfony/dotenv. Ensure .env files are loaded:

   // config/packages/framework.yaml
   framework:
       env:
           enabled: true
   

2. YAML Validation: The validate-yaml command may fail on malformed files. Pre-validate with:

   php bin/console debug:container Austral\ToolsBundle\Validator\YamlValidator
   

Extension Points

1. Custom Abstract Tools: Override AbstractTool methods like sanitizeInput() for project-specific validation.

2. Twig Extensions: Subclass AustralToolsExtension to add filters:

   class CustomAustralToolsExtension extends AustralToolsExtension
   {
       public function getFilters()
       {
           return [
               new \Twig\TwigFilter('custom_filter', [$this, 'customFilter']),
           ];
       }
   }
   

   Register in services.yaml:

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

3. Console Commands: Extend AustralToolsCommand to add custom logic:

   namespace App\Command;
   
   use Austral\ToolsBundle\Command\AustralToolsCommand;
   
   class CustomToolCommand extends AustralToolsCommand
   {
       protected function configure()
       {
           $this->setName('app:custom-tool');
       }
   
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           // Custom logic
       }
   }
   

4. Serializer Groups: Configure symfony/serializer groups in config/packages/serializer.yaml:

   framework:
       serializer:
           mapping:
               paths: ['%kernel.project_dir%/config/serializer']
   

   Create config/serializer/AustralTools.yaml:

   Austral\ToolsBundle\Dto\ExampleDto:
       attributes:
           id:
               groups: ['api']