Generate backed enums from XSD

phpro · Dec 20, 2024 · 9b24e19 · 9b24e19
1 parent 25a2f2e
commit 9b24e19
Show file tree

Hide file tree

Showing 18 changed files with 391 additions and 73 deletions.
diff --git a/composer.json b/composer.json
@@ -17,9 +17,9 @@
         "laminas/laminas-code": "^4.14.0",
         "php-soap/cached-engine": "~0.3",
         "php-soap/engine": "^2.14.0",
-        "php-soap/encoding": "~0.14",
+        "php-soap/encoding": "~0.15",
         "php-soap/psr18-transport": "^1.7",
-        "php-soap/wsdl-reader": "~0.20",
+        "php-soap/wsdl-reader": "~0.21",
         "psr/event-dispatcher": "^1.0",
         "psr/log": "^1.0 || ^2.0 || ^3.0",
         "symfony/console": "~5.4 || ~6.0 || ~7.0",

diff --git a/spec/Phpro/SoapClient/CodeGenerator/Util/NormalizerSpec.php b/spec/Phpro/SoapClient/CodeGenerator/Util/NormalizerSpec.php
@@ -60,6 +60,24 @@ function it_noramizes_properties()
         $this->normalizeProperty('My-./final*prop_123')->shouldReturn('MyFinalProp_123');
     }
 
+    function it_normalizes_enum_cases()
+    {
+        $this->normalizeEnumCaseName('')->shouldReturn('Empty');
+
+        $this->normalizeEnumCaseName('0')->shouldReturn('Value_0');
+        $this->normalizeEnumCaseName('1')->shouldReturn('Value_1');
+        $this->normalizeEnumCaseName('10000')->shouldReturn('Value_10000');
+
+        $this->normalizeEnumCaseName('final')->shouldReturn('final');
+        $this->normalizeEnumCaseName('Final')->shouldReturn('Final');
+        $this->normalizeEnumCaseName('UpperCased')->shouldReturn('UpperCased');
+        $this->normalizeEnumCaseName('my-./*prop_123')->shouldReturn('myProp_123');
+        $this->normalizeEnumCaseName('My-./*prop_123')->shouldReturn('MyProp_123');
+        $this->normalizeEnumCaseName('My-./final*prop_123')->shouldReturn('MyFinalProp_123');
+
+        $this->normalizeEnumCaseName('1 specific option')->shouldReturn('Value_1SpecificOption');
+    }
+
     function it_normalizes_datatypes()
     {
         $this->normalizeDataType('string')->shouldReturn('string');

diff --git a/src/Phpro/SoapClient/CodeGenerator/Assembler/ClassMapAssembler.php b/src/Phpro/SoapClient/CodeGenerator/Assembler/ClassMapAssembler.php
@@ -4,6 +4,7 @@
 
 use Phpro\SoapClient\CodeGenerator\Context\ClassMapContext;
 use Phpro\SoapClient\CodeGenerator\Context\ContextInterface;
+use Phpro\SoapClient\CodeGenerator\Model\Type;
 use Phpro\SoapClient\CodeGenerator\Model\TypeMap;
 use Phpro\SoapClient\Exception\AssemblerException;
 use Laminas\Code\Generator\ClassGenerator;
@@ -48,31 +49,66 @@ public function assemble(ContextInterface $context)
             $file->setUse(ClassMapCollection::class);
             $file->setUse(ClassMap::class);
             $linefeed = $file::LINE_FEED;
-            $classMap = $this->assembleClassMap($typeMap, $linefeed, $file->getIndentation());
-            $code = $this->assembleClassMapCollection($classMap, $linefeed).$linefeed;
-            $class->addMethodFromGenerator(
-                (new MethodGenerator('getCollection'))
-                    ->setStatic(true)
-                    ->setBody('return '.$code)
-                    ->setReturnType(ClassMapCollection::class)
-            );
+            $indentation = $file->getIndentation();
+
+            $class->addMethodFromGenerator($this->generateTypes($typeMap, $linefeed, $indentation));
+            $class->addMethodFromGenerator($this->generateEnums($typeMap, $linefeed, $indentation));
         } catch (\Exception $e) {
             throw AssemblerException::fromException($e);
         }
     }
 
