Skip to content

Latest commit

 

History

History
264 lines (190 loc) · 8.72 KB

rules.md

File metadata and controls

264 lines (190 loc) · 8.72 KB
Raw

Code generation rules

Since every application has it's own rules on how to write and structure code, we made it possible to configure the way your code is auto generated. You can specify your own rules and apply them to the code generator.

The goal of a rule is to run a code assembler. Here you can find a full list of built-in code assemblers.

Built-in rules

AssemblerRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;

$rule = Rules\AssembleRule(new Assembler\GetterAssembler($someGetterOptions))

The AssemblerRule will always apply an assembler in the right context. This way, the code is added during every code generation command.

In the example above, a getter will be created for every property in the SOAP type.

ClientMethodMatchesRule

use My\Project\CodeGenerator\Assembler as CustomAssembler;
use Phpro\SoapClient\CodeGenerator\Rules;

new Rules\ClientMethodMatchesRule(
    new Rules\AssembleRule(new CustomAssembler\RemoveClientMethodAssembler()),
    '/demoSetup$/'
)

The ClientMethodMatchesRule can be used in the types generation command and contains a subRule and a regular expression. The subRule is mostly a regular AssembleRule, but can be any class that implements the RuleInterface. The regular expression will be matched against the method name added to the generated Client. If the regular expression matches and the subRule is accepted, the defined assembler will run.

In the example above, a custom RemoveClientMethodAssembler is is used to remove the demoSetup method from the Client completely.

IsAbstractTypeRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;
use Soap\Engine\Metadata\Metadata;

assert($metadata instanceof Metadata);

new Rules\IsAbstractTypeRule(
    $metadata,
    new Rules\AssembleRule(new Assembler\AbstractClassAssembler())
)

The IsAbstractTypeRule can be used in the "types" generation command and contains the engine's metadata and a subRule. The rule will detect all abstract types based on the provided SOAP metadata. If the type matches an abstract type and the subRule is accepted, the defined assembler will run.

This rule can be used to e.g. mark the PHP class as abstract.

IsExtendingTypeRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;
use Soap\Engine\Metadata\Metadata;

assert($metadata instanceof Metadata);

new Rules\IsExtendingTypeRule(
    $metadata,
    new Rules\AssembleRule(new Assembler\ExtendingTypeAssembler())
)

The IsExtendingTypeRule can be used in the "types" generation command and contains the engine's metadata and a subRule. The rule will detect all types that extend another SOAP type based on the provided SOAP metadata. If the type matches an abstract type and the subRule is accepted, the defined assembler will run.

This rule can be used to make the PHP class of a type extend the base PHP class that is provided by the metadata.

IsRequestRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;
use Soap\Engine\Metadata\Metadata;

assert($metadata instanceof Metadata);

new Rules\IsRequestRule(
    $metadata,
    new Rules\AssembleRule(new Assembler\RequestAssembler())
)

The IsRequestRule can be used in the "types" generation command and contains the engine's metadata and a subRule. The rule will try to guess all request types based on the provided SOAP metadata. If the type matches a request type and the subRule is accepted, the defined assembler will run.

This rule can be used to e.g. add the required RequestInterface to request objects.

IsResultRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;
use Soap\Engine\Metadata\Metadata;

assert($metadata instanceof Metadata);

new Rules\IsResultRule(
    $metadata,
    new Rules\AssembleRule(new Assembler\ResultAssembler())
)

The IsResultRule can be used in the "types" generation command and contains the engine's metadata and a subRule. The rule will try to guess all response types based on the provided SOAP metadata. If the type matches a response type and the subRule is accepted, the defined assembler will run.

This rule can be used to e.g. add the required ResultInterface to request objects.

MultiRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;

$rule = new Rules\MultiRule([
    new Rules\AssembleRule(new Assembler\GetterAssembler($someGetterOptions)),
    new Rules\AssembleRule(new Assembler\SetterAssembler()),
]);

The MultiRule makes it possible to define multiple rules that need to be applied on a SOAP type. This rule can be very handy in combination with rules like the TypeMapRule or TypenameMatchesRule. By using the MultiRule, you can e.g. specify the regex once but run multiple assemblers.

In the example above, both the getters and setters are added for every property in the SOAP type.

PropertynameMatchesRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;

new Rules\PropertynameMatchesRule(
    new Rules\AssembleRule(new Assembler\InterfaceAssembler(ApiKeyAwareInterface::class)),
    '/^ApiKey$/'
)

The PropertynameMatchesRule can be used in the types generation command and contains a subRule and a regular expression. The subRule is mostly a regular AssmbleRule, but can be any class that implements the RuleInterface. The regular expression will be matched against the normalized SOAP property name. If the regular expression matches and the subRule is accepted, the defined assembler will run.

In the example above, the ApiKeyAwareInterface is added to the class if the SOAP property ApiKey exists.

TypeMapRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;

$resultProviderRule = new Rules\AssembleRule(new Assembler\ResultProviderAssembler());
$defaultRule = new Rules\AssembleRule(new Assembler\ResultAssembler());

new Rules\TypeMapRule(
    [
        'SomeType' => $resultProviderRule,
        'NullType' => null
    ]
    $defaultRule
)

The TypeMapRule can be used in the types generation command and contains a map of types with a subrule. When the SOAP type is found in the TypeMap, the configured rule will be applied. The last parameter is the default rule. When the type cannot be found in the TypeMap, the default Rule will apply. This rule will make it easy to apply some specific rules for specific templates.

In the example above, the ResultProviderInterface is added to the class if the SOAP type equals SomeType. On the SOAP type NullType, no actions are executed. On all other SOAP types, the ResultInterface is added.

TypenameMatchesRule

use Phpro\SoapClient\CodeGenerator\Assembler;
use Phpro\SoapClient\CodeGenerator\Rules;

new Rules\TypenameMatchesRule(
    new Rules\AssembleRule(new Assembler\RequestAssembler()),
    '/Request$/'
)

The TypenameMatchesRule can be used in the types generation command and contains a subRule and a regular expression. The subRule is mostly a regular AssembleRule, but can be any class that implements the RuleInterface. The regular expression will be matched against the normalized SOAP type name. If the regular expression matches and the subRule is accepted, the defined assembler will run.

In the example above, the RequestInterface is added to the class if the SOAP type ends on Request.

Creating your own Rule

Creating your own Rule is pretty easy. The only thing you'll need to do is implementing the RuleInterface.

/**
 * Interface RuleInterface
 *
 * @package Phpro\SoapClient\CodeGenerator\Rules
 */
interface RuleInterface
{
    /**
     * @param ContextInterface $context
     *
     * @return bool
     */
    public function appliesToContext(ContextInterface $context);

    /**
     * @param ContextInterface $context
     */
    public function apply(ContextInterface $context);
}

Possible contexts:

  • ClassMapContext: Triggered during the generate:classmap command.
  • TypeContext: Triggered during the generate:types command for every type in the SOAP scheme.
  • PropertyContext: Triggered during the generate:types command for every property in a SOAP type.
  • FileContext: Triggered during every generate command.