### Manual Installation of HEPTAconnect Playground

Source: https://www.heptaconnect.io/guides/playground

Provides a manual, step-by-step installation process for the HEPTAconnect Playground using Composer. This method offers more control over the installation and setup compared to the automated approach.

```bash
# Download the Playground project
composer create-project heptaconnect/playground --no-install --no-scripts

# Move into Playground directory
cd playground

# Download the project's dependencies
composer install

# Ask you some questions during the setup process
bin/console system:setup

# Create the database and run all migrations
bin/console system:install
```

--------------------------------

### Install HEPTAconnect Playground with Composer

Source: https://www.heptaconnect.io/guides/playground

This command installs the HEPTAconnect Playground project and its dependencies using Composer. It automates project setup, including environment configuration, URL setup, and database initialization.

```bash
composer create-project heptaconnect/playground
```

--------------------------------

### Install RabbitMQ PECL Extension

Source: https://www.heptaconnect.io/guides/integrator/message-brokers

Installs the AMQP PECL extension, which is a dependency for using RabbitMQ as a message broker in some PHP environments.

```bash
pecl install amqp
```

--------------------------------

### Install Redis PECL Extension

Source: https://www.heptaconnect.io/guides/integrator/message-brokers

Installs the Redis PECL extension, which is a dependency for using Redis as a message broker in some PHP environments.

```bash
pecl install redis
```

--------------------------------

### FinderBuilder.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Illustrates a typical file structure for a FinderBuilder within the portal base package. This includes the builder itself, the component, and related tokens.

```php
<?php

namespace PortalBase\Builder\Builder;

class FinderBuilder
{
    // ... implementation details ...
}
```

--------------------------------

### PHP Constructor for Dependency Acquisition - HeptaConnect

Source: https://www.heptaconnect.io/reference/adr/2021-06-17-flow-component-short-notation

This PHP code snippet illustrates the constructor of an emitter class, highlighting the acquisition of dependencies through type-hinted parameters. It's an example of the setup code that the proposed short notation seeks to streamline.

```php
public function __construct(ApiClient $client, BottlePacker $packer/*, string $externalId*/)

```

--------------------------------

### Finder.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Illustrates a typical file structure for a Finder component within the portal base package. This file represents the core finder component.

```php
<?php

namespace PortalBase\Builder\Component;

class Finder
{
    // ... implementation details ...
}
```

--------------------------------

### FinderStackBuilderFactory.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Implements the FinderStackBuilderFactoryInterface, providing a factory for creating FinderStackBuilder instances within the core package. This ensures consistent builder instantiation.

```php
<?php

namespace Core\Find;

use Core\Find\Contract\FinderStackBuilderFactoryInterface;
use Core\Find\Contract\FinderStackBuilderInterface;
use Heptacom\HeptaConnect\Core\Flow\Contract\FlowComponentStack;

class FinderStackBuilderFactory implements FinderStackBuilderFactoryInterface
{
    public function create(): FinderStackBuilderInterface
    {
        return new FinderStackBuilder();
    }
}
```

--------------------------------

### Create HEPTAconnect Production Project with Composer

Source: https://www.heptaconnect.io/news/2022-11-29-production-template

This command uses Composer to create a new project based on the HEPTAconnect production template. It installs the necessary packages and sets up a development environment for your new integration. Ensure Composer is installed and accessible in your environment.

```bash
composer create-project heptaconnect/production my-project -s dev
```

--------------------------------

### Install HEPTAconnect Portal with Composer

Source: https://www.heptaconnect.io/guides/playground/add-portals

Use Composer to install a new HEPTAconnect portal package into your project. This command fetches the specified portal from Packagist and integrates it with your existing HEPTAconnect setup.

```bash
composer require niemand-online/heptaconnect-portal-nasa-apod
```

--------------------------------

### FinderToken.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Illustrates a typical file structure for a FinderToken within the portal base package. Tokens are often used for identifying or managing specific functionalities.

```php
<?php

namespace PortalBase\Builder\Token;

class FinderToken
{
    // ... implementation details ...
}
```

--------------------------------

### Example Log Message with Code (grep)

Source: https://www.heptaconnect.io/news/2022-05-17-exception-and-log-message-codes

Demonstrates how to use 'grep' to search for exception codes within the HeptaConnect installation's changelogs. This helps locate the specific code that triggered an exception and its context.