-    /***
-     * @param TypeMap $typeMap
-     * @param string  $linefeed
-     * @param string  $indentation
-     *
-     * @return string
+    private function generateTypes(
+        TypeMap $typeMap,
+        string $linefeed,
+        string $indentation,
+    ): MethodGenerator {
+        $classMap = $this->assembleClassMap(
+            $typeMap,
+            $linefeed,
+            $indentation,
+            static fn (Type $type) => !(new IsConsideredScalarType())($type->getMeta())
+        );
+        $code = $this->assembleClassMapCollection($classMap, $linefeed).$linefeed;
+
+        return (new MethodGenerator('types'))
+            ->setStatic(true)
+            ->setBody('return '.$code)
+            ->setReturnType(ClassMapCollection::class);
+    }
+
+    private function generateEnums(
+        TypeMap $typeMap,
+        string $linefeed,
+        string $indentation,
+    ): MethodGenerator {
+        $classMap = $this->assembleClassMap(
+            $typeMap,
+            $linefeed,
+            $indentation,
+            static fn (Type $type) => (new IsConsideredScalarType())($type->getMeta())
+                && $type->getMeta()->enums()->isSome()
+        );
+        $code = $this->assembleClassMapCollection($classMap, $linefeed).$linefeed;
+
+        return (new MethodGenerator('enums'))
+            ->setStatic(true)
+            ->setBody('return '.$code)
+            ->setReturnType(ClassMapCollection::class);
+    }
+
+    /**
+     * @param \Closure(Type): bool $predicate
      */
