ProcessDto

Overview #

ProcessDto is the data transfer object that flows through your connectors, custom nodes, and batch processors. It contains the input data, output data, headers, user context, and control flow information. Every connector receives a ProcessDto in its processAction() method and returns a modified version.

Purpose:

Carry data through the processing pipeline
Provide access to user and application context
Control processing flow (success, failure, retry, rate limiting)
Maintain headers for tracking and debugging

Package: hanaboso/commons-bundle
Namespace: Hanaboso\CommonsBundle\Process

When to Use #

You work with ProcessDto in every connector and custom node:

Input: Get data from previous steps via getData() or getJsonData()
Output: Set results via setData() or setJsonData()
Context: Access user info via getUser()
Control: Set status codes for error handling, retries, etc.

Class Hierarchy #

ProcessDtoAbstract
    ↓
ProcessDto

Core Methods #

Data Methods #

getData() #

public function getData(): string

Returns the raw data as a string.

Returns: string - Raw data content

Example:

$rawData = $dto->getData();
echo $rawData; // '{"name":"John","age":30}'

setData() #

public function setData(string $data): self

Sets raw string data.

Parameters:

Parameter	Type	Description
$data	string	Raw string data to set

Returns: self - For method chaining

Example:

// From: orchesty-php-sdk/src/Utils/ProcessDtoFactory.php
$dto = new ProcessDto();
$dto->setData($content)
    ->setHeaders($headers)
    ->setSuccessProcess();

getJsonData() #

public function getJsonData(): mixed

Returns the data parsed as a PHP array or object.

Returns: mixed - Parsed JSON data

Example:

$data = $dto->getJsonData();
echo $data['name']; // 'John'
echo $data['age'];  // 30

setJsonData() #

public function setJsonData(mixed $body): self

Sets data by automatically converting array/object to JSON string.

Parameters:

Parameter	Type	Description
$body	mixed	Array or object to be JSON-encoded

Returns: self - For method chaining

Example:

$dto->setJsonData([
    'userId' => 123,
    'name' => 'John Doe',
    'status' => 'active',
]);

Header Methods #

getHeaders() #

public function getHeaders(): array

Returns all headers as an associative array.

Returns: array - Headers array

Example:

// From: orchesty-php-sdk/src/Utils/ProcessDtoControllerTrait.php
$headers = $dto->getHeaders();
// ['pf-user' => 'user123', 'pf-application' => 'app-key']

setHeaders() #

public function setHeaders(array $headers): self

Sets all headers, replacing existing ones.

Parameters:

Parameter	Type	Description
$headers	array	Associative array of headers

Returns: self - For method chaining

Example:

$dto->setHeaders([
    'pf-user' => 'user123',
    'pf-application' => 'my-app',
    'custom-header' => 'value',
]);

addHeader() #

public function addHeader(string $key, string $value): self

Adds a single header without replacing existing ones.

Parameters:

Parameter	Type	Description
$key	string	Header name
$value	string	Header value

Returns: self - For method chaining

Example:

$dto->addHeader('X-Custom-ID', '12345');

Context Methods #

getUser() #

public function getUser(): ?string

Gets the user identifier from headers (pf-user header).

Returns: string|null - User ID or null if not set

Example:

// From: orchesty-php-sdk/src/CustomNode/CommonNodeTrait.php
$user = $dto->getUser();
if (!$user) {
    throw new CustomNodeException('User not defined');
}

Control Flow Methods #

setSuccessProcess() #

public function setSuccessProcess(): self

Marks the process as successful. Use this when your connector completes successfully.

Returns: self - For method chaining

Example:

// From: orchesty-php-sdk/src/Utils/ProcessDtoFactory.php
$dto = new ProcessDto();
$dto
    ->setData($content)
    ->setHeaders($headers)
    ->setSuccessProcess();

setStopProcess() #

public function setStopProcess(int $code, string $message): self

Marks the process as failed or stopped with a specific code and message.

Parameters:

Parameter	Type	Description
$code	int	Stop code (use ProcessDtoAbstract constants)
$message	string	Error or stop message

Returns: self - For method chaining

Stop Codes:

Constant	Value	Description
`ProcessDtoAbstract::STOP_AND_FAILED`	1001	Stop process and mark as failed
`ProcessDtoAbstract::DO_NOT_CONTINUE`	1002	Stop but don't mark as failed

Example:

// From: orchesty-php-sdk/src/Utils/ProcessDtoControllerTrait.php
$dto->setStopProcess(ProcessDtoAbstract::STOP_AND_FAILED, $e->getMessage());

getBridgeData() #

public function getBridgeData(): string

Gets the data that will be passed to the next node. Typically the same as getData().

Returns: string - Bridge data

Example:

// From: orchesty-php-sdk/src/Utils/ProcessDtoControllerTrait.php
$body = $dto->getBridgeData();

Debug and Logging Methods #

getDebugInfo() #