```bash
grep "123" /path/to/heptaconnect/installation/changelogs
```

--------------------------------

### FindService.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Implements the FindServiceInterface, acting as the main entry point for executing the find flow component within the core package. It orchestrates stack building, context creation, and actor execution.

```php
<?php

namespace Core\Find;

use Core\Find\Contract\FindActorInterface;
use Core\Find\Contract\FindContextFactoryInterface;
use Core\Find\Contract\FindServiceInterface;
use Core\Find\Contract\FinderStackBuilderFactoryInterface;
use Heptacom\HeptaConnect\Core\Flow\Contract\FlowComponentStack;
use Heptacom\HeptaConnect\Core\Flow\Contract\FlowComponentStackContext;

class FindService implements FindServiceInterface
{
    private FinderStackBuilderFactoryInterface $finderStackBuilderFactory;
    private FindContextFactoryInterface $findContextFactory;
    private FindActorInterface $findActor;

    public function __construct(
        FinderStackBuilderFactoryInterface $finderStackBuilderFactory,
        FindContextFactoryInterface $findContextFactory,
        FindActorInterface $findActor
    )
    {
        $this->finderStackBuilderFactory = $finderStackBuilderFactory;
        $this->findContextFactory = $findContextFactory;
        $this->findActor = $findActor;
    }

    public function find(FlowComponentStack $stack, FlowComponentStackContext $context): void
    {
        // ... implementation to execute find operation ...
    }
}
```

--------------------------------

### Replay HTTP Request Dumps with Telnet

Source: https://www.heptaconnect.io/guides/integrator/http-handlers

This example shows how to replay HTTP request dumps using the 'telnet' command. After connecting to the target host and port, you can paste the content of the dump file directly into the terminal. Ensure telnet is installed and the host/port are correct.

```shell
telnet localhost 80 # paste file content
```

--------------------------------

### FinderCodeOriginFinder.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Implements the FinderCodeOriginFinderInterface, responsible for locating the code origin of finder components within the core package. This aids in code traceability and management.

```php
<?php

namespace Core\Find;

use Core\Find\Contract\FinderCodeOriginFinderInterface;

class FinderCodeOriginFinder implements FinderCodeOriginFinderInterface
{
    // ... implementation for finding code origin ...
}
```

--------------------------------

### FinderCollection.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Represents a collection of finders or related data within the portal base package. This class facilitates the management and iteration over finder elements.

```php
<?php

namespace PortalBase\Find;

class FinderCollection
{
    // ... implementation details for collections ...
}
```

--------------------------------

### Basic PHP REPL Command

Source: https://www.heptaconnect.io/news/2023-08-15-code-execution-in-repl

This example shows how to use the built-in PHP interactive mode (REPL) to execute a simple command. It demonstrates the basic functionality of a REPL by instantiating a DateTime object and displaying it.

```php
var_dump(new DateTime());
```

--------------------------------

### Changelog Entry: Introduce New Feature (PHP)

Source: https://www.heptaconnect.io/guides/contributor/changelog

Example of how to document the introduction of a new feature in a changelog. This typically involves adding a new class or functionality to the public API.

```markdown
### Added

- Introduce fiddling of stuff into new class `\Heptacom\HeptaConnect\StuffFiddler`
```

--------------------------------

### FinderStackBuilder.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Implements the FinderStackBuilderInterface, responsible for constructing finder stacks within the core package. This class works with factories to assemble the necessary components.

```php
<?php

namespace Core\Find;

use Core\Find\Contract\FinderStackBuilderInterface;
use Heptacom\HeptaConnect\Core\Flow\Contract\FlowComponentStack;

class FinderStackBuilder implements FinderStackBuilderInterface
{
    public function build(FlowComponentStack $stack): FlowComponentStack
    {
        // ... implementation to build the finder stack ...
        return $stack;
    }
}
```

--------------------------------

### FinderCodeOriginFinderInterface.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Defines the interface for finding the code origin of a finder within the portal base package. This is crucial for tracking and managing the source of finder components.

```php
<?php

namespace PortalBase\Find\Contract;

interface FinderCodeOriginFinderInterface
{
    // ... methods for finding code origin ...
}
```

--------------------------------

### FinderStack.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Represents the stack used during finder operations within the portal base package. This class implements the FinderStackInterface and manages the state of a finder operation.

