Utils Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aequation/utils
   

   This installs the package and its dependencies (including Symfony 7.2+ compatibility).

2. First Use Case: The package provides utility classes for common Symfony tasks. Start by importing the core utility class:

   use Aequation\Utils\Utils;
   

   Example: Generate a UUID (if included in the package):

   $uuid = Utils::generateUuid();
   

3. Where to Look First:

   • src/Utils.php: Core utility methods (check for generateUuid(), slugify(), or sanitizeInput()).
   • README.md: Verify if the package includes controllers/assets (e.g., AssetController for file handling).
   • config/packages/aequation_utils.yaml: Check for default configurations (e.g., allowed file types, cache settings).

Implementation Patterns

Common Workflows

1. Asset Handling (if included):

   // Upload a file (hypothetical example)
   $filePath = Utils::uploadAsset(
       $request->file('file'),
       'uploads',
       ['jpg', 'png'] // Allowed extensions
   );
   

2. Data Sanitization:

   $cleanInput = Utils::sanitizeInput($userInput, ['strip_tags', 'trim']);
   

3. Controller Integration:

   use Aequation\Utils\Controller\AssetController;
   
   // Inject into your controller
   public function __construct(private AssetController $assetController) {}
   
   public function upload(Request $request) {
       return $this->assetController->handleUpload($request);
   }
   

4. Configuration Overrides: Override defaults in config/packages/aequation_utils.yaml:

   aequation_utils:
       upload_dir: 'custom_uploads'
       allowed_extensions: ['pdf', 'docx']
   

Integration Tips

• Symfony Forms: Use utility methods in form type classes for validation/sanitization.
• Event Listeners: Hook into kernel.request to pre-process input with Utils::sanitizeInput().
• Twig Extensions: Expose utilities to templates (if the package supports it):

  // src/Twig/AppExtension.php
  public function getFunctions() {
      return [
          new \Twig\TwigFunction('generate_uuid', [Utils::class, 'generateUuid']),
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Symfony Version Lock:

   • The package targets Symfony 7.2+. Ensure your project matches this version or risk compatibility issues.
   • Fix: Pin Symfony version in composer.json if downgrading:

     "symfony/*": "7.2.*"
     

2. Undocumented Methods:

   • The package has 0 stars/dependents, so some methods may lack examples or edge-case handling.
   • Tip: Inspect Utils.php for @method annotations or test the package locally with phpunit.

3. Configuration Overrides:

   • Default configs might not be loaded if the package lacks a proper Extension class.
   • Fix: Manually merge configs in config/packages/aequation_utils.yaml:

     imports:
         - { resource: '@AequationUtilsBundle/Resources/config/services.yaml' }
     

4. Asset Permissions:

   • If using file uploads, ensure the upload_dir is writable:

     chmod -R 775 config/uploads
     

Debugging Tips

• Enable Debug Mode:

  // config/packages/dev/aequation_utils.yaml
  aequation_utils:
      debug: true
  

  (Check if the package supports this.)

• Log Utility Calls:

  Utils::setLogger($logger); // If supported
  

Extension Points

1. Custom Utilities: Extend the Utils class:

   namespace App\Utils;
   
   use Aequation\Utils\Utils as BaseUtils;
   
   class AppUtils extends BaseUtils {
       public static function customMethod() { ... }
   }
   

2. Event Subscribers: Listen for package events (if documented):

   // config/services.yaml
   App\EventListener\AssetUploadListener:
       tags:
           - { name: 'kernel.event_subscriber' }
   

3. Twig Filters: Add custom filters to Twig:

   // src/Twig/AppExtension.php
   public function getFilters() {
       return [
           new \Twig\TwigFilter('custom_filter', [Utils::class, 'customMethod']),
       ];
   }