BasicApplicationAbstract

Overview #

BasicApplicationAbstract is the base class for creating applications that use basic authentication (username/password) or token-based authentication. You extend this class when building integrations with services that use simple authentication mechanisms like API keys, bearer tokens, or HTTP basic auth.

Purpose:

Provide a foundation for applications with basic/token authentication
Define standard authentication forms
Validate that required credentials are present
Integrate with connectors for authenticated API calls

File location: orchesty-php-sdk/src/Authorization/Base/Basic/BasicApplicationAbstract.php

Developer workflow: After creating connectors, you build applications to handle authentication. BasicApplicationAbstract is used for APIs that require API keys, tokens, or username/password credentials.

Class Hierarchy #

ApplicationAbstract
    ↓
BasicApplicationAbstract

Implements: BasicApplicationInterface, ApplicationInterface

Abstract Methods #

You must implement these methods when extending BasicApplicationAbstract:

getName() #

abstract public function getName(): string

Returns the unique identifier for your application.

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

Example:

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

getPublicName() #

abstract public function getPublicName(): string

Returns the human-readable display name.

Returns: string - Display name shown in UI

Example:

public function getPublicName(): string
{
    return 'HubSpot CRM';
}

getDescription() #

abstract public function getDescription(): string

Returns a description of what the application does.

Returns: string - Application description

Example:

public function getDescription(): string
{
    return 'CRM platform for managing customer relationships and sales pipelines';
}

getFormStack() #

abstract public function getFormStack(): FormStack

Returns the form configuration for collecting user credentials and settings.

Returns: FormStack - Form stack with authentication fields

Example:

// From: orchesty-php-sdk/tests/Integration/Application/TestNullApplication.php
public function getFormStack(): FormStack
{
    $form = new Form(ApplicationInterface::AUTHORIZATION_FORM, 'Authorization');
    $form
        ->addField(new Field(Field::TEXT, BasicApplicationInterface::USER, 'Username', null, true))
        ->addField(new Field(Field::PASSWORD, BasicApplicationInterface::PASSWORD, 'Password', null, true))
        ->addField(new Field(Field::TEXT, ApplicationInterface::TOKEN, 'API Token', null, false));

    $formStack = new FormStack();
    return $formStack->addForm($form);
}

getRequestDto() #

abstract public function getRequestDto(
    ProcessDtoAbstract $dto,
    ApplicationInstall $applicationInstall,
    string $method,
    ?string $url = null,
    ?string $data = null
): RequestDto

Creates an authenticated HTTP request with credentials from ApplicationInstall.

Parameters:

Parameter	Type	Description
$dto	ProcessDtoAbstract	The process DTO
$applicationInstall	ApplicationInstall	Installation with credentials
$method	string	HTTP method (GET, POST, etc.)
$url	string\|null	Request URL
$data	string\|null	Request body data

Returns: RequestDto - Configured request with authentication headers

Example:

public function getRequestDto(
    ProcessDtoAbstract $dto,
    ApplicationInstall $applicationInstall,
    string $method,
    ?string $url = null,
    ?string $data = null
): RequestDto
{
    $settings = $applicationInstall->getSettings();
    $apiKey = $settings[ApplicationInterface::AUTHORIZATION_FORM][ApplicationInterface::TOKEN] ?? '';
    
    $request = new RequestDto($this->getUri($url), $method, $dto);
    $request->setHeaders([
        'Authorization' => sprintf('Bearer %s', $apiKey),
        'Content-Type' => 'application/json',
    ]);
    
    if ($data) {
        $request->setBody($data);
    }
    
    return $request;
}

Provided Methods #

getAuthorizationType() #

public function getAuthorizationType(): string

Returns the authorization type for this application.

Returns: string - Always returns 'basic'

Note: This method is final and cannot be overridden.

isAuthorized() #

public function isAuthorized(ApplicationInstall $applicationInstall): bool

Checks if the application has valid credentials configured.

Parameters:

Parameter	Type	Description
$applicationInstall	ApplicationInstall	Installation to check

Returns: bool - True if credentials are present

Logic: Returns true if either:

Both user and password fields are set in authorization_form, OR
token field is set in authorization_form

Example:

$applicationInstall = $this->getApplicationInstallFromProcess($dto);

if (!$this->application->isAuthorized($applicationInstall)) {
    throw new ConnectorException('Application is not authorized');
}

Inherited Methods from ApplicationAbstract #

getApplicationForms() #

public function getApplicationForms(ApplicationInstall $applicationInstall): array

Returns form configuration with current values populated from ApplicationInstall.

Parameters:

Parameter	Type	Description
$applicationInstall	ApplicationInstall	Installation with saved settings

Returns: array - Form array with values