```php
<?php

namespace PortalBase\Find;

class FinderStack implements FinderStackInterface
{
    // ... implementation details for finder stack ...
}
```

--------------------------------

### FinderContract.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Defines the primary contract for a finder component within the portal base package. This interface specifies the fundamental operations and behavior of a finder.

```php
<?php

namespace PortalBase\Find\Contract;

interface FinderContract
{
    // ... methods for finder operations ...
}
```

--------------------------------

### FinderStackInterface.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Defines the interface for the stack used in finder operations within the portal base package. This interface governs how data and components are managed within the finder stack.

```php
<?php

namespace PortalBase\Find\Contract;

interface FinderStackInterface
{
    // ... methods for managing the finder stack ...
}
```

--------------------------------

### HEPTAconnect Dataset Composer Package Configuration (PHP)

Source: https://www.heptaconnect.io/guides/portal-developer/dataset

Example `composer.json` for a HEPTAconnect dataset package. It specifies package metadata, dependencies on PHP and the dataset base, and autoloading configuration.

```json
{
    "name": "acme/heptaconnect-dataset-bottle",
    "description": "HEPTAconnect dataset package to provide bottles",
    "type": "library",
    "keywords": [
        "heptaconnect-dataset"
    ],
    "require": {
        "php": ">=7.4",
        "heptacom/heptaconnect-dataset-base": ">=1"
    },
    "autoload": {
        "psr-4": {
            "Acme\\Dataset\\Bottle\\": "src/"
        }
    }
}
```

--------------------------------

### Graylog Docker Compose Setup

Source: https://www.heptaconnect.io/guides/integrator/logging

Docker Compose configuration to set up Graylog with MongoDB and Elasticsearch. This allows for a quick local or production environment for log management. It defines services for mongo, elasticsearch, and graylog, along with network configurations.

```yaml
version: '3'
services:
    mongo:
        image: mongo:4.2
        networks:
            - graylog
    elasticsearch:
        image: docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2
        environment:
            - http.host=0.0.0.0
            - transport.host=localhost
            - network.host=0.0.0.0
            - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
        ulimits:
            memlock:
                soft: -1
                hard: -1
        deploy:
            resources:
                limits:
                    memory : 1g
        networks:
            - graylog
    graylog:
        image: graylog/graylog:4.1
        environment:
            - GRAYLOG_PASSWORD_SECRET=somepasswordpepper
            - GRAYLOG_ROOT_PASSWORD_SHA2=8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918
            - GRAYLOG_HTTP_EXTERNAL_URI=http://127.0.0.1:9000/
        networks:
            - graylog
        restart: always
        depends_on:
            - mongo
            - elasticsearch
        ports:
            - 9000:9000
            - 12201:12201
            - 12201:12201/udp
networks:
    graylog:
        driver: bridge

```

--------------------------------

### Run Explorer and Emit Data - PHP

Source: https://www.heptaconnect.io/guides/portal-developer/direct-emission-explorer

This PHP code snippet demonstrates the `run` method within an HEPTAconnect explorer. It iterates over objects fetched from a data source via an `ApiClient`, sets the primary key for each object, and yields them as dataset entities for emission. It requires configuration credentials and uses a hypothetical `ApiClient` and `Bottle` entity.

```php
protected function run(ExploreContextInterface $context): iterable
{
    $credentials = $context->getConfig()['credentials'];
    $client = new ApiClient($credentials);

    foreach ($client->getBottles() as $bottle)
    {
        $entity = new Bottle();
        $entity->setPrimaryKey((string) $bottle['id']);
        $entity->setCapacity(new Liter($bottle['volume']));

        yield $entity;
    }
}
```

--------------------------------

### Start HEPTAconnect Worker Process

Source: https://www.heptaconnect.io/guides/playground

Starts a long-running worker process for HEPTAconnect using Symfony Messenger. This process consumes messages from the queue to handle asynchronous data transfers.

```bash
bin/console messenger:consume
```

--------------------------------

### PHP Repository Implementation Example

Source: https://www.heptaconnect.io/guides/portal-developer/dependency-injection

Demonstrates how to implement an API resource repository in PHP, adhering to a common interface. This example shows dependency injection of an ApiClient and a method to fetch resources.

```php
namespace FooBar\AcmeApi;

class AppleRepository implements ApiResourceInterface
{
    private ApiClient $client;

    public function __construct(ApiClient $client)
    {
        $this->client = $client;
    }

    public function findAll(): array
    {
        return $this->client->findAll('apple');
    }
}

```

