keboola / php-component
Helper classes for developing Keboola PHP components
Installs: 63 402
Dependents: 6
Suggesters: 0
Security: 0
Stars: 0
Watchers: 17
Forks: 1
Open Issues: 5
Type:project
Requires
- php: >=8.1
- ext-json: *
- keboola/common-exceptions: ^1.2
- monolog/monolog: ^2.3
- symfony/config: ^5.4|^6.0
- symfony/filesystem: ^5.4|^6.0
- symfony/finder: ^5.4|^6.0
- symfony/property-access: ^5.4|^6.0
- symfony/serializer: ^5.4|^6.0
Requires (Dev)
- devedge/sami-github: ^1.0
- keboola/coding-standard: ^15.0
- keboola/php-temp: ^2.0
- phpstan/phpstan: ^1.4
- phpunit/phpunit: ^9.5
- dev-master
- 10.1.6
- 10.1.5
- 10.1.4
- 10.1.3
- 10.1.2
- 10.1.1
- 10.1.0
- 10.0.2
- 10.0.1
- 10.0.0
- 9.4.0
- 9.3.0
- 9.2.0
- 9.1.2
- 9.1.1
- 9.1.0
- 9.0.0
- 8.3.0
- 8.2.0
- 8.1.2
- 8.1.1
- 8.1.0
- 8.0.0
- 7.0.3
- 7.0.2
- 7.0.1
- 7.0.0
- 6.0.1
- 6.0.0
- 5.0.0
- 4.4.2
- 4.4.1
- 4.4.0
- 4.3.0
- 4.2.0
- 4.1.1
- 4.1.0
- 4.0.0
- 3.0.0
- 2.1.0
- 2.0.0
- 1.0.0
- dev-miro-php-8
- dev-webrouse-COM-153-monolog-fix
This package is auto-updated.
Last update: 2024-10-30 08:54:00 UTC
README
General library for php component running in KBC. The library provides function related to Docker Runner.
Installation
composer require keboola/php-component
Usage
Create a subclass of BaseComponent
.
<?php class Component extends \Keboola\Component\BaseComponent { protected function run(): void { // get parameters $parameters = $this->getConfig()->getParameters(); // get value of customKey.customSubKey parameter and fail if missing $customParameter = $this->getConfig()->getValue(['parameters', 'customKey', 'customSubKey']); // get value with default value if not present $customParameterOrNull = $this->getConfig()->getValue(['parameters', 'customKey'], 'someDefaultValue'); // get manifest for input file $fileManifest = $this->getManifestManager()->getFileManifest('input-file.csv'); // get manifest for input table $tableManifest = $this->getManifestManager()->getTableManifest('in.tableName'); // write manifest for output file $this->getManifestManager()->writeFileManifest( 'out-file.csv', (new OutFileManifestOptions()) ->setTags(['tag1', 'tag2']) ); // write manifest for output table $this->getManifestManager()->writeTableManifest( 'data.csv', (new OutTableManifestOptions()) ->setPrimaryKeyColumns(['id']) ->setDestination('out.report'), true // legacy manifest format flag ); } protected function customSyncAction(): array { return ['result' => 'success', 'data' => ['joe', 'marry']]; } protected function getSyncActions(): array { return ['custom' => 'customSyncAction']; } }
Use this src/run.php
template.
<?php declare(strict_types=1); use Keboola\Component\Logger; require __DIR__ . '/../vendor/autoload.php'; $logger = new Logger(); try { $app = new MyComponent\Component($logger); $app->execute(); exit(0); } catch (\Keboola\Component\UserException $e) { $logger->error($e->getMessage()); exit(1); } catch (\Throwable $e) { $logger->critical( get_class($e) . ':' . $e->getMessage(), [ 'errFile' => $e->getFile(), 'errLine' => $e->getLine(), 'errCode' => $e->getCode(), 'errTrace' => $e->getTraceAsString(), 'errPrevious' => $e->getPrevious() ? get_class($e->getPrevious()) : '', ] ); exit(2); }
Sync actions support
Sync actions can be called directly via API. API will block and wait for the result. The correct action is selected based on the action
key of config. BaseComponent
class handles the selection automatically. Also it handles serialization and output of the action result - sync actions must output valid JSON.
To implement a sync action
- add a method in your
Component
class. The naming is entirely up to you. - override the
Component::getSyncActions()
method to return array containing your sync actions names as keys and corresponding method names from theComponent
class as values. - return value of the method will be serialized to json
Customizing config
Custom getters in config
You might want to add getter methods for custom parameters in the config. That way you don't need to remember exact keys (parameters.customKey.customSubKey
), but instead use a method to retrieve the value ($config->getCustomSubKey()
).
Simply create your own Config
class, that extends BaseConfig
and override \Keboola\Component\BaseComponent::getConfigClass()
method to return your new class name.
class MyConfig extends \Keboola\Component\Config\BaseConfig { public function getCustomSubKey() { $defaultValue = 0; return $this->getValue(['parameters', 'customKey', 'customSubKey'], $defaultValue); } }
and
class MyComponent extends \Keboola\Component\BaseComponent { protected function getConfigClass(): string { return MyConfig::class; } }
Custom parameters validation
To validate input parameters extend \Keboola\Component\Config\BaseConfigDefinition
class. By overriding the getParametersDefinition()
method, you can validate the parameters part of the config. Make sure that you return the actual node you add, not TreeBuilder
. You can use parent::getParametersDefinition()
to get the default node or you can build it yourself.
If you need to validate other parts of config as well, you can override getRootDefinition()
method. Again, make sure that you return the actual node, not the TreeBuilder
.
class MyConfigDefinition extends \Keboola\Component\Config\BaseConfigDefinition { protected function getParametersDefinition() { $parametersNode = parent::getParametersDefinition(); $parametersNode ->isRequired() ->children() ->arrayNode('customKey') ->isRequired() ->children() ->integerNode('customSubKey') ->isRequired(); return $parametersNode; } }
Note: Your build may fail if you use PhpStan because of complicated type behavior of the \Symfony\Component\Config\Definition\Builder\ExprBuilder::end()
method, so you may need to ignore some errors.
Again you need to supply the new class name in your component
class MyComponent extends \Keboola\Component\BaseComponent { protected function getConfigDefinitionClass(): string { return MyConfigDefinition::class; } }
If any constraint of config definition is not met a UserException
is thrown. That means you don't need to handle the messages yourself.
Migration from version 6 to version 7
The default entrypoint of component (in index.php
) changed from BaseComponent::run()
to BaseComponent::execute()
. Please also note, that the run
method can no longer be public and can only be called from inside the component now.
More reading
For more information, please refer to the generated docs. See development guide for help with KBC integration.
License
MIT licensed, see LICENSE file.