ApplicationInstall

Overview #

ApplicationInstall represents an installed application instance in the Orchesty PHP SDK. It stores user-specific credentials, settings, and configuration data that connectors and custom nodes use to authenticate with external APIs. Each user can have their own application installation with unique credentials.

Purpose:

Store user credentials and API keys
Manage application settings configured through forms
Track installation state (enabled/disabled, expiration)
Separate encrypted sensitive data from regular settings

File location: orchesty-php-sdk/src/Application/Document/ApplicationInstall.php

Developer workflow: Connectors retrieve ApplicationInstall to access user credentials when making authenticated API requests.

Class Hierarchy #

DocumentAbstract
    ↓
ApplicationInstall

Extends Hanaboso\PipesPhpSdk\Storage\Mongodb\DocumentAbstract for MongoDB persistence.

Constructor #

public function __construct(?array $data = [])

Parameters #

Parameter	Type	Description
$data	array\|null	Optional initialization data

Throws #

DateTimeException - If datetime creation fails

Note: The constructor automatically sets created and updated timestamps.

Core Methods #

Settings Management #

getSettings() #

public function getSettings(): array

Returns all application settings as an associative array. Settings typically contain form data like API keys, URLs, and configuration options.

Returns: array - Settings array with form structure: ['form_key' => ['field_key' => 'value']]

Example:

// From: orchesty-php-sdk/src/Application/Base/ApplicationAbstract.php
$settings = $applicationInstall->getSettings();
$apiKey = $settings['api_form']['api_key'] ?? '';
$apiUrl = $settings['api_form']['base_url'] ?? 'https://api.example.com';

setSettings() #

public function setSettings(?array $settings): self

Replaces all settings with new data.

Parameters:

Parameter	Type	Description
$settings	array\|null	New settings array

Returns: self - For method chaining

addSettings() #

public function addSettings(array $settings): self

Merges new settings into existing settings without replacing everything.

Parameters:

Parameter	Type	Description
$settings	array	Settings to merge

Returns: self - For method chaining

Example:

// From: orchesty-php-sdk/src/Application/Base/ApplicationAbstract.php
$applicationInstall->addSettings([
    'auth_form' => [
        'api_key' => $newApiKey,
    ],
]);

User and Key Management #

getUser() #

public function getUser(): ?string

Returns the user ID who owns this application installation.

Returns: string|null - User identifier or null for shared installations

Example:

$userId = $applicationInstall->getUser();
// 'user_123'

setUser() #

public function setUser(?string $user): self

Sets the user who owns this installation.

Parameters:

Parameter	Type	Description
$user	string\|null	User identifier

Returns: self - For method chaining

getKey() #

public function getKey(): ?string

Returns the application key (application name/identifier).

Returns: string|null - Application key (e.g., 'hubspot', 'mailchimp')

Example:

$appKey = $applicationInstall->getKey();
// 'hubspot'

setKey() #

public function setKey(?string $key): self

Sets the application key.

Parameters:

Parameter	Type	Description
$key	string\|null	Application identifier

Returns: self - For method chaining

State Management #

isEnabled() #

public function isEnabled(): bool

Checks if the application installation is enabled and can be used.

Returns: bool - True if enabled

Example:

if (!$applicationInstall->isEnabled()) {
    throw new ConnectorException('Application is disabled');
}

setEnabled() #

public function setEnabled(?bool $enabled): self

Enables or disables the application installation.

Parameters:

Parameter	Type	Description
$enabled	bool\|null	Enable state

Returns: self - For method chaining

getExpires() #

public function getExpires(): ?DateTime

Returns the expiration date for OAuth tokens or temporary credentials.

Returns: DateTime|null - Expiration date or null if not applicable

setExpires() #

public function setExpires(?DateTime $expires): self

Sets the expiration date.

Parameters:

Parameter	Type	Description
$expires	DateTime\|null	Expiration datetime

Returns: self - For method chaining

Encrypted Settings #

getEncryptedSettings() #

public function getEncryptedSettings(): string

Returns encrypted settings string (typically OAuth tokens or sensitive data).

