Development Environment

Docker

The Transfer Object repository includes a development environment facilitated by a Docker SDK shell script.

To view all available commands and arguments (e.g., phpunit, phpstan, etc.), run the following command:

$ docker/sdk

Project Installation

Important

To begin working with the Transfer Object project, please ensure you have Docker and Docker Compose installed on your system.

Execute command bellow to install the Project:

$ docker/sdk install

CaptainHook Installation

Note

CaptainHook is a Git hook library for PHP projects.

$ docker/sdk hook-install

Verify CaptainHook Installation:

$ docker/sdk hook config:info

Shell configuration

In order to add docker/sdk autocomplition and its alias ds:

1. Add to ~/.bashrc, replacing {project-path} with your project path:

# source the composer autocompletion script
if [ -f {project-path}/docker/bash/sdk-autocomplete.sh ]; then
  source {project-path}/docker/bash/sdk-autocomplete.sh
fi

# ds alias
alias ds="docker/sdk"

2. Reload shell

$ source ~/.bashrc

3. Test alias autocompletion by typing ds followed by <tab>
4. Test full command autocompletion by typing docker/sdk followed by <tab>

Helper Snippets

Definition Schema

To actualize definition.schema.json with new Symfony constrains attributes, following shell script should be executed:

#!/bin/bash

# Configuration
DIRECTORY="vendor/symfony/validator/Constraints"
PREFIX="sf-assert:"

# Check if directory exists
if [ ! -d "$DIRECTORY" ]; then
    echo "Error: Directory $DIRECTORY not found."
    exit 1
fi

# Search for PHP files containing the Attribute marker
# Sort the results
# Extract the filename without extension
# Prepend the prefix and wrap in JSON format
grep -l "#\[\\\\Attribute(" "$DIRECTORY"/*.php | xargs -I {} basename {} .php | sort | sed "s/.*/{ \"const\": \"$PREFIX&\" },/"

Configuration File List

To actualise the configuration list var/config/config.list.txt following command should be executed:

$ find . -type f -name "*.config.yml" > ./var/config/config.list.txt

Demo

Transfer Generate

To see how the Transfer Object generator works, please follow the steps below:

1. Add or edit a definition file in: examples/config/transfer-generator/definition
2. Run the console command to generate Transfer objects:

$ docker/sdk to-generate ./examples/config/transfer-generator/generator.config.yml

3. Check the generated Transfer objects in: examples/Generated/TransferGenerator

Tip

The examples examples/try-transfer-generator.php illustrate how to generate Transfer objects using the Facade methods. They can also be used as a playground for Transfer objects generated by the console command as well. You can run examples from your IDE (using the container's PHP) or inside Docker container.

Running the console command without argument will generate project's internal transfer objects.

$ docker/sdk to-generate

Alternatively Transfer Object generator can be run directly from container.

1. Open container cli:

$ docker/sdk cli

2. Run the generator command:

$ ./bin/transfer-generate -c ./examples/config/transfer-generator/generator.config.yml

or the same by composer:

$ composer transfer-generate -- -c ./examples/config/transfer-generator/generator.config.yml

Transfer Generate Bulk

The Transfer Object Bulk generator can be run as:

$ docker/sdk to-generate-bulk [BULK]

where [BULK] is a path to the configuration bulk file.

Note

Internally project uses bulk file located at ./var/config/config.list.txt running the command above without argument will fallback to the internal project bulk file.

Alternatively Transfer Object Bulk generator can be run directly from container:

1. Open container cli:

$ docker/sdk cli

2. Run the generator command:

$ ./bin/transfer-generate-bulk -b ./var/config/config.list.txt

or the same by composer:

$ composer composer transfer-generate-bulk -- -b ./var/config/config.list.txt

Definition Generate

To see how the Definition generator works, please run command bellow:

$ docker/sdk df-generate

Alternatively Definition generator can be run directly from container:

1. Open container cli:

$ docker/sdk cli

2. Run the generator command:

$ ./bin/definition-generate

or the same by composer:

$ composer definition-generate

Debug

Transfer Object

The Transfer Object generator might fail in the middle showing the error message. The process is successful when all Transfer Objects are generated.

The Transfer Objects are generated on the directory {path-to-transfer-object-directory}/_tmp/{uuid} preventing breaking the application on failure. In case of validation error, the temporary directory is automatically deleted.

Caution

In case of critical errors the temporary directory migh not be deleted.

Definition File

Each Transfer Objects' includes doc-block with path to the definition file:

/**
 * Specification:
 * - Class is automatically generated based on a definition file.
 * - To modify it, please update the corresponding definition file and run the generator again.
 *
 * Note: Do not manually edit this file, as changes will be overwritten.
 *
 * @see /doc/samples/config/transfer-generator/definition/customer.transfer.yml Definition file path.
 */

It helps to find faster the necessary definition file.

Xdebug Configuration

Note

Xdebug is disabled by default.

To enable Xdebug, execute:

$ docker/sdk -x start

To enable Xdebug profiler, execute:

$ docker/sdk -xp start

Alternatively Xdebug mode can be managed by .env

XDEBUG_MODE=off

with following

$ docker/sdk start