Configuration Schema

To validate the pipeline configuration, Springbok uses a configuration schema. The schema is defined in the buildConfigurationSchema method of each plugin (extractor, transformer, loader and hook).

The schema definition is also used by the command springbok:generate-xsd to generate an XSD file (src/Generated/Zed/Springbok/schema.xsd) based on the Schemas built by buildConfigurationSchema of each plugin. It enables auto-completion in the pipeline configuration files.

Each pipeline configuration file needs to be wrapped around a springbok tag with the following attributes:

<springbok xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://www.example.com/schema file://../../../src/Generated/Zed/Springbok/schema.xsd"
           xmlns="http://www.example.com/schema">
           <pipeline name="product_abstract">
                 ...
            </pipeline>
</springbok>

How to define a configuration schema

Every Plugin must implement the buildConfigurationSchema method. This method should return void.

...

    /**
     * @param \Antiloop\Zed\Springbok\Business\ConfigurationSchema\SchemaBuilderInterface $schemaBuilder
     *
     * @return void
     **/
    public function buildConfigurationSchema(SchemaBuilderInterface $schemaBuilder): void
    {
        $schemaBuilder
            ->addField(name, type, required, default)
            // ...
            ->addSchema(
                name,
                setup,
                minOccurrence,
                maxOccurrence,
            );
    }

addField method

The addField method is used to add a field to the schema. The method takes four parameters:

Parameter	Description
name (string)	The name of the field
type (string)	The type of the field defined as constants in the Field class. The available types are: Field::TYPE_STRING Field::TYPE_INT Field::TYPE_BOOL
required (bool)	Whether the field is required or not. Default is false.
default (mixed)	The default value of the field. Default is null.

addSchema method

The addSchema method is used to add a configuration of a subnode to the schema. The method takes four parameters:

Parameter	Description
name (string)	The name of the subnode
setup (Closure)	A closure that takes a SchemaBuilderInterface object as a parameter to create the fields of the subnode like this: fn (SchemaBuilderInterface $schemaBuilder) => $schemaBuilder ->addField(name, type, required, default), ->addField(name, type, required, default), // ... more fields
minOccurrence (int)	The minimum number of occurrences of the subnode. Default is 0.
maxOccurrence (int)	The maximum number of occurrences of the subnode. Default is null (no maximum).

setSchemaType method

The setSchemaType method is used to define a complex type that will be referenced for the child nodes of the current schema. This is particularly useful for plugins like ForEachKeyTransformerPlugin, which require the ability to reference all transformers as child nodes, allowing for dynamic schema configurations.

The method takes one parameter:

Parameter	Description
setSchemaType (SchemaComplexType|null).	The type of the schema, represented by one of the values from the SchemaComplexType enum (e.g., transformersType). If null, no type is set.

Example

For the xml defintion of the propel-join transformer:

 ...
 <transformers>
     ...
     <propel-join
             pipelineFieldName="pipelineFieldName"
             dbFilterFieldName="dbFilterFieldName"
             modelFilterFieldName="modelFilterFieldName"
             limit="1"
     >
         <with-column name="columnName" alias="columnAlias" />
     </propel-join>
     ...
 </transformers>
...

the corresponding configuration schema in PropelJoinTransformerPlugin looks like:

...

    /**
     * @param \Antiloop\Zed\Springbok\Business\ConfigurationSchema\SchemaBuilderInterface $schemaBuilder
     *
     * @return void
     */
    public function buildConfigurationSchema(SchemaBuilderInterface $schemaBuilder): void
    {
        $schemaBuilder
            ->addField(static::ATTRIBUTE_QUERY_CLASS, FieldInterface::TYPE_STRING, true)
            ->addField(static::ATTRIBUTE_LIMIT, Field::TYPE_INT, false, 1)
            ->addField(static::ATTRIBUTE_JOIN_TYPE, FieldInterface::TYPE_STRING, false, 'left')
            ->addSchema(
                static::ATTRIBUTE_WITH_COLUMN,
                fn (SchemaBuilderInterface $schemaBuilder) => $schemaBuilder
                ->addField(static::ATTRIBUTE_NAME, Field::TYPE_STRING, true)
                ->addField(static::ATTRIBUTE_ALIAS, Field::TYPE_STRING),
                1,
            )
            ->addSchema(
                static::ATTRIBUTE_VALUE_FILTER,
                fn (SchemaBuilderInterface $schemaBuilder) => $schemaBuilder
                ->addField(static::ATTRIBUTE_DB_FIELD, FieldInterface::TYPE_STRING, true)
                ->addField(static::ATTRIBUTE_VALUE, FieldInterface::TYPE_STRING, true)
                ->addField(static::ATTRIBUTE_COMPARISON, FieldInterface::TYPE_STRING, false, ' = ');
            )
            ->addSchema(
                static::ATTRIBUTE_ON,
                fn (SchemaBuilderInterface $schemaBuilder) => $schemaBuilder
                ->addField(static::ATTRIBUTE_DB_FIELD, FieldInterface::TYPE_STRING, true)
                ->addField(static::ATTRIBUTE_FROM, FieldInterface::TYPE_STRING, true)
                ->addField(static::ATTRIBUTE_COMPARISON, FieldInterface::TYPE_STRING, false, ' = ');
            );
    }