Gear 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): Configure config/packages/adadgio_gear.yaml:

   adadgio_gear:
       auth:
           type: Basic
           user: "admin"
           password: "secure123"
   

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

   use Adadgio\GearBundle\Component\Api\Annotation\ApiAuth;
   
   class MyController extends AbstractController
   {
       /**
        * @ApiAuth()
        */
       public function secureEndpoint()
       {
           return new JsonResponse(['data' => 'protected']);
       }
   }
   

Implementation Patterns

API Endpoints with Annotations

• Workflow:

  1. Annotate controller methods with @ApiAuth().
  2. Configure auth type (Basic, custom service, etc.) in adadgio_gear.yaml.
  3. Use dependency injection for custom auth logic (e.g., database-backed tokens).

• Example: Custom Auth Provider:

  adadgio_gear:
      auth:
          type: ~
          provider: "adadgio_gear.api.authenticator_db_service"
  

  Define the service in services.yaml:

  services:
      adadgio_gear.api.authenticator_db_service:
          class: App\Service\CustomAuthProvider
          arguments: ['@doctrine.orm.entity_manager']
  

CSV Data Handling

• CSV Export: Use the CsvExporter service to generate CSV files from arrays or Doctrine collections:

  $exporter = $this->get('adadgio_gear.csv.exporter');
  $csvData = $exporter->export($arrayOfData, ['header1', 'header2']);
  file_put_contents('output.csv', $csvData);
  

• CSV Import: Parse CSV files into arrays or hydrate entities:

  $reader = $this->get('adadgio_gear.csv.reader');
  $csvData = $reader->read('input.csv');
  

Entity Hydration

• Hydrate from Array: Convert flat arrays into Doctrine entities:

  $hydrator = $this->get('adadgio_gear.entity.hydrator');
  $entity = $hydrator->hydrate($arrayData, User::class);
  

Node-RED Integration

• Configure Node-RED Connector:

  adadgio_gear:
      nodered:
          url: "http://nodered.local:1880"
          auth:
              type: Basic
              user: "nodered"
              password: "password"
  

• Trigger Flows: Use the FlowExecutor service to send data to Node-RED:

  $executor = $this->get('adadgio_gear.nodered.flow_executor');
  $executor->execute('my-flow-id', ['key' => 'value']);
  

Gotchas and Tips

Deprecation Warning

• Status: The package is deprecated (last release: 2018). Use alternatives like:
  • API Auth: lexik/jwt-authentication-bundle or nelmio/api-doc-bundle.
  • CSV Handling: league/csv or php-console/csv.
  • Node-RED: Official Node-RED PHP client.

Common Pitfalls

1. Annotation Parsing:

   • Ensure annotations are parsed by Symfony’s annotation reader. If using PHP 8+, add:

     framework:
         annotations: true
     

   • For custom auth providers, verify the service is tagged as an authenticator:

     tags: ['adadgio_gear.authenticator']
     

2. CSV Encoding:

   • Specify encoding explicitly in CsvReader/CsvExporter to avoid UTF-8/BOM issues:

     $reader->setEncoding('UTF-8');
     

3. Entity Hydration:

   • Hydration fails silently if the array keys don’t match entity property names. Use setPropertyMapping():

     $hydrator->setPropertyMapping([
         'user_email' => 'email', // Map array key to entity property
     ]);
     

Debugging Tips

• Auth Failures: Enable debug mode and check Symfony’s profiler for 401 Unauthorized errors. Verify:

  • Auth config in adadgio_gear.yaml.
  • Annotations are correctly applied to routes/controllers.

• Node-RED Connectivity: Test the Node-RED URL manually (e.g., curl http://nodered.local:1880). Use GuzzleHttp for debugging:

  $client = new \GuzzleHttp\Client();
  $response = $client->get('http://nodered.local:1880');
  

Extension Points

• Custom Auth Logic: Extend Adadgio\GearBundle\Component\Api\Authenticator\AbstractAuthenticator for bespoke auth:

  class DatabaseAuthenticator extends AbstractAuthenticator
  {
      public function authenticate(Request $request)
      {
          // Custom logic (e.g., check DB for API keys)
      }
  }
  

• Serializer Extensions: Override the default serializer by configuring a custom service:

  adadgio_gear:
      serializer:
          class: App\Service\CustomSerializer