Returns: string - Encrypted settings

Note: The encryption/decryption is handled by the application manager.

setEncryptedSettings() #

public function setEncryptedSettings(?string $encryptedSettings): self

Sets encrypted settings.

Parameters:

Parameter	Type	Description
$encryptedSettings	string\|null	Encrypted settings string

Returns: self - For method chaining

Non-Encrypted Settings #

getNonEncryptedSettings() #

public function getNonEncryptedSettings(): ?array

Returns settings that don't require encryption (e.g., public configuration).

Returns: array|null - Non-encrypted settings array

setNonEncryptedSettings() #

public function setNonEncryptedSettings(array $nonEncryptedSettings): self

Sets non-encrypted settings.

Parameters:

Parameter	Type	Description
$nonEncryptedSettings	array	Settings that don't need encryption

Returns: self - For method chaining

addNonEncryptedSettings() #

public function addNonEncryptedSettings(array $nonEncryptedSettings): self

Merges non-encrypted settings into existing non-encrypted settings.

Parameters:

Parameter	Type	Description
$nonEncryptedSettings	array	Settings to merge

Returns: self - For method chaining

Timestamps #

getCreated() #

public function getCreated(): ?DateTime

Returns when the installation was created.

Returns: DateTime|null - Creation timestamp

getUpdated() #

public function getUpdated(): ?DateTime

Returns when the installation was last updated.

Returns: DateTime|null - Update timestamp

preUpdate() #

public function preUpdate(): void

Lifecycle hook that updates the updated timestamp before saving.

Throws: DateTimeException - If datetime creation fails

Soft Delete #

isDeleted() #

public function isDeleted(): bool

Checks if the installation is soft-deleted.

Returns: bool - True if deleted

setDeleted() #

public function setDeleted(?bool $deleted): self

Marks the installation as deleted (soft delete).

Parameters:

Parameter	Type	Description
$deleted	bool\|null	Deleted state

Returns: self - For method chaining

Usage Examples #

Accessing Credentials in a Connector #

<?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;

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

    public function processAction(ProcessDto $dto): ProcessDto
    {
        // Get the application installation for the current user
        $applicationInstall = $this->getApplicationInstallFromProcess($dto);
        
        // Access credentials from settings
        $settings = $applicationInstall->getSettings();
        $apiKey = $settings['auth_form']['api_key'] ?? '';
        $baseUrl = $settings['config_form']['base_url'] ?? 'https://api.hubapi.com';
        
        // Use credentials in API request
        $request = new RequestDto(
            sprintf('%s/contacts/v1/contact', $baseUrl),
            RequestDto::POST,
            $dto->getData()
        );
        $request->setHeaders([
            'Authorization' => sprintf('Bearer %s', $apiKey),
            'Content-Type' => 'application/json',
        ]);
        
        $response = $this->getSender()->send($request);
        $this->evaluateStatusCode($response->getStatusCode(), $dto);
        
        $dto->setData($response->getBody());
        
        return $dto;
    }
}

Checking Installation State #

use Hanaboso\PipesPhpSdk\Application\Document\ApplicationInstall;
use Hanaboso\PipesPhpSdk\Connector\Exception\ConnectorException;

public function processAction(ProcessDto $dto): ProcessDto
{
    $applicationInstall = $this->getApplicationInstallFromProcess($dto);
    
    // Check if installation is enabled
    if (!$applicationInstall->isEnabled()) {
        throw new ConnectorException(
            sprintf('Application %s is disabled', $applicationInstall->getKey())
        );
    }
    
    // Check if credentials have expired (OAuth tokens)
    $expires = $applicationInstall->getExpires();
    if ($expires && $expires < new \DateTime()) {
        throw new ConnectorException('Application credentials have expired');
    }
    
    // Proceed with normal processing
    $settings = $applicationInstall->getSettings();
    // ...
}

Working with Multiple Form Settings #

use Hanaboso\PipesPhpSdk\Application\Document\ApplicationInstall;

