Crowdentials Api Wrapper Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require crowdvalley/crowdentials-api-wrapper-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       CrowdValley\CrowdentialsApiWrapperBundle\CrowdentialsApiWrapperBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console crowdentials:install
   

   Update config/packages/crowdentials_api_wrapper.yaml with your API credentials:

   crowdentials_api_wrapper:
       api_key: '%env(CROWDENTIALS_API_KEY)%'
       api_secret: '%env(CROWDENTIALS_API_SECRET)%'
       base_uri: 'https://api.crowdvalley.com'
   

3. First Use Case: Authentication Inject the client into a service/controller:

   use CrowdValley\CrowdentialsApiWrapper\Client;
   
   class AuthController extends AbstractController {
       public function __construct(private Client $client) {}
   
       public function login(Request $request) {
           $response = $this->client->auth()->login([
               'email' => $request->request->get('email'),
               'password' => $request->request->get('password'),
           ]);
           // Handle response
       }
   }
   

Implementation Patterns

Common Workflows

1. Service Layer Integration Create a dedicated service to abstract API calls:

   namespace App\Service;
   
   use CrowdValley\CrowdentialsApiWrapper\Client;
   
   class CrowdentialsService {
       public function __construct(private Client $client) {}
   
       public function verifyEmail(string $token): bool {
           return $this->client->auth()->verifyEmail($token)->isSuccess();
       }
   }
   

2. Event-Driven Extensions Listen to Crowdentials events (e.g., CrowdentialsEvent::USER_CREATED) via Symfony’s event dispatcher:

   # config/services.yaml
   services:
       App\EventListener\CrowdentialsListener:
           tags:
               - { name: kernel.event_listener, event: crowdentials.user.created, method: onUserCreated }
   

3. Form Integration Use Crowdentials validators in Symfony forms:

   use CrowdValley\CrowdentialsApiWrapper\Validator\Constraints as CrowdentialsAssert;
   
   $builder->add('email', EmailType::class, [
       'constraints' => [
           new CrowdentialsAssert\EmailExists(),
       ],
   ]);
   

4. Command-Line Operations Create console commands for bulk operations:

   use CrowdValley\CrowdentialsApiWrapper\Client;
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class SyncUsersCommand extends Command {
       protected static $defaultName = 'crowdentials:sync-users';
   
       public function __construct(private Client $client) {}
   
       protected function execute(InputInterface $input, OutputInterface $output): int {
           $users = $this->client->users()->list(['limit' => 100]);
           // Process users...
       }
   }
   

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • The API enforces rate limits (e.g., 60 requests/minute). Cache responses aggressively for read-heavy operations:

     $this->client->users()->list(['cache' => true]); // Uses Symfony cache system
     

2. Token Expiry

   • Authentication tokens expire after 1 hour. Handle TokenExpiredException gracefully:

     try {
         $this->client->auth()->me();
     } catch (\CrowdValley\CrowdentialsApiWrapper\Exception\TokenExpiredException $e) {
         $this->client->auth()->refreshToken();
         // Retry logic
     }
     

3. Webhook Validation

   • Always validate webhook signatures using the CrowdentialsWebhookValidator:

     $validator = new \CrowdValley\CrowdentialsApiWrapper\Webhook\Validator(
         $this->client->getConfig()->getApiSecret()
     );
     if (!$validator->validate($request->getContent(), $request->headers->get('X-Signature'))) {
         throw new \RuntimeException('Invalid webhook signature');
     }
     

Tips

1. Logging Enable debug logging for API calls in config/packages/crowdentials_api_wrapper.yaml:

   crowdentials_api_wrapper:
       debug: '%kernel.debug%'
   

2. Testing Use the CrowdentialsApiWrapperBundleTestCase for unit tests:

   use CrowdValley\CrowdentialsApiWrapperBundle\Tests\CrowdentialsApiWrapperBundleTestCase;
   
   class MyTest extends CrowdentialsApiWrapperBundleTestCase {
       public function testSomething() {
           $this->assertTrue(true);
       }
   }
   

3. Custom Endpoints Extend the client for private endpoints:

   namespace App\Service;
   
   use CrowdValley\CrowdentialsApiWrapper\Client;
   use CrowdValley\CrowdentialsApiWrapper\Endpoint\AbstractEndpoint;
   
   class CustomEndpoint extends AbstractEndpoint {
       protected $uri = 'custom/endpoint';
   }
   
   // Register in services.yaml:
   services:
       App\Service\CustomEndpoint:
           arguments:
               $client: '@crowdentials.client'
   

4. Environment-Specific Config Override config per environment (e.g., config/packages/dev/crowdentials_api_wrapper.yaml):

   crowdentials_api_wrapper:
       base_uri: 'https://sandbox.api.crowdvalley.com'
   

5. Error Handling Centralize API error handling with a decorator:

   use CrowdValley\CrowdentialsApiWrapper\ClientInterface;
   use CrowdValley\CrowdentialsApiWrapper\Exception\ApiException;
   
   class DecoratedClient implements ClientInterface {
       public function __construct(private ClientInterface $client) {}
   
       public function call(string $method, string $uri, array $params = []) {
           try {
               return $this->client->call($method, $uri, $params);
           } catch (ApiException $e) {
               // Log, translate, or retry
               throw new \RuntimeException('API Error: ' . $e->getMessage());
           }
       }
   }