ConnectorAbstract

Overview #

ConnectorAbstract is the base class for all connectors in the Orchesty PHP SDK. A connector represents a reusable component that performs a specific action, typically interacting with external APIs or services. You extend this class when creating connectors that process data and make HTTP requests.

File location: orchesty-php-sdk/src/Connector/ConnectorAbstract.php

Developer workflow: Connectors are the most common component developers create. They process data using ProcessDto, make HTTP requests via CurlManager, and often require authentication via ApplicationInstall.

Class Hierarchy # 

CommonNodeAbstract (extends)
  ↳ ConnectorAbstract

Implements: ConnectorInterface, CommonNodeInterface

Uses traits:

  • ConnectorTrait - Provides HTTP client management and status code evaluation
  • CommonNodeTrait - Provides application management and authentication

Constructor # 

public function __construct(ApplicationInstallRepository $applicationInstallRepository)

Parameters #

ParameterTypeDescription
$applicationInstallRepositoryApplicationInstallRepositoryRepository for accessing application installations and credentials

The constructor is automatically called by Symfony's dependency injection container when your connector is instantiated.

Abstract Methods #

You must implement the following abstract methods when extending ConnectorAbstract:

getName() # 

abstract public function getName(): string

Returns a unique identifier for your connector. This name is used for registration and routing.

Example # 

public function getName(): string
{
    return 'hubspot-create-contact';
}

processAction() # 

abstract public function processAction(ProcessDto $dto): ProcessDto

The main entry point for your connector's logic. Receives incoming data via ProcessDto, processes it (often making HTTP requests), and returns the modified ProcessDto.

Parameters #

ParameterTypeDescription
$dtoProcessDtoThe data transfer object containing headers, body, and user information

Returns #

ProcessDto - The modified process DTO with response data

Throws #

ConnectorException - When connector operations fail

Methods from ConnectorTrait #

getSender() # 

protected function getSender(): CurlManagerInterface

Gets the HTTP client for making requests.

Returns #

CurlManagerInterface - The HTTP client instance

Throws #

ConnectorException - If sender is not set

setSender() # 

public function setSender(CurlManagerInterface $sender): self

Sets the HTTP client (automatically injected by dependency injection).

Parameters #

ParameterTypeDescription
$senderCurlManagerInterfaceThe HTTP client instance

Returns #

self - For method chaining

evaluateStatusCode() # 

public function evaluateStatusCode(
    int $statusCode, 
    ProcessDtoAbstract $dto, 
    ?string $message = null
): bool

Evaluates HTTP response status codes and handles failures. Default acceptable status codes are 200 and 201.

Parameters #

ParameterTypeDescription
$statusCodeintThe HTTP status code to evaluate
$dtoProcessDtoAbstractThe process DTO to mark as failed if needed
$messagestring|nullOptional custom error message

Returns #

bool - True if status code is acceptable, false otherwise

Example # 

$response = $this->getSender()->send($request);
$statusCode = $response->getStatusCode();

if (!$this->evaluateStatusCode($statusCode, $dto)) {
    return $dto; // DTO is already marked as failed
}

Methods from CommonNodeTrait #

getApplication() # 

public function getApplication(): ApplicationInterface

Gets the associated application instance (for authentication).

Returns #

ApplicationInterface - The application instance

Throws #

CustomNodeException - If application is not set

setApplication() # 

public function setApplication(ApplicationInterface $application): self

Sets the application instance (automatically injected when configured).

Parameters #

ParameterTypeDescription
$applicationApplicationInterfaceThe application providing authentication

Returns #

self - For method chaining

getApplicationKey() # 

public function getApplicationKey(): string

Gets the application's unique identifier.

Returns #

string - The application name/key

Throws #

CustomNodeException - If application is not set

getApplicationInstall() # 

protected function getApplicationInstall(?string $user): ApplicationInstall

Retrieves the application installation containing user credentials and settings.

Parameters #

ParameterTypeDescription
$userstring|nullThe user ID, or null for shared installation

Returns #

ApplicationInstall - The application installation with credentials

Throws #

  • ApplicationInstallException - If installation not found
  • CustomNodeException - If application not set
  • GuzzleException - If HTTP request fails

getApplicationInstallFromProcess() # 

protected function getApplicationInstallFromProcess(ProcessDtoAbstract $dto): ApplicationInstall

Convenience method to get application installation from ProcessDto's user header.

Parameters #

ParameterTypeDescription
$dtoProcessDtoAbstractThe process DTO containing user information

Returns #

ApplicationInstall - The application installation with credentials

Throws #

  • ApplicationInstallException - If installation not found
  • CustomNodeException - If user not defined or application not set
  • GuzzleException - If HTTP request fails

Properties #

$sender # 

protected ?CurlManagerInterface $sender

The HTTP client for making requests. Automatically injected by dependency injection.

$okStatuses # 

protected array $okStatuses = [200, 201]

Array of acceptable HTTP status codes. You can override this in your connector to accept different status codes.

Example # 

class MyConnector extends ConnectorAbstract
{
    protected array $okStatuses = [200, 201, 204];
    
    // ... rest of implementation
}

Usage Examples #

Basic Connector Implementation # 

// From: orchesty-php-sdk/tests/Unit/Connector/TestNullConnector.php
<?php declare(strict_types=1);

