Rocket Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require adadgio/gear-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Adadgio\GearBundle\AdadgioGearBundle::class => ['all' => true],
   ];
   

2. Basic API Auth (Basic Auth Example): Configure in config/packages/adadgio_gear.yaml:

   adadgio_gear:
       auth:
           type: Basic
           user: "your_username"
           password: "your_password"
   

3. First Use Case: Annotate a controller method to secure an endpoint:

   use Adadgio\GearBundle\Component\Api\Annotation\ApiAuth;
   
   class MyController extends AbstractController
   {
       /**
        * @ApiAuth()
        */
       public function secureEndpoint()
       {
           return $this->json(['message' => 'Access granted!']);
       }
   }
   

Implementation Patterns

API Annotations & Auth

1. Annotation-Based Security:

   • Use @ApiAuth() on controller methods to enforce authentication.
   • Supports custom providers (e.g., database-backed API keys):

     adadgio_gear:
         auth:
             provider: "app.service.api_auth_provider"
     

2. NodeRed Integration:

   • Configure NodeRed connectors in config/packages/adadgio_gear.yaml:

     adadgio_gear:
         nodered:
             enabled: true
             url: "http://nodered.example.com"
             token: "your_token"
     

   • Trigger flows via HTTP endpoints or use the Adadgio\GearBundle\Component\NodeRed\FlowRunner service.

3. CSV Handling:

   • Export:

     use Adadgio\GearBundle\Component\Csv\CsvExporter;
     
     $exporter = new CsvExporter();
     $exporter->export($data, 'output.csv');
     

   • Read:

     use Adadgio\GearBundle\Component\Csv\CsvReader;
     
     $reader = new CsvReader();
     $data = $reader->read('input.csv');
     

4. Entity Hydration:

   • Convert arrays to entities:

     use Adadgio\GearBundle\Component\Entity\Hydrator;
     
     $hydrator = new Hydrator();
     $entity = $hydrator->hydrate($arrayData, NewEntity::class);
     

5. Serializer:

   • Custom serialization/deserialization:

     use Adadgio\GearBundle\Component\Serializer\Serializer;
     
     $serializer = new Serializer();
     $json = $serializer->serialize($object);
     $object = $serializer->deserialize($json, Object::class);
     

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • The package is deprecated (last release: 2018). Use alternatives like:
     • Symfony’s built-in security components (security.yaml).
     • league/csv for CSV.
     • symfony/serializer.

2. NodeRed Integration:

   • Requires manual configuration of NodeRed server URL/token. No built-in retry logic for failed HTTP calls.
   • Tip: Use Symfony’s HttpClient for better error handling:

     $client = $this->get('http_client');
     $response = $client->request('POST', 'http://nodered.example.com/flow', [
         'headers' => ['Authorization' => 'Bearer your_token']
     ]);
     

3. Auth Configuration:

   • Basic Auth: Hardcodes credentials in config. Use environment variables or Symfony’s parameter_bag for secrets:

     adadgio_gear:
         auth:
             user: "%env(API_USER)%"
             password: "%env(API_PASSWORD)%"
     

4. CSV Handling:

   • Encoding Issues: Ensure CSV files use UTF-8 encoding to avoid garbled output.
   • Large Files: For big CSVs, stream processing is recommended (not natively supported here).

5. Entity Hydration:

   • Type Mismatches: Hydrator may fail silently if array keys don’t match entity property names. Validate input first:

     if (!array_key_exists('required_field', $data)) {
         throw new \InvalidArgumentException('Missing required field.');
     }
     

Debugging

1. Annotations Not Working:

   • Clear Symfony’s cache:

     php bin/console cache:clear
     

   • Verify annotations are loaded by checking debug:container for the api_auth_listener.

2. NodeRed Failures:

   • Check NodeRed server logs for errors. Use try-catch blocks:

     try {
         $flowRunner->run('flow_name');
     } catch (\Exception $e) {
         $this->addFlash('error', $e->getMessage());
     }
     

Extension Points

1. Custom Auth Providers:

   • Implement Adadgio\GearBundle\Component\Api\Authenticator\AuthProviderInterface:

     class CustomAuthProvider implements AuthProviderInterface
     {
         public function authenticate(Request $request): bool
         {
             // Custom logic (e.g., JWT validation)
             return true;
         }
     }
     

   • Register as a service and reference in config:

     adadgio_gear:
         auth:
             provider: "app.service.custom_auth_provider"
     

2. Serializer Extensions:

   • Override serialization logic by extending Adadgio\GearBundle\Component\Serializer\Serializer and injecting custom encoders/normalizers.

3. CSV Customization:

   • Extend CsvExporter/CsvReader to add headers, custom delimiters, or validation:

     class CustomCsvExporter extends CsvExporter
     {
         protected function configureWriter(WriterInterface $writer)
         {
             $writer->setDelimiter(';');
         }
     }