```php
namespace FooBar\AcmeApi;

class OrangeRepository implements ApiResourceInterface
{
    private ApiClient $client;

    public function __construct(ApiClient $client)
    {
        $this->client = $client;
    }

    public function findAll(): array
    {
        return $this->client->findAll('orange');
    }
}

```

--------------------------------

### Implement HEPTAconnect Portal Contract

Source: https://www.heptaconnect.io/guides/portal-developer

A minimal HEPTAconnect portal implementation using the PortalContract. This serves as the entry point for a portal and can be extended with custom methods for configuration or flow components.

```php
namespace Acme\Portal\Bottle;

use Heptacom\HeptaConnect\Portal\Base\Portal\Contract\PortalContract;

class BottlePortal extends PortalContract
{
}
```

--------------------------------

### PHP Emitter Class Example - HeptaConnect

Source: https://www.heptaconnect.io/reference/adr/2021-06-17-flow-component-short-notation

This PHP code demonstrates a basic emitter class within the HeptaConnect framework. It shows dependency injection in the constructor and a run method that utilizes a packer to process data obtained from an API client. This serves as an example of the boilerplate code that the short notation aims to reduce.

```php
<?php

define(string_types=1);

namespace FooBar\Emitter;

use FooBar\Packer\BottlePacker;
use FooBar\Service\ApiClient;
use Heptacom\HeptaConnect\Dataset\Base\Contract\DatasetEntityContract;
use Heptacom\HeptaConnect\Portal\Base\Emission\Contract\EmitContextInterface;
use Heptacom\HeptaConnect\Portal\Base\Emission\Contract\EmitterContract;

class BottleEmitter extends EmitterContract
{
    private ApiClient $client;

    private BottlePacker $packer;

    public function __construct(ApiClient $client, BottlePacker $packer)
    {
        $this->client = $client;
        $this->packer = $packer;
    }

    public function run(string $externalId, EmitContextInterface $context) : ?DatasetEntityContract
    {
        return $this->packer->pack($this->client->getBottleData($externalId));
    }
}

```

--------------------------------

### FindContextFactory.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Implements the FindContextFactoryInterface, responsible for creating FindContext instances within the core package. This factory ensures consistent context creation.

```php
<?php

namespace Core\Find;

use Core\Find\Contract\FindContextFactoryInterface;
use Heptacom\HeptaConnect\Core\Flow\Contract\FlowComponentStack;
use Heptacom\HeptaConnect\Core\Flow\Contract\FlowComponentStackContext;

class FindContextFactory implements FindContextFactoryInterface
{
    public function create(FlowComponentStack $stack): FlowComponentStackContext
    {
        // ... implementation to create context ...
    }
}
```

--------------------------------

### Configure HEPTAconnect Portal with Composer

Source: https://www.heptaconnect.io/guides/portal-developer

This snippet shows a typical composer.json file for a HEPTAconnect portal package. It includes mandatory keywords, dependencies, autoloading configuration, and extra HEPTAconnect portal registration.

```json
{
    "name": "acme/heptaconnect-portal-bottle",
    "description": "HEPTAconnect portal to provide bottles",
    "type": "library",
    "keywords": [
        "heptaconnect-portal"
    ],
    "require": {
        "php": ">=7.4",
        "acme/heptaconnect-dataset-bottle": ">=1",
        "heptacom/heptaconnect-portal-base": ">=1"
    },
    "autoload": {
        "psr-4": {
            "Acme\Portal\Bottle\": "src/"
        }
    },
    "extra": {
        "heptaconnect": {
            "portals": [
                "Acme\Portal\Bottle\BottlePortal"
            ]
        }
    }
}
```

--------------------------------

### Add Entries with run() - PHP

Source: https://www.heptaconnect.io/guides/portal-developer/explorer-decoration

This method demonstrates how to add additional entries to the exploration process. It fetches data using an ApiClient, iterates over the results, and yields new entities. Dependencies include `ExploreContextInterface`, `ApiClient`, and `Bottle` classes.

```PHP
protected function run(ExploreContextInterface $context): iterable
{
    $credentials = $context->getConfig()['credentials'];
    $client = new ApiClient($credentials);

    foreach ($client->getOtherBottles() as $bottle)
    {
        $entity = new Bottle();
        $entity->setPrimaryKey((string) $bottle['id']);

        yield $entity;
    }
}
```

