Extractor Bundle Laravel Package

Getting Started

Frame it correctly before you install anything. keboola/extractor-bundle is a Symfony bundle, not a Laravel package. Its job is to scaffold Keboola extractor components — standalone Docker-packaged PHP jobs that pull data from an external API into Keboola Storage. If your goal is "pull Keboola data into my Laravel app," this is the wrong package — use the Keboola Storage/Job Queue REST APIs instead. If your goal is "build a Keboola extractor," read on.

Minimal steps:

1. Confirm access and licensing. The canonical repo is Bitbucket and semi-private; there is no license metadata surfaced and zero Packagist presence in the provided data. Get written confirmation you can vendor/fork it before writing a line of code.
2. Create a standalone Composer project (its own repo, its own composer.json, its own Docker image). Do not add it to a Laravel app's dependency graph — the Symfony minor-version constraints and the keboola/php-component peer dependency will almost certainly conflict with a current Laravel install.
3. Add a repositories entry pointing at the Bitbucket VCS and pin a specific commit SHA. CI will need SSH deploy credentials.
4. composer require keboola/extractor-bundle in that project, then register it in a Symfony Kernel via config/bundles.php. There is no ExtractorBundleServiceProvider and no package auto-discovery.
5. Read the bundle's own Tests/ directory first. For Keboola bundles, the functional tests are usually the most reliable documentation of how a working extractor wires config → API client → CSV output.

Where to look first, in order:

• Tests/ — functional tests showing the full run lifecycle
• The base run-action class and any abstract extractor class — this is your extension point
• Output manifest helpers — how tables and columns get declared
• Docker setup shipped with the bundle or the Keboola component template

First use case: the smallest possible extractor. One API endpoint, one output table, a hand-written .manifest, logs to stdout. Validate it with docker run against a real (non-production) Keboola project before you add pagination, auth flows, or incremental state. Getting the runtime contract right — exit codes, /data paths, manifest shape — is 80% of the learning curve; the extraction logic is the easy part.

If you're a Laravel developer, budget 1–2 weeks to be productive. Laravel familiarity does not transfer to the bundle's idioms: component conventions (config.json, config rows, run action, state files), Docker packaging, Storage API basics, and Symfony DI are all new surface.

Implementation Patterns

Separate deployable, invoked from Laravel. The recommended architecture is: the extractor lives in its own image built on this bundle; your Laravel app triggers it via a queued job that either shells out (Symfony\Process / proc_open) or calls an internal HTTP endpoint. Data lands in Keboola Storage — not in your application container. This keeps two very different dependency graphs from ever touching.

Extend the base classes, don't fight them. The bundle exists to remove boilerplate for config parsing, run handling, logging, error reporting, and output generation. The idiomatic pattern is: subclass the provided base extractor/run action, implement only the "fetch from source and write rows" method, and let the parent handle the lifecycle. Resisting this and writing your own run() defeats the purpose of the dependency.

Model configuration as config rows. Keboola's convention is a top-level config.json plus per-row configuration (one row per source endpoint/table). Parse config once at startup via the bundle's config handler, loop rows, and emit one output table per row. This maps cleanly onto "one connector, N tables" and is what reviewers of Keboola components expect.

Incremental state is a round-trip contract. Read last-run state from the input state file, write updated state (high-water-mark timestamps, cursors, page tokens) to the output state file. Wrap the whole extraction so state is only committed on success — a partial write followed by a crash is how you get silent data gaps. Treat the state file as the source of truth for "where did we leave off," never an in-memory variable.

Output tables plus manifests, always. Every CSV you write to /data/out/tables/ needs a matching .manifest declaring columns, primary_key, and incremental where relevant. Use the bundle's manifest helpers rather than hand-rolling JSON — schema drift between CSV and manifest is the single most common "it ran but the data is wrong" bug.

Error semantics are load-bearing. The component contract distinguishes user errors (bad config, invalid credentials — should fail fast, do not retry) from application errors (transient API failure, network blip — retryable). Map these to the correct exit codes via the bundle's exception types. If you collapse everything into a generic failure, Keboola's job queue will retry the wrong things and not retry the right ones.

Isolate runtime concerns behind one adapter. If you ever must embed (fallback, not default), register the bundle's services manually in a Laravel service provider and put all Keboola runtime concerns — state files, config parsing, /data paths — behind one adapter class. Do not let /data/... strings leak into your application code.

Logging: PSR-3 to stdout. The bundle expects a Monolog/PSR-3 logger. Log to stdout/stderr so the Keboola platform captures it; do not write log files inside the container. Include the config row ID in log context so operators can tell which source failed.

Pin, fork, and own it. Vendor or fork into your own VCS at a specific commit. Document the fork point. There is no ecosystem pressure to keep constraints current, so you will be the one bumping Symfony/PHP constraints when the platform moves.

Gotchas and Tips

Composer resolution is your first gate — test it first. Before any design work, spend a day on a spike: composer require the pinned tag into a bare PHP image and into a clone of your Laravel app, and record what happens. That single test decides whether the separate-deployable architecture is even necessary or whether you can share anything. Expect conflicts with Laravel's Symfony 6/7 components.

There is no Laravel service provider. Package auto-discovery will not find this. No ExtractorBundleServiceProvider exists — it assumes a Symfony kernel with a bundle registry. Attempting to boot it inside Laravel's container is technically possible via manual bridging but imports the full Symfony DI surface into your app and buys you nothing.

Verify the runtime dependency chain before committing. Check: PHP floor vs. your runtime, Symfony component versions vs. Laravel's, PSR-3 logger binding available, whether a full Kernel is required at boot, and which keboola/php-component version it pairs with. Much of the extractor scaffolding may have been absorbed into php-component — confirm with Keboola docs whether this bundle is still the recommended path or effectively superseded.

State-file failures are silent. A lost or malformed state file causes either a full reload (wasteful, sometimes rate-limited) or, worse, data gaps that look like successful runs. Add explicit assertions that the state file was read and that the new cursor is >= the old one before writing.

Memory is your ceiling, not the library. Extractors hold batches in PHP memory depending on your implementation. Stream or chunk large extracts; set container memory limits explicitly per extractor. The bundle does nothing to protect you here.

Exit codes drive retry behavior. Get this wrong and the platform will retry user errors forever and fail transient errors permanently. Test both paths deliberately: an invalid token should be a clean user error, and a 503 from the source should be retryable.

Upstream API changes and rate limiting are your most common real failure — and the package mitigates neither. Build rate-limit backoff and pagination handling into your extractor, and version-pin your source-API assumptions in tests.

"Zero stars" is a hosting artifact, not a quality signal — but the practical implication is real: zero dependents means no external bug-fixing pressure and no public failure corpus. Bitbucket hosting means no meaningful star metric. Budget for owning a fork; there is no community safety net and no implied commercial support. Your support path is Keboola's developer docs and any existing commercial relationship with Keboola, not this library.

Debug locally with the /data convention reproduced. Before reaching for the platform, run the image with a local directory mounted at /data containing a real config.json, and inspect /data/out/tables/. Most "it fails in Keboola" issues reproduce instantly here.

Extension points to know: the base extractor/run-action class (your implementation surface), the config handler (override for custom validation), the manifest/output helpers (override for non-CSV outputs), and the logger binding. Everything else you should let the bundle own.