saveApplicationForms() #

public function saveApplicationForms(
    ApplicationInstall $applicationInstall,
    array $settings
): ApplicationInstall

Saves form settings to ApplicationInstall.

Parameters:

Parameter	Type	Description
$applicationInstall	ApplicationInstall	Installation to update
$settings	array	Form settings to save

Returns: ApplicationInstall - Updated installation

savePassword() #

public function savePassword(
    ApplicationInstall $applicationInstall,
    string $formKey,
    string $fieldKey,
    string $password
): ApplicationInstall

Saves a password field value.

Parameters:

Parameter	Type	Description
$applicationInstall	ApplicationInstall	Installation to update
$formKey	string	Form key (e.g., 'authorization_form')
$fieldKey	string	Field key (e.g., 'password')
$password	string	Password value

Returns: ApplicationInstall - Updated installation

getLogo() #

public function getLogo(): ?string

Returns base64-encoded logo for the application.

Returns: string|null - Base64 logo data URI or null

getInfo() #

public function getInfo(): string

Returns additional info text about the application.

Returns: string - Info text

Usage Examples #

Complete Basic Application with API Key #

<?php declare(strict_types=1);

namespace YourApp\Application;

use Hanaboso\CommonsBundle\Process\ProcessDtoAbstract;
use Hanaboso\CommonsBundle\Transport\Curl\Dto\RequestDto;
use Hanaboso\PipesPhpSdk\Application\Base\ApplicationInterface;
use Hanaboso\PipesPhpSdk\Application\Document\ApplicationInstall;
use Hanaboso\PipesPhpSdk\Application\Model\Form\Field;
use Hanaboso\PipesPhpSdk\Application\Model\Form\Form;
use Hanaboso\PipesPhpSdk\Application\Model\Form\FormStack;
use Hanaboso\PipesPhpSdk\Authorization\Base\Basic\BasicApplicationAbstract;

final class HubSpotApplication extends BasicApplicationAbstract
{
    public function getName(): string
    {
        return 'hubspot';
    }

    public function getPublicName(): string
    {
        return 'HubSpot CRM';
    }

    public function getDescription(): string
    {
        return 'CRM platform for managing customer relationships and sales pipelines';
    }

    public function getFormStack(): FormStack
    {
        // Create authorization form with API key field
        $form = new Form(ApplicationInterface::AUTHORIZATION_FORM, 'API Credentials');
        $form->addField(
            new Field(
                Field::TEXT,
                ApplicationInterface::TOKEN,
                'API Key',
                null,
                true // required
            )
        );

        // Add configuration form
        $configForm = new Form('config_form', 'Configuration');
        $configForm->addField(
            new Field(
                Field::TEXT,
                'base_url',
                'API Base URL',
                'https://api.hubapi.com',
                false
            )
        );

        $formStack = new FormStack();
        $formStack
            ->addForm($form)
            ->addForm($configForm);

        return $formStack;
    }

    public function getRequestDto(
        ProcessDtoAbstract $dto,
        ApplicationInstall $applicationInstall,
        string $method,
        ?string $url = null,
        ?string $data = null
    ): RequestDto
    {
        // Get credentials from settings
        $settings = $applicationInstall->getSettings();
        $apiKey = $settings[ApplicationInterface::AUTHORIZATION_FORM][ApplicationInterface::TOKEN] ?? '';
        $baseUrl = $settings['config_form']['base_url'] ?? 'https://api.hubapi.com';

        // Build full URL
        $fullUrl = sprintf('%s%s', rtrim($baseUrl, '/'), $url);

        // Create request with authentication
        $request = new RequestDto($this->getUri($fullUrl), $method, $dto);
        $request->setHeaders([
            'Authorization' => sprintf('Bearer %s', $apiKey),
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
        ]);

        if ($data) {
            $request->setBody($data);
        }

        return $request;
    }
}

Application with Username/Password Authentication #

<?php declare(strict_types=1);

namespace YourApp\Application;

use Hanaboso\CommonsBundle\Process\ProcessDtoAbstract;
use Hanaboso\CommonsBundle\Transport\Curl\Dto\RequestDto;
use Hanaboso\PipesPhpSdk\Application\Base\ApplicationInterface;
use Hanaboso\PipesPhpSdk\Application\Document\ApplicationInstall;
use Hanaboso\PipesPhpSdk\Application\Model\Form\Field;
use Hanaboso\PipesPhpSdk\Application\Model\Form\Form;
use Hanaboso\PipesPhpSdk\Application\Model\Form\FormStack;
use Hanaboso\PipesPhpSdk\Authorization\Base\Basic\BasicApplicationAbstract;
use Hanaboso\PipesPhpSdk\Authorization\Base\Basic\BasicApplicationInterface;

