Merge pull request #206 from tabuna/patch-1

Added phpdoc for facade Breadcrumbs
d13r · Oct 20, 2019 · b7a24a5 · b7a24a5
2 parents 0108438 + 033a80b
commit b7a24a5
Show file tree

Hide file tree

Showing 3 changed files with 133 additions and 1 deletion.
diff --git a/src/BreadcrumbsManager.php b/src/BreadcrumbsManager.php
@@ -242,7 +242,7 @@ public function render(string $name = null, ...$params): HtmlString
      * @throws \DaveJamesMiller\Breadcrumbs\Exceptions\UnnamedRouteException if the current route doesn't have an associated name.
      * @throws \DaveJamesMiller\Breadcrumbs\Exceptions\InvalidBreadcrumbException if the name is (or any ancestor names are) not registered.
      */
-    public function current()
+    public function current(): ?\stdClass
     {
         return $this->generate()->where('current', '!==', false)->last();
     }

diff --git a/src/Facades/Breadcrumbs.php b/src/Facades/Breadcrumbs.php
@@ -8,6 +8,22 @@
 /**
  * Breadcrumbs facade - allows easy access to the Manager instance.
  *
+ * @method static void for(string $name, callable $callback)
+ * @method static void register(string $name, callable $callback)
+ * @method static void before(callable $callback)
+ * @method static void after(callable $callback)
+ * @method static bool exists(string $name = null)
+ * @method static \Illuminate\Support\Collection generate(string $name = null, $params)
+ * @method static \Illuminate\Support\HtmlString view(string $view, string $name = null, $params)
+ * @method static \Illuminate\Support\HtmlString render(string $name = null, $params)
+ * @method static \stdClass|null current()
+ * @method static array getCurrentRoute()
+ * @method static void setCurrentRoute(string $name, $params)
+ * @method static void clearCurrentRoute()
+ * @method static macro($name, $macro)
+ * @method static mixin($mixin, $replace = 1)
+ * @method static hasMacro($name)
+ *
  * @see BreadcrumbsManager
  */
 class Breadcrumbs extends Facade

diff --git a/tests/FacadePhpDocTest.php b/tests/FacadePhpDocTest.php
@@ -2,8 +2,36 @@
 
 namespace BreadcrumbsTests;
 
+use DaveJamesMiller\Breadcrumbs\BreadcrumbsManager;
+use DaveJamesMiller\Breadcrumbs\Facades\Breadcrumbs;
+use Illuminate\Support\Str;
+use ReflectionClass;
+use ReflectionMethod;
+use ReflectionParameter;
+
 class FacadePhpDocTest extends TestCase
 {
+    /**
+     * Methods that are not needed in phpDoc
+     */
+    private const EXCLUSION_METHODS = [
+        '__construct',
+        '__destruct',
+        '__call',
+        '__callStatic',
+        '__get',
+        '__set',
+        '__isset',
+        '__unset',
+        '__sleep',
+        '__wakeup',
+        '__toString',
+        '__invoke',
+        '__set_state',
+        '__clone',
+        '__debugInfo',
+    ];
+
     public function tags()
     {
         $code = file_get_contents(__DIR__ . '/../src/BreadcrumbsManager.php');
@@ -40,4 +68,92 @@ public function testFullyQualifiedClassNames($class, $line)
             "Must use fully qualified class names in BreadcrumbsManger PhpDoc: $line"
         );
     }
+
+    public function testBreadcrumbsFacade()
+    {
+        $this->checkMethodDocBlock(Breadcrumbs::class, BreadcrumbsManager::class);
+    }
+
+    /**
+     * Checks the correctness of building the doc block according to the main class
+     *
+     * @param string $facade
+     * @param string $class
+     *
+     * @throws \ReflectionException
+     */
+    private function checkMethodDocBlock(string $facade, string $class)
+    {
+        $class = new ReflectionClass($class);
+        $methods = $class->getMethods(ReflectionMethod::IS_PUBLIC);
+        $facadeDocs = (new ReflectionClass($facade))->getDocComment();
+
+        collect($methods)
+            ->map(function (ReflectionMethod $method) {
+                return in_array($method->name, self::EXCLUSION_METHODS, true) ? null : $method;
+            })
+            ->filter()
+            ->map(function (ReflectionMethod $method) {
+
+                $parameters = $this->buildParametsDocBlock($method->getParameters());
+                $returns = $this->buildReturnTypeDocBlock($method->getReturnType());
+
+                $docMethod = sprintf('@method static %s %s%s',
+                    $returns,
+                    $method->getName(),
+                    $parameters
+                );
+
+                return preg_replace('/\s+/', ' ', $docMethod);
+            })
+            ->each(function (string $method) use ($facadeDocs) {
+                $this->assertStringContainsString($method, $facadeDocs, 'Not found: ' . $method);
+            });
+    }
+
+    /**
+     * @param ReflectionParameter[] $parameters
+     *
+     * @return string
+     */
+    private function buildParametsDocBlock($parameters = [])
+    {
+        $parameters = array_map(function (ReflectionParameter $parameter) {
+            $name = optional($parameter->getType())->getName();
+
+            $strParam = sprintf('%s $%s', $name, $parameter->getName());
+            $strParam = trim($strParam);
+
+            if (!$parameter->isDefaultValueAvailable()) {
+                return $strParam;
+            }
+
+            $defaultValue = $parameter->getDefaultValue() ?? 'null';
+            return sprintf('%s = %s', $strParam, $defaultValue);
+        }, $parameters);
+
+        return sprintf('(%s)', implode(', ', $parameters));
+    }
+
+    /**
+     * @param \ReflectionType|null $reflectionType
+     *
+     * @return string
+     */
+    private function buildReturnTypeDocBlock(\ReflectionType $reflectionType = null)
+    {
+        $reflectionType = optional($reflectionType);
+
+        $strReturn = $reflectionType->getName();
+
+        if (class_exists($strReturn)) {
+            $strReturn = Str::start($strReturn, '\\');
+        }
+
+        if ($reflectionType->allowsNull()) {
+            $strReturn = sprintf('%s|%s', $strReturn, 'null');
+        }
+
+        return $strReturn;
+    }
 }