--------------------------------

### Changelog Entry: Fix a Bug (PHP)

Source: https://www.heptaconnect.io/guides/contributor/changelog

Example of how to document a bug fix in a changelog. It clearly states the issue that was resolved.

```markdown
### Fixed

- When passing foobaz into `\Heptacom\HeptaConnect\StuffFiddler::fiddle` did not pay respect to a GizmoStuff situation
```

--------------------------------

### Load Configuration from INI File (PHP)

Source: https://www.heptaconnect.io/guides/integrator/portal-node-configuration

This example shows how to load configuration from an INI file using the Config::helper()->ini() method. Similar to JSON and array sources, it requires the file path and a mapping array to specify which configuration values to extract. INI files offer a simple, hierarchical way to manage configuration settings.

```PHP
<?php

declare(strict_types=1);

use Heptacom\HeptaConnect\Core\Bridge\PortalNode\Configuration\Config;

$mapping = [
    'username' => 'assoc.key',
    'password' => 'assoc.secret',
    'logging' => [
        'levels' => 'list',
    ],
];
$source = Config::helper()->ini(__DIR__ . '/config.ini', $mapping);
```

--------------------------------

### Load Configuration from JSON File (PHP)

Source: https://www.heptaconnect.io/guides/integrator/portal-node-configuration

This snippet illustrates loading configuration settings from a JSON file. The Config::helper()->json() method takes the file path and a mapping array to extract the desired configuration. This is ideal for externalizing configuration into a structured, human-readable format. The mapping syntax is identical to that used for arrays.

```PHP
<?php

declare(strict_types=1);

use Heptacom\HeptaConnect\Core\Bridge\PortalNode\Configuration\Config;

$mapping = [
    'username' => 'assoc.key',
    'password' => 'assoc.secret',
    'logging' => [
        'levels' => 'list',
    ],
];
$source = Config::helper()->json(__DIR__ . '/config.json', $mapping);
```

--------------------------------

### FindActor.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Implements the FindActorInterface, containing the core logic for processing a find stack. This class is part of the core package and executes the find operation.

```php
<?php

namespace Core\Find;

use Core\Find\Contract\FindActorInterface;
use Heptacom\HeptaConnect\Core\Flow\Contract\FlowComponentStack;
use Heptacom\HeptaConnect\Core\Flow\Contract\FlowComponentStackContext;

class FindActor implements FindActorInterface
{
    public function performFind(FlowComponentStack $stack, FlowComponentStackContext $context): void
    {
        // ... implementation of find logic ...
    }
}
```

--------------------------------

### Portal Node Configuration Instruction File (PHP)

Source: https://www.heptaconnect.io/guides/integrator/portal-node-configuration

This is a placeholder PHP file for portal node configuration instructions. It uses the `Config::` facade and is intended to be filled with specific configuration logic. The `TODO` comment indicates where custom instructions should be added.

```php
<?php

declare(strict_types=1);

use Heptacom\HeptaConnect\Core\Bridge\PortalNode\Configuration\Config;

// TODO enter your Config:: instructions

```

--------------------------------

### Implement Explorer Run Method (PHP)

Source: https://www.heptaconnect.io/guides/portal-developer/explorer

The run method iterates over primary keys in the data source and yields them. It retrieves credentials from the context and uses an ApiClient to fetch object identifiers.

```php
protected function run(ExploreContextInterface $context): iterable
{
    $credentials = $context->getConfig()['credentials'];
    $client = new ApiClient($credentials);

    yield from $client->getBottleIds();
}
```

--------------------------------

### FindContext.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Implements the FindContextInterface, representing the context for a find operation within the core package. This class holds state and configuration relevant to the find process.

```php
<?php

namespace Core\Find;

use Core\Find\Contract\FindContextInterface;

class FindContext implements FindContextInterface
{
    // ... implementation details for find context ...
}
```

--------------------------------

### FindContextInterface.php Example Structure

Source: https://www.heptaconnect.io/guides/contributor/build-flow-components

Defines the interface for the context used during a find operation within the portal base package. This interface outlines the expected methods and properties for the context.

```php
<?php

namespace PortalBase\Find\Contract;

interface FindContextInterface
{
    // ... methods and properties for find context ...
}
```