final class BasicAuthApplication extends BasicApplicationAbstract
{
    public function getName(): string
    {
        return 'basic-auth-api';
    }

    public function getPublicName(): string
    {
        return 'Basic Auth API';
    }

    public function getDescription(): string
    {
        return 'API with HTTP Basic Authentication';
    }

    public function getFormStack(): FormStack
    {
        $form = new Form(ApplicationInterface::AUTHORIZATION_FORM, 'Credentials');
        $form
            ->addField(
                new Field(
                    Field::TEXT,
                    BasicApplicationInterface::USER,
                    'Username',
                    null,
                    true
                )
            )
            ->addField(
                new Field(
                    Field::PASSWORD,
                    BasicApplicationInterface::PASSWORD,
                    'Password',
                    null,
                    true
                )
            );

        $formStack = new FormStack();
        return $formStack->addForm($form);
    }

    public function getRequestDto(
        ProcessDtoAbstract $dto,
        ApplicationInstall $applicationInstall,
        string $method,
        ?string $url = null,
        ?string $data = null
    ): RequestDto
    {
        $settings = $applicationInstall->getSettings();
        $username = $settings[ApplicationInterface::AUTHORIZATION_FORM][BasicApplicationInterface::USER] ?? '';
        $password = $settings[ApplicationInterface::AUTHORIZATION_FORM][BasicApplicationInterface::PASSWORD] ?? '';

        // Create Basic Auth header
        $credentials = base64_encode(sprintf('%s:%s', $username, $password));

        $request = new RequestDto($this->getUri($url), $method, $dto);
        $request->setHeaders([
            'Authorization' => sprintf('Basic %s', $credentials),
            'Content-Type' => 'application/json',
        ]);

        if ($data) {
            $request->setBody($data);
        }

        return $request;
    }
}

Using Application in a Connector #

<?php declare(strict_types=1);

namespace YourApp\Connector;

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

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

    public function processAction(ProcessDto $dto): ProcessDto
    {
        // Get application and installation
        $app = $this->getApplication();
        $appInstall = $this->getApplicationInstallFromProcess($dto);

        // Check if authorized
        if (!$app->isAuthorized($appInstall)) {
            $dto->setStopProcess(
                ProcessDto::STOP_AND_FAILED,
                'HubSpot application is not authorized'
            );
            return $dto;
        }

        // Create authenticated request using application
        $request = $app->getRequestDto(
            $dto,
            $appInstall,
            'POST',
            '/contacts/v1/contact',
            $dto->getData()
        );

        // Send request
        $response = $this->getSender()->send($request);
        $this->evaluateStatusCode($response->getStatusCode(), $dto);

        $dto->setData($response->getBody());

        return $dto;
    }
}

Service Registration #

# config/services.yaml
services:
    hbpf.application.hubspot:
        class: YourApp\Application\HubSpotApplication
        tags: ['hbpf.application']

Or use auto-configuration:

# config/services.yaml
services:
    _instanceof:
        Hanaboso\PipesPhpSdk\Application\Base\ApplicationInterface:
            tags: ['hbpf.application']
            
    YourApp\Application\:
        resource: '../src/Application'
        autowire: true

Constants #

From BasicApplicationInterface #

public const string USER = 'user';
public const string PASSWORD = 'password';

Field keys for username/password authentication.

From ApplicationInterface #

public const string AUTHORIZATION_FORM = 'authorization_form';
public const string TOKEN = 'token';

Standard form and field keys.

Notes #

Authentication Types: Use BasicApplicationAbstract for API keys, tokens, or username/password auth. For OAuth2, use OAuth2ApplicationAbstract.
Form Structure: Always use ApplicationInterface::AUTHORIZATION_FORM as the key for your authentication form.
Credentials Security: Passwords and tokens are automatically encrypted when saved to ApplicationInstall.
Authorization Check: Always check isAuthorized() before making API requests to ensure credentials are configured.
Logo and Info: Set $logoFilename and $infoFilename properties to customize application branding.

BasicApplicationAbstract

Overview #

Class Hierarchy #

Abstract Methods #

getName() #

getPublicName() #

getDescription() #

getFormStack() #

getRequestDto() #

Provided Methods #

getAuthorizationType() #

isAuthorized() #

Inherited Methods from ApplicationAbstract #

getApplicationForms() #

saveApplicationForms() #

savePassword() #

getLogo() #

getInfo() #

Usage Examples #

Complete Basic Application with API Key #

Application with Username/Password Authentication #

Using Application in a Connector #

Service Registration #

Constants #

From BasicApplicationInterface #

From ApplicationInterface #

Notes #

See Also #