Issue #3387642: Clarify identifiers in ServerEndpointController

src/Controller/ServerEndpointController.php

@@ -18,9 +18,7 @@ use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
 
 /**
- * Provides an endpoint for Storybook to query.
- *
- * @see https://github.com/storybookjs/storybook/tree/next/app/server
+ * Provides an endpoint for component libraries to query.
  */
 class ServerEndpointController extends ControllerBase {
 
@@ -96,7 +94,7 @@ class ServerEndpointController extends ControllerBase {
   }
 
   /**
-   * Render a Twig template from a Storybook component directory.
+   * Render a Twig template from a component directory.
    */
   public function render(Request $request): array {
     try {
@@ -161,13 +159,17 @@ class ServerEndpointController extends ControllerBase {
    *   If the component cannot be found.
    */
   public function getComponent(Request $request): Component {
+    $component_filename = $request->query->get('_componentFileName');
     $story_filename = $request->query->get('_storyFileName');
-    if (!$story_filename) {
-      throw new ComponentNotFoundException('Impossible to find a story with an empty story file name.');
+    if (!$component_filename && !$story_filename) {
+      throw new ComponentNotFoundException('Impossible to find a component with an empty component file name.');
+    } else if (!$component_filename) {
+      @trigger_error('The _storyFileName parameter is deprecated in cl_server:2.0.0 and will be removed in cl_server:3.0.0. Please use _componentFileName instead.', E_USER_DEPRECATED);
+      $component_filename = $story_filename;
     }
-    $basename = basename($story_filename);
+    $basename = basename($component_filename);
     [$machine_name] = explode('.', $basename);
-    $provider = $this->findExtensionName($this->findStoryFile($story_filename));
+    $provider = $this->findDrupalExtensionName($this->findComponentFile($component_filename));
     return $this->pluginManager->createInstance("$provider:$machine_name");
   }
 
@@ -220,6 +222,9 @@ class ServerEndpointController extends ControllerBase {
    *   The template context.
    * @param \Drupal\sdc\Component\ComponentMetadata $metadata
    *   The component metadata.
+   *
+   * @return boolean
+   *   Whether attributes property needs to be upcasted.
    */
   private function attributesPropNeedsUpcasting(array $context, ComponentMetadata $metadata) {
     $properties = $metadata->schema['properties'] ?? [];
@@ -229,19 +234,19 @@ class ServerEndpointController extends ControllerBase {
   }
 
   /**
-   * Finds the plugin ID from the story file name.
+   * Finds the component file relative to Drupal docroot.
    *
-   * The story file should be in the component directory, but storybook will
-   * not process is from the Drupal docroot. This means we don't know what the
-   * path is relative to.
+   * The component file should be in the component directory, but the component
+   * library may be processing it from outside the Drupal docroot. This means
+   * we don't know what the path is relative to.
    *
    * @param string $filename
    *   The filename.
    *
-   * @return string
-   *   The plugin ID.
+   * @return string|null
+   *   The path to the component file relative the Drupal docroot.
    */
-  private function findStoryFile(string $filename): ?string {
+  private function findComponentFile(string $filename): ?string {
     if (empty($filename)) {
       return NULL;
     }
@@ -251,13 +256,25 @@ class ServerEndpointController extends ControllerBase {
     $parts = explode(DIRECTORY_SEPARATOR, $filename);
     array_shift($parts);
     $filename = implode(DIRECTORY_SEPARATOR, $parts);
-    return $this->findStoryFile($filename);
+    return $this->findComponentFile($filename);
   }
 
   /**
+   * Finds the module or theme to which a component belongs using the component
+   * path.
+   *
+   * This method works by traversing the component’s directory tree and finding
+   * the first directory with a `$EXT.info.yml` file where `$EXT` matches the
+   * directory’s name.
+   *
+   * @param string $path
+   *   The path to the component file.
    *
+   * @return string|null
+   *   The machine name of the module or theme to which the component belongs,
+   *   or null if none is found.
    */
-  private function findExtensionName(string $path): ?string {
+  private function findDrupalExtensionName(string $path): ?string {
     if (empty($path)) {
       return NULL;
     }
@@ -267,7 +284,7 @@ class ServerEndpointController extends ControllerBase {
     if (file_exists($info_file)) {
       return $dir;
     }
-    return $this->findExtensionName($path);
+    return $this->findDrupalExtensionName($path);
   }
 
 }