Refactor Util helper into non-static SourceFinder

Author: DerManoMann

bin/openapi

@@ -6,7 +6,7 @@ use OpenApi\Analysers\DocBlockAnnotationFactory;
 use OpenApi\Analysers\ReflectionAnalyser;
 use OpenApi\Annotations\OpenApi;
 use OpenApi\Generator;
-use OpenApi\Util;
+use OpenApi\SourceFinder;
 use OpenApi\Loggers\ConsoleLogger;
 
 if (class_exists(Generator::class) === false) {
@@ -224,7 +224,7 @@ $openapi = $generator
     ->setVersion($options['version'])
     ->setConfig($options['config'])
     ->setAnalyser($analyser)
-    ->generate(Util::finder($paths, $exclude, $pattern));
+    ->generate(new SourceFinder($paths, $exclude, $pattern));
 
 if ($options['output'] === false) {
     if (strtolower($options['format']) === 'json') {

docs/reference/generator.md

@@ -51,14 +51,12 @@ require('"vendor/autoload.php');
 $openapi = (new \OpenApi\Generator())->generate(['/path1/to/project']);
 ```
 
-The `generate()` method does not support the CLI `exclude` and `pattern` options directly. Instead, a Symfony `Finder` instance can be passed in
-as source directly.
-
-If needed, the `\OpenApi\Util` class provides a builder method that undertands these options.
+The `generate()` method does not support the CLI `exclude` and `pattern` options directly.
+Instead, a custom Symfony `Finder` class (`SourceFinder`) can be used that understands these options.
 
 ```php
 $exclude = ['tests'];
 $pattern = '*.php';
 
-$openapi = (new \OpenApi\Generator())->generate(\OpenApi\Util::finder(__DIR__, $exclude, $pattern));
+$openapi = (new \OpenApi\Generator())->generate(new \OpenApi\SourceFinder(__DIR__, $exclude, $pattern));
 ```

src/Annotations/AbstractAnnotation.php

@@ -10,7 +10,6 @@
 use OpenApi\Generator;
 use OpenApi\Annotations as OA;
 use OpenApi\OpenApiException;
-use OpenApi\Util;
 use Symfony\Component\Yaml\Yaml;
 
 /**
@@ -454,14 +453,14 @@ public function validate(array $stack = [], array $skip = [], string $ref = '',
             if ($details = $this->matchNested($annotation)) {
                 $property = $details->value;
                 if (is_array($property)) {
-                    $this->_context->logger->warning('Only one ' . Util::shorten(get_class($annotation)) . '() allowed for ' . $this->identity() . ' multiple found, skipped: ' . $annotation->_context);
+                    $this->_context->logger->warning('Only one ' . static::shorten(get_class($annotation)) . '() allowed for ' . $this->identity() . ' multiple found, skipped: ' . $annotation->_context);
                 } else {
-                    $this->_context->logger->warning('Only one ' . Util::shorten(get_class($annotation)) . '() allowed for ' . $this->identity() . " multiple found in:\n    Using: " . $this->{$property}->_context . "\n  Skipped: " . $annotation->_context);
+                    $this->_context->logger->warning('Only one ' . static::shorten(get_class($annotation)) . '() allowed for ' . $this->identity() . " multiple found in:\n    Using: " . $this->{$property}->_context . "\n  Skipped: " . $annotation->_context);
                 }
             } elseif ($annotation instanceof AbstractAnnotation) {
                 $message = 'Unexpected ' . $annotation->identity();
                 if ($class::$_parents) {
-                    $message .= ', expected to be inside ' . implode(', ', Util::shorten($class::$_parents));
+                    $message .= ', expected to be inside ' . implode(', ', static::shorten($class::$_parents));
                 }
                 $this->_context->logger->warning($message . ' in ' . $annotation->_context);
             }
@@ -481,7 +480,7 @@ public function validate(array $stack = [], array $skip = [], string $ref = '',
             $keyField = $nested[1];
             foreach ($this->{$property} as $key => $item) {
                 if (is_array($item) && is_numeric($key) === false) {
-                    $this->_context->logger->warning($this->identity() . '->' . $property . ' is an object literal, use nested ' . Util::shorten($annotationClass) . '() annotation(s) in ' . $this->_context);
+                    $this->_context->logger->warning($this->identity() . '->' . $property . ' is an object literal, use nested ' . static::shorten($annotationClass) . '() annotation(s) in ' . $this->_context);
                     $keys[$key] = $item;
                 } elseif (Generator::isDefault($item->{$keyField})) {
                     $this->_context->logger->error($item->identity() . ' is missing key-field: "' . $keyField . '" in ' . $item->_context);
@@ -511,11 +510,11 @@ public function validate(array $stack = [], array $skip = [], string $ref = '',
                         $nestedProperty = is_array($nested) ? $nested[0] : $nested;
                         if ($property === $nestedProperty) {
                             if ($this instanceof OpenApi) {
-                                $message = 'Required ' . Util::shorten($class) . '() not found';
+                                $message = 'Required ' . static::shorten($class) . '() not found';
                             } elseif (is_array($nested)) {
-                                $message = $this->identity() . ' requires at least one ' . Util::shorten($class) . '() in ' . $this->_context;
+                                $message = $this->identity() . ' requires at least one ' . static::shorten($class) . '() in ' . $this->_context;
                             } else {
-                                $message = $this->identity() . ' requires a ' . Util::shorten($class) . '() in ' . $this->_context;
+                                $message = $this->identity() . ' requires a ' . static::shorten($class) . '() in ' . $this->_context;
                             }
                             break;
                         }
@@ -675,7 +674,7 @@ protected function _identity(array $properties): string
             }
         }
 
-        return Util::shorten(get_class($this)) . '(' . implode(',', $fields) . ')';
+        return static::shorten(get_class($this)) . '(' . implode(',', $fields) . ')';
     }
 
     /**
@@ -794,4 +793,24 @@ protected function combine(...$args): array
 
         return array_filter($combined, fn ($value): bool => !Generator::isDefault($value) && $value !== null);
     }
+
+    /**
+     * Shorten class name(s).
+     *
+     * @param array|object|string $classes Class(es) to shorten
+     *
+     * @return string|string[] One or more shortened class names
+     */
+    protected static function shorten($classes)
+    {
+        $short = [];
+        foreach ((array) $classes as $class) {
+            $short[] = '@' . str_replace([
+                    'OpenApi\\Annotations\\',
+                    'OpenApi\\Attributes\\',
+                ], 'OA\\', $class);
+        }
+
+        return is_array($classes) ? $short : array_pop($short);
+    }
 }

src/Annotations/Components.php

@@ -7,7 +7,6 @@
 namespace OpenApi\Annotations;
 
 use OpenApi\Generator;
-use OpenApi\Util;
 
 /**
  * Holds a set of reusable objects for different aspects of the OA.
@@ -151,6 +150,28 @@ public static function ref($component, bool $encode = true): string
             $name = $component;
         }
 
-        return self::COMPONENTS_PREFIX . $type . '/' . ($encode ? Util::refEncode((string) $name) : $name);
+        return self::COMPONENTS_PREFIX . $type . '/' . ($encode ? static::refEncode((string) $name) : $name);
+    }
+
+    /**
+     * Escapes the special characters "/" and "~".
+     *
+     * https://swagger.io/docs/specification/using-ref/
+     * https://tools.ietf.org/html/rfc6901#page-3
+     */
+    public static function refEncode(string $raw): string
+    {
+        return str_replace('/', '~1', str_replace('~', '~0', $raw));
+    }
+
+    /**
+     * Converted the escaped characters "~1" and "~" back to "/" and "~".
+     *
+     * https://swagger.io/docs/specification/using-ref/
+     * https://tools.ietf.org/html/rfc6901#page-3
+     */
+    public static function refDecode(string $encoded): string
+    {
+        return str_replace('~1', '/', str_replace('~0', '~', $encoded));
     }
 }

src/Annotations/OpenApi.php

@@ -9,7 +9,6 @@
 use OpenApi\Analysis;
 use OpenApi\Generator;
 use OpenApi\OpenApiException;
-use OpenApi\Util;
 
 /**
  * This is the root document object for the API specification.
@@ -215,7 +214,7 @@ private static function resolveRef(string $ref, string $resolved, $container, ar
         $slash = strpos($path, '/');
 
         $subpath = $slash === false ? $path : substr($path, 0, $slash);
-        $property = Util::refDecode($subpath);
+        $property = Components::refDecode($subpath);
         $unresolved = $slash === false ? $resolved . $subpath : $resolved . $subpath . '/';
 
         if (is_object($container)) {

src/Generator.php

@@ -362,7 +362,7 @@ protected function scanSources(iterable $sources, Analysis $analysis, Context $r
                     continue;
                 }
                 if (is_dir($resolvedSource)) {
-                    $this->scanSources(Util::finder($resolvedSource), $analysis, $rootContext);
+                    $this->scanSources(new SourceFinder($resolvedSource), $analysis, $rootContext);
                 } else {
                     $rootContext->logger->debug(sprintf('Analysing source: %s', $resolvedSource));
                     $analysis->addAnalysis($analyser->fromFile($resolvedSource, $rootContext));

src/SourceFinder.php

@@ -0,0 +1,63 @@
+<?php declare(strict_types=1);
+
+namespace OpenApi;
+
+use Symfony\Component\Finder\Finder;
+
+/**
+ * Custom Symfony `Finder` that understands `swagger-php` CLI options.
+ */
+class SourceFinder extends Finder
+{
+    public function __construct(string|array $directory, null|array|string $exclude = null, string $pattern = '*.php')
+    {
+        parent::__construct();
+
+        $this
+            ->sortByName()
+            ->files()
+            ->followLinks()
+            ->name($pattern);
+
+        $directories = (array) $directory;
+
+        foreach ($directories as $path) {
+            if (is_file($path)) {
+                $this->append([$path]);
+            } else {
+                $this->in($path);
+            }
+        }
+
+        foreach ((array) $exclude as $path) {
+            $this->notPath($this->getRelativePath($path, $directories));
+        }
+    }
+
+    /**
+     * Turns the given $fullPath into a relative path based on $basePaths, which can either
+     * be a single string path, or a list of possible paths. If a list is given, the first
+     * matching basePath in the list will be used to compute the relative path. If no
+     * relative path could be computed, the original string will be returned because there
+     * is always a chance it was a valid relative path to begin with.
+     *
+     * It should be noted that these are "relative paths" primarily in Finder's sense of them,
+     * and conform specifically to what is expected by functions like <code>exclude()</code> and <code>notPath()</code>.
+     *
+     * In particular, leading and trailing slashes are removed.
+     */
+    private function getRelativePath(string $fullPath, array $directories): string
+    {
+        foreach ($directories as $directory) {
+            if (str_starts_with($directory, $fullPath)) {
+                $relativePath = substr($directory, strlen($fullPath));
+
+                if ($relativePath !== '' && $relativePath !== '0') {
+                    return trim($relativePath, '/');
+                }
+            }
+        }
+
+        return $fullPath;
+    }
+}