Platform Libraries

A monorepo containing 20+ PHP libraries for the Keboola platform. All libraries are located in the libs/ directory. Each library is independently versioned and published but developed together for easier testing and cross-library changes.

Libraries

Data Movement

• input-mapping - Downloads tables/files from Storage API (CSV/Parquet support)
• output-mapping - Uploads data to Storage API with import handling
• staging-provider - Configures staging factories for local/workspace storage
• slicer - Data slicing utilities

API Clients

• api-bundle - Symfony bundle for Keboola API applications with authentication
• service-client - Generic service client for Keboola services
• query-service-api-client - Query Service API client
• sync-actions-api-php-client - Sync Actions API client
• sandboxes-service-api-client - Sandboxes Service API client
• azure-api-client - Azure API client
• vault-api-client - Vault API client

Infrastructure

• k8s-client - Kubernetes client wrapper
• messenger-bundle - Symfony Messenger bundle with Azure Service Bus support
• doctrine-retry-bundle - Database retry logic for Doctrine
• logging-bundle - Logging configuration bundle

Utilities

• configuration-variables-resolver - Resolves configuration variables
• permission-checker - Permission checking utilities
• key-generator - Key generation utilities
• settle - Settlement utilities for async operations
• php-test-utils - Shared testing utilities

Development

Environment Setup

Docker Compose Environment Variables

Before working on any library:

• Open libs/<library>/README.md and note the required variables.
• Create a ./.env file in the repository root and define those variables there.
• Start the dev container for that library and follow its README commands (e.g., docker compose run --rm dev-<library> bash).

Running Tests for a Library

Each library has a dedicated Docker Compose service. To work on a specific library:

# Enter library container
docker compose run --rm dev-<library> bash

# Inside container - install dependencies and run tests
composer install
composer tests          # PHPUnit
composer paratests      # Parallel tests (faster)

Code Quality Checks

# Inside library container
composer phpcs          # Check code style
composer phpcbf         # Fix code style automatically
composer phpstan        # Static analysis
composer check          # Validation + phpcs + phpstan
composer ci             # Full CI suite (check + tests)

Running Single Tests

# Run specific test file
docker compose run --rm dev-input-mapping bash -c "vendor/bin/phpunit tests/Functional/DownloadFilesTest.php"

# Run specific test method
docker compose run --rm dev-input-mapping bash -c "vendor/bin/phpunit --filter testTableManifest tests/Functional/DownloadTablesTest.php"

Continuous Integration

CI runs on GitHub Actions (.github/workflows/).

• ci.yml (on every branch push; there is no pull_request trigger — PR checks attach to the push-triggered run on the head SHA) detects affected libraries via bin/ci/affected-libraries.php — the changed libraries plus their transitive *@dev dependents — and runs only the matching per-library workflows (lib-<lib>.yml). Infra-wide changes test all libraries. The tests-result job is the single required status check.
• On every branch push, affected libraries are split/published to their standalone repos (so composer require keboola/<lib>:dev-<branch> works in dependents).
• release.yml publishes a single library on a refs/tags/<lib>/* tag push.

Publishing uses the .github/actions/split-library composite action (wraps bin/split-repo.sh), which mints a short-lived GitHub App installation token at runtime from SPLIT_APP_ID (variable) + SPLIT_APP_PRIVATE_KEY (secret), scoped to the single target repo. CI configuration is provisioned by a repo admin: non-sensitive values (Storage API URLs, HOSTNAME_SUFFIX_GCP, OUTPUT_MAPPING__BIGQUERY_STORAGE_API_URL, AWS access key IDs, SPLIT_APP_ID) are repository variables (vars.*); Storage API tokens, Terraform secret keys and SPLIT_APP_PRIVATE_KEY are repository secrets (secrets.*). The full list is in CLAUDE.md.

To run the CI detection tool's own checks locally:

docker compose run --rm dev82 bash -c 'cd bin/ci && composer ci'

Contributing

Commit Message Format

This project uses Conventional Commits v1.0.0.

IMPORTANT: Since this is a monorepo, commit messages MUST include the library name:

Format: <type>(<library-name>): <description>

Examples:

• feat(input-mapping): add support for Parquet format downloads
• fix(output-mapping): resolve memory leak in large file uploads
• docs(service-client): update README with new endpoint examples

License

MIT licensed, see LICENSE file.