namespace YourNamespace\Connector;

use Hanaboso\CommonsBundle\Process\ProcessDto;
use Hanaboso\PipesPhpSdk\Connector\ConnectorAbstract;

final class TestNullConnector extends ConnectorAbstract
{
    public function getName(): string
    {
        return 'null-test-trait';
    }

    public function processAction(ProcessDto $dto): ProcessDto
    {
        // Simple passthrough connector
        return new ProcessDto();
    }
}

Connector with HTTP Requests # 

<?php declare(strict_types=1);

namespace YourApp\Connector;

use Hanaboso\CommonsBundle\Process\ProcessDto;
use Hanaboso\CommonsBundle\Transport\Curl\CurlException;
use Hanaboso\CommonsBundle\Transport\Curl\Dto\RequestDto;
use Hanaboso\PipesPhpSdk\Connector\ConnectorAbstract;
use Hanaboso\PipesPhpSdk\Connector\Exception\ConnectorException;
use Hanaboso\Utils\String\Json;

final class HubSpotCreateContactConnector extends ConnectorAbstract
{
    public function getName(): string
    {
        return 'hubspot-create-contact';
    }

    /**
     * @throws ConnectorException
     * @throws CurlException
     */
    public function processAction(ProcessDto $dto): ProcessDto
    {
        // Parse incoming data
        $data = Json::decode($dto->getData());
        
        // Prepare API request
        $url = 'https://api.hubapi.com/contacts/v1/contact';
        $request = new RequestDto(
            $url,
            RequestDto::POST,
            Json::encode([
                'properties' => [
                    ['property' => 'email', 'value' => $data['email']],
                    ['property' => 'firstname', 'value' => $data['firstName']],
                    ['property' => 'lastname', 'value' => $data['lastName']],
                ],
            ])
        );
        
        // Add authentication headers
        $request->setHeaders([
            'Content-Type' => 'application/json',
            'Authorization' => sprintf('Bearer %s', 'your-api-token'),
        ]);
        
        // Send request
        $response = $this->getSender()->send($request);
        
        // Evaluate response
        if (!$this->evaluateStatusCode($response->getStatusCode(), $dto)) {
            return $dto; // Already marked as failed
        }
        
        // Set response data
        $dto->setData($response->getBody());
        
        return $dto;
    }
}

Connector with Application Authentication # 

<?php declare(strict_types=1);

namespace YourApp\Connector;

use Hanaboso\CommonsBundle\Process\ProcessDto;
use Hanaboso\CommonsBundle\Transport\Curl\Dto\RequestDto;
use Hanaboso\PipesPhpSdk\Application\Document\ApplicationInstall;
use Hanaboso\PipesPhpSdk\Connector\ConnectorAbstract;
use Hanaboso\PipesPhpSdk\Connector\Exception\ConnectorException;
use Hanaboso\Utils\String\Json;

final class AuthenticatedApiConnector extends ConnectorAbstract
{
    public function getName(): string
    {
        return 'authenticated-api-connector';
    }

    /**
     * @throws ConnectorException
     */
    public function processAction(ProcessDto $dto): ProcessDto
    {
        // Get application credentials
        $applicationInstall = $this->getApplicationInstallFromProcess($dto);
        
        // Extract credentials from settings
        $apiKey = $this->getApiKey($applicationInstall);
        
        // Prepare authenticated request
        $request = new RequestDto(
            'https://api.example.com/data',
            RequestDto::GET
        );
        $request->setHeaders([
            'Authorization' => sprintf('Bearer %s', $apiKey),
        ]);
        
        // Send and process
        $response = $this->getSender()->send($request);
        $this->evaluateStatusCode($response->getStatusCode(), $dto);
        
        $dto->setData($response->getBody());
        
        return $dto;
    }
    
    private function getApiKey(ApplicationInstall $install): string
    {
        $settings = $install->getSettings();
        return $settings['api_form']['api_key'] ?? '';
    }
}

Service Registration #

Connectors must be registered in Symfony's service container with the hbpf.connector prefix:

# config/services.yaml
services:
    hbpf.connector.hubspot-create-contact:
        class: YourApp\Connector\HubSpotCreateContactConnector
        tags: ['hbpf.connector']

Alternatively, use auto-configuration:

# config/services.yaml
services:
    _instanceof:
        Hanaboso\PipesPhpSdk\Connector\ConnectorAbstract:
            tags: ['hbpf.connector']
            
    YourApp\Connector\:
        resource: '../src/Connector'
        autowire: true

Notes #

  • Dependency Injection: All dependencies (ApplicationInstallRepository, CurlManager) are automatically injected by Symfony.
  • Error Handling: Use evaluateStatusCode() for HTTP errors and throw ConnectorException for connector-specific errors.
  • Data Flow: Always return a ProcessDto from processAction(), even on failure (use $dto->setStopProcess()).
  • Stateless: Connectors should be stateless - all data comes from ProcessDto and ApplicationInstall.
  • Testing: The SDK provides test utilities for connector testing (see ConnectorHandler tests).

See Also #

Next Steps:

After creating a connector, you typically need to:

  1. Understand ProcessDto for data handling
  2. Use CurlManager for HTTP requests
  3. Access credentials via ApplicationInstall
  4. Create an Application if authentication is needed
© 2025 Orchesty Solutions. All rights reserved.