public function processAction(ProcessDto $dto): ProcessDto
{
    $applicationInstall = $this->getApplicationInstallFromProcess($dto);
    $settings = $applicationInstall->getSettings();
    
    // Access different form settings
    $authSettings = $settings['authorization_form'] ?? [];
    $apiKey = $authSettings['api_key'] ?? '';
    $apiSecret = $authSettings['api_secret'] ?? '';
    
    $configSettings = $settings['config_form'] ?? [];
    $timeout = $configSettings['timeout'] ?? 30;
    $retries = $configSettings['max_retries'] ?? 3;
    
    $webhookSettings = $settings['webhook_form'] ?? [];
    $webhookUrl = $webhookSettings['callback_url'] ?? '';
    
    // Use settings...
}

Retrieving Installation from Repository #

use Hanaboso\PipesPhpSdk\Application\Repository\ApplicationInstallRepository;
use Hanaboso\PipesPhpSdk\Application\Document\ApplicationInstall;

class CustomService
{
    public function __construct(
        private readonly ApplicationInstallRepository $repository
    ) {}
    
    public function getInstallation(string $appKey, string $userId): ApplicationInstall
    {
        // Find installation for specific user and application
        return $this->repository->findUserApp($appKey, $userId);
    }
    
    public function getSharedInstallation(string $appKey): ApplicationInstall
    {
        // Find shared installation (no specific user)
        return $this->repository->findOneByName($appKey);
    }
}

Constants #

USER #

public const string USER = 'user';

Field name for user identifier in array representation.

NAME #

public const string NAME = 'name';

Field name for application key in array representation.

Data Persistence #

ApplicationInstall extends DocumentAbstract and is persisted to MongoDB. The document structure:

{
    "_id": "507f1f77bcf86cd799439011",
    "user": "user_123",
    "name": "hubspot",
    "key": "hubspot",
    "enabled": true,
    "settings": {
        "auth_form": {
            "api_key": "pk_live_123...",
            "base_url": "https://api.hubapi.com"
        },
        "config_form": {
            "timeout": 30
        }
    },
    "encryptedSettings": "...",
    "nonEncryptedSettings": {},
    "created": "2024-01-15T10:30:00.000Z",
    "updated": "2024-01-20T14:22:00.000Z",
    "expires": null,
    "deleted": false
}

Settings Structure #

Settings follow a hierarchical structure based on forms:

[
    'form_key' => [
        'field_key' => 'field_value',
        'another_field' => 'another_value',
    ],
    'another_form' => [
        'field1' => 'value1',
    ],
]

Example:

[
    'authorization_form' => [
        'api_key' => 'abc123',
        'api_secret' => 'secret456',
    ],
    'config_form' => [
        'base_url' => 'https://api.example.com',
        'timeout' => 30,
    ],
]

Notes #

User-Specific vs Shared: Installations can be user-specific (has user field) or shared (no user field).
Encryption: Sensitive data like passwords and tokens should use encryptedSettings instead of regular settings.
Soft Delete: Installations are soft-deleted (marked as deleted) rather than physically removed.
Timestamps: created and updated are automatically managed by the document lifecycle.
Expiration: The expires field is primarily used for OAuth2 token expiration tracking.

ApplicationInstall

Overview #

Class Hierarchy #

Constructor #

Parameters #

Throws #

Core Methods #

Settings Management #

getSettings() #

setSettings() #

addSettings() #

User and Key Management #

getUser() #

setUser() #

getKey() #

setKey() #

State Management #

isEnabled() #

setEnabled() #

getExpires() #

setExpires() #

Encrypted Settings #

getEncryptedSettings() #

setEncryptedSettings() #

Non-Encrypted Settings #

getNonEncryptedSettings() #

setNonEncryptedSettings() #

addNonEncryptedSettings() #

Timestamps #

getCreated() #

getUpdated() #

preUpdate() #

Soft Delete #

isDeleted() #

setDeleted() #

Usage Examples #

Accessing Credentials in a Connector #

Checking Installation State #

Working with Multiple Form Settings #

Retrieving Installation from Repository #

Constants #

USER #

NAME #

Data Persistence #

Settings Structure #

Notes #

See Also #