-    private function assembleClassMap(TypeMap $typeMap, string $linefeed, string $indentation): string
-    {
+    private function assembleClassMap(
+        TypeMap $typeMap,
+        string $linefeed,
+        string $indentation,
+        \Closure $predicate
+    ): string {
         $classMap = [];
         foreach ($typeMap->getTypes() as $type) {
-            if ((new IsConsideredScalarType())($type->getMeta())) {
+            if (!$predicate($type)) {
                 continue;
             }
 

diff --git a/src/Phpro/SoapClient/CodeGenerator/ClassMapGenerator.php b/src/Phpro/SoapClient/CodeGenerator/ClassMapGenerator.php
@@ -4,14 +4,13 @@
 
 use Phpro\SoapClient\CodeGenerator\Context\ClassMapContext;
 use Phpro\SoapClient\CodeGenerator\Context\FileContext;
+use Phpro\SoapClient\CodeGenerator\Model\Type;
 use Phpro\SoapClient\CodeGenerator\Model\TypeMap;
 use Phpro\SoapClient\CodeGenerator\Rules\RuleSetInterface;
 use Laminas\Code\Generator\FileGenerator;
 
 /**
- * Class ClassMapGenerator
- *
- * @package Phpro\SoapClient\CodeGenerator
+ * @template-implements GeneratorInterface<TypeMap>
  */
 class ClassMapGenerator implements GeneratorInterface
 {

diff --git a/src/Phpro/SoapClient/CodeGenerator/ClientFactoryGenerator.php b/src/Phpro/SoapClient/CodeGenerator/ClientFactoryGenerator.php
@@ -7,6 +7,7 @@
 use Phpro\SoapClient\Caller\EngineCaller;
 use Phpro\SoapClient\Caller\EventDispatchingCaller;
 use Phpro\SoapClient\CodeGenerator\Context\ClientFactoryContext;
+use Phpro\SoapClient\CodeGenerator\Model\Type;
 use Phpro\SoapClient\Soap\DefaultEngineFactory;
 use Phpro\SoapClient\Soap\EngineOptions;
 use Soap\Encoding\EncoderRegistry;
@@ -16,19 +17,17 @@
 use Laminas\Code\Generator\MethodGenerator;
 
 /**
- * Class ClientBuilderGenerator
- *
- * @package Phpro\SoapClient\CodeGenerator
+ * @template-implements GeneratorInterface<ClientFactoryContext>
  */
 class ClientFactoryGenerator implements GeneratorInterface
 {
     const BODY = <<<BODY
 \$engine = DefaultEngineFactory::create(
     EngineOptions::defaults(\$wsdl)
         ->withEncoderRegistry(
-            EncoderRegistry::default()->addClassMapCollection(
-                %2\$s::getCollection()
-            )
+            EncoderRegistry::default()
+                ->addClassMapCollection(%2\$s::types())
+                ->addBackedEnumClassMapCollection(%2\$s::enums())
         )
         // If you want to enable WSDL caching:
         // ->withCache() 

diff --git a/src/Phpro/SoapClient/CodeGenerator/ClientGenerator.php b/src/Phpro/SoapClient/CodeGenerator/ClientGenerator.php
@@ -15,9 +15,7 @@
 use Laminas\Code\Generator\FileGenerator;
 
 /**
- * Class ClientGenerator
- *
- * @package Phpro\SoapClient\CodeGenerator
+ * @template-implements GeneratorInterface<Client>
  */
 class ClientGenerator implements GeneratorInterface
 {

diff --git a/src/Phpro/SoapClient/CodeGenerator/ConfigGenerator.php b/src/Phpro/SoapClient/CodeGenerator/ConfigGenerator.php
@@ -5,13 +5,12 @@
 use Phpro\SoapClient\CodeGenerator\Config\Config;
 use Phpro\SoapClient\CodeGenerator\Context\ConfigContext;
 use Laminas\Code\Generator\FileGenerator;
+use Phpro\SoapClient\CodeGenerator\Model\Type;
 use Phpro\SoapClient\Soap\DefaultEngineFactory;
 use Phpro\SoapClient\Soap\EngineOptions;
 
 /**
- * Class ConfigGenerator
- *
- * @package Phpro\SoapClient\CodeGenerator
+ * @template-implements GeneratorInterface<ConfigContext>
  */
 class ConfigGenerator implements GeneratorInterface
 {

diff --git a/src/Phpro/SoapClient/CodeGenerator/EnumerationGenerator.php b/src/Phpro/SoapClient/CodeGenerator/EnumerationGenerator.php
@@ -0,0 +1,77 @@
+<?php
+
+namespace Phpro\SoapClient\CodeGenerator;
+
+use Laminas\Code\Generator\DocBlockGenerator;
+use Phpro\SoapClient\CodeGenerator\Model\Type;
+use Phpro\SoapClient\CodeGenerator\Util\Normalizer;
+use Laminas\Code\Generator\EnumGenerator\EnumGenerator;
+use Laminas\Code\Generator\FileGenerator;
+use Soap\Engine\Metadata\Model\XsdType;
+use function Psl\Dict\pull;
+use function Psl\Type\int;
+
+/**
+ * @template-implements GeneratorInterface<Type>
+ */
+class EnumerationGenerator implements GeneratorInterface
+{
+    /**
+     * @param FileGenerator $file
+     * @param Type $context
+     * @return string
+     */
+    public function generate(FileGenerator $file, $context): string
+    {
+        $file->setNamespace($context->getNamespace());
+        $file->setBody($this->generateBody($context));
+
+        return $file->generate();
+    }
+
+    private function generateBody(Type $type): string
+    {
+        $xsdType = $type->getXsdType();
+        $xsdMeta = $xsdType->getMeta();
+        $enumType = match ($xsdType->getBaseType()) {
+            'int', 'integer' => 'int',
+            default => 'string',
+        };
+
+        $body = EnumGenerator::withConfig([
+            'name' => Normalizer::normalizeClassname($type->getName()),
+            'backedCases' => [
+                'type' => $enumType,
+                'cases' => $this->buildCases($xsdType, $enumType),
+            ]
+        ])->generate();
+
+        if ($docs = $xsdMeta->docs()->unwrapOr('')) {
+            $docblock = (new DocBlockGenerator())
+                ->setWordWrap(false)
+                ->setLongDescription($docs)
+                ->generate();
+            $body = $docblock . $body;
+        }
+
+        return $body;
+    }
+
+    /**
+     * @param 'string'|'int' $enumType
+     * @return array<string, int|string>
+     */
+    private function buildCases(XsdType $xsdType, string $enumType): array
+    {
+        $enums = $xsdType->getMeta()->enums()->unwrapOr([]);
+
+        return pull(
+            $enums,
+            static fn(string $value): int|string => match ($enumType) {
+                'int' => int()->coerce($value),
+                'string' => $value,
+            },
+            static fn(string $value): string => Normalizer::normalizeEnumCaseName($value)
+        );
+    }
+}
diff --git a/src/Phpro/SoapClient/CodeGenerator/GeneratorInterface.php b/src/Phpro/SoapClient/CodeGenerator/GeneratorInterface.php
@@ -8,6 +8,8 @@
  * Interface GeneratorInterface
  *
  * @package Phpro\SoapClient\CodeGenerator
+ *
+ * @template Context
  */
 interface GeneratorInterface
 {
@@ -16,9 +18,9 @@ interface GeneratorInterface
 
     /**
      * @param FileGenerator $file
-     * @param mixed         $model
+     * @param Context       $context
      *
      * @return string
      */
-    public function generate(FileGenerator $file, $model): string;
+    public function generate(FileGenerator $file, $context): string;
 }
diff --git a/src/Phpro/SoapClient/CodeGenerator/TypeEnhancer/Calculator/TypeNameCalculator.php b/src/Phpro/SoapClient/CodeGenerator/TypeEnhancer/Calculator/TypeNameCalculator.php
@@ -13,9 +13,10 @@ public function __invoke(XsdType $type): string
     {
         $meta = $type->getMeta();
         $isSimpleType = $meta->isSimple()->unwrapOr(false);
+        $isGlobalEnum = $isSimpleType && $meta->enums()->isSome() && !$meta->isLocal()->unwrapOr(false);
 
-        // For non-simple types, we always want to use the name of the type.
-        if (!$isSimpleType) {
+        // For non-simple types or backed enums, we always want to use the name of the type.
+        if (!$isSimpleType || $isGlobalEnum) {
             return $type->getName();
         }
 

diff --git a/src/Phpro/SoapClient/CodeGenerator/TypeEnhancer/MetaTypeEnhancer.php b/src/Phpro/SoapClient/CodeGenerator/TypeEnhancer/MetaTypeEnhancer.php
@@ -22,9 +22,13 @@ public function __construct(
      */
     public function asDocBlockType(string $type): string
     {
+        $isLocal = $this->meta->isLocal()->unwrapOr(false);
+        $isEnum = (bool) $this->meta->enums()->unwrapOr([]);
+        $isUnion = (bool) $this->meta->unions()->unwrapOr([]);
+
         $type = match (true) {
-            (bool) $this->meta->enums()->unwrapOr([]) => (new EnumValuesCalculator())($this->meta),
-            (bool) $this->meta->unions()->unwrapOr([]) => (new UnionTypesCalculator())($this->meta),
+            $isLocal && $isEnum => (new EnumValuesCalculator())($this->meta),
+            $isUnion => (new UnionTypesCalculator())($this->meta),
             default => $type
         };
 

diff --git a/src/Phpro/SoapClient/CodeGenerator/TypeGenerator.php b/src/Phpro/SoapClient/CodeGenerator/TypeGenerator.php
@@ -12,9 +12,7 @@
 use Laminas\Code\Generator\FileGenerator;
 
 /**
- * Class TypeGenerator
- *
- * @package Phpro\SoapClient\CodeGenerator
+ * @template-implements GeneratorInterface<Type>
  */
 class TypeGenerator implements GeneratorInterface
 {

diff --git a/src/Phpro/SoapClient/CodeGenerator/Util/Normalizer.php b/src/Phpro/SoapClient/CodeGenerator/Util/Normalizer.php
@@ -209,6 +209,32 @@ public static function normalizeProperty(string $property): string
         return self::camelCase($property, '{[^a-z0-9_]+}i');
     }
 
+    /**
+     * @param non-empty-string $emptyCase
+     * @param non-empty-string $conflictPrefix
+     * @return non-empty-string
+     */
+    public static function normalizeEnumCaseName(
+        string $value,
+        string $emptyCase = 'Empty',
+        string $conflictPrefix = 'Value_'
+    ): string {
+        if ($value === '') {
+            return $emptyCase;
+        }
+
+        if (is_numeric($value)) {
+            return $conflictPrefix.$value;
+        }
+
+        $normalized = self::normalizeProperty($value);
+        if (preg_match('/^[0-9]/', $normalized)) {
+            $normalized = $conflictPrefix.$normalized;
+        }
+
+        return $normalized;
+    }
+
     /**
      * @param non-empty-string $type
      *