public function getDebugInfo(): array

Gets debug information about the process.

Returns: array - Debug info array

setDebugInfo() #

public function setDebugInfo(string $key, mixed $value): self

Adds debug information to the process DTO.

Parameters:

Parameter	Type	Description
$key	string	Debug key
$value	mixed	Debug value

Returns: self - For method chaining

Usage Examples #

Basic Connector Data Flow #

<?php declare(strict_types=1);

namespace YourApp\Connector;

use Hanaboso\CommonsBundle\Process\ProcessDto;
use Hanaboso\PipesPhpSdk\Connector\ConnectorAbstract;
use Hanaboso\Utils\String\Json;

final class DataTransformConnector extends ConnectorAbstract
{
    public function getName(): string
    {
        return 'data-transform';
    }

    public function processAction(ProcessDto $dto): ProcessDto
    {
        // Get input data
        $inputData = $dto->getJsonData();
        
        // Transform data
        $outputData = [
            'fullName' => sprintf('%s %s', $inputData['firstName'], $inputData['lastName']),
            'email' => $inputData['email'],
            'timestamp' => time(),
        ];
        
        // Set output data
        $dto->setJsonData($outputData);
        
        return $dto;
    }
}

Working with Headers #

public function processAction(ProcessDto $dto): ProcessDto
{
    // Get user from headers
    $user = $dto->getUser();
    
    // Get all headers
    $headers = $dto->getHeaders();
    $appKey = $headers['pf-application'] ?? null;
    
    // Add custom header
    $dto->addHeader('X-Processed-By', $this->getName());
    $dto->addHeader('X-Processed-At', date('c'));
    
    // Process and return
    return $dto;
}

Error Handling #

use Hanaboso\CommonsBundle\Process\ProcessDtoAbstract;

public function processAction(ProcessDto $dto): ProcessDto
{
    try {
        $data = $dto->getJsonData();
        
        if (!isset($data['required_field'])) {
            $dto->setStopProcess(
                ProcessDtoAbstract::STOP_AND_FAILED,
                'Missing required field: required_field'
            );
            return $dto;
        }
        
        // Process data...
        $result = $this->processData($data);
        
        $dto->setJsonData($result);
        $dto->setSuccessProcess();
        
    } catch (\Exception $e) {
        $dto->setStopProcess(
            ProcessDtoAbstract::STOP_AND_FAILED,
            sprintf('Processing failed: %s', $e->getMessage())
        );
    }
    
    return $dto;
}

Factory Creation #

// From: orchesty-php-sdk/src/Utils/ProcessDtoFactory.php
use Hanaboso\CommonsBundle\Process\ProcessDto;
use Hanaboso\PipesPhpSdk\Utils\ProcessDtoFactory;
use Symfony\Component\HttpFoundation\Request;

// Create from HTTP request
$dto = ProcessDtoFactory::createFromRequest($request);

// Or create manually
$dto = new ProcessDto();
$dto
    ->setData('{"key":"value"}')
    ->setHeaders(['pf-user' => 'user123'])
    ->setSuccessProcess();

JSON Data Manipulation #

public function processAction(ProcessDto $dto): ProcessDto
{
    // Parse incoming JSON
    $data = $dto->getJsonData();
    
    // Modify the data
    $data['processed'] = true;
    $data['processedAt'] = date('c');
    $data['processor'] = $this->getName();
    
    // Set back as JSON
    $dto->setJsonData($data);
    
    return $dto;
}

Standard Headers #

The following headers are commonly used in ProcessDto:

Header	Description
`pf-user`	User identifier for the current process
`pf-application`	Application key being used
`result-code`	HTTP result code from previous step
`result-message`	Result message from previous step
`pf-limit-key`	Rate limiting key
`pf-repeat-interval`	Retry interval in seconds
`pf-repeat-max-hops`	Maximum retry attempts

Notes #

Immutability: While ProcessDto allows modifications, each connector should receive, modify, and return the DTO.
Type Safety: Use getJsonData() and setJsonData() for structured data, getData() and setData() for raw strings.
Error Handling: Always set proper stop codes and messages when process fails.
Headers: Headers are preserved across the pipeline and can carry metadata between nodes.
User Context: The pf-user header identifies which user's credentials to use for authentication.

ProcessDto

Overview #

When to Use #

Class Hierarchy #

Core Methods #

Data Methods #

getData() #

setData() #

getJsonData() #

setJsonData() #

Header Methods #

getHeaders() #

setHeaders() #

addHeader() #

Context Methods #

getUser() #

Control Flow Methods #

setSuccessProcess() #

setStopProcess() #

getBridgeData() #

Debug and Logging Methods #

getDebugInfo() #

setDebugInfo() #

Usage Examples #

Basic Connector Data Flow #

Working with Headers #

Error Handling #

Factory Creation #

JSON Data Manipulation #

Standard Headers #

Notes #

See Also #