Issue #3048134 by Pancho: Properly document $context arrays in...

Issue #3048134 by Pancho: Properly document $context arrays in FillPdfLinkManipulatorInterface::parseLink()

src/Controller/HandlePdfController.php

@@ -277,8 +277,8 @@ class HandlePdfController extends ControllerBase {
    * @param string $pdf_data
    *   A string containing the content of the merged PDF.
    * @param array $context
-   *   The FillPDF request context as returned by
-   *   \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink().
+   *   The request context as returned by
+   *   FillPdfLinkManipulatorInterface::parseLink().
    * @param string $filename
    *   Filename of the merged PDF.
    * @param \Drupal\Core\Entity\EntityInterface[] $entities
@@ -287,6 +287,8 @@ class HandlePdfController extends ControllerBase {
    *
    * @return \Symfony\Component\HttpFoundation\Response
    *   The action plugin's response object.
+   *
+   * @see \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink()
    */
   protected function handlePopulatedPdf(FillPdfFormInterface $fillpdf_form, $pdf_data, array $context, $filename, array $entities) {
     $force_download = FALSE;

src/FillPdfBackendPluginInterface.php

@@ -36,27 +36,29 @@ interface FillPdfBackendPluginInterface {
    * @param array $field_mapping
    *   An array of fields mapping PDF field keys to the values with which they
    *   should be replaced. Example array:
-   *
-   * @code
-   *   array(
-   *     'values' => array(
+   *   @code
+   *   [
+   *     'values' => [
    *       'Field 1' => 'value',
    *       'Checkbox Field' => 'On',
-   *     ),
-   *     'images' => array(
-   *       'Image Field 1' => array(
+   *     ],
+   *     'images' => [
+   *       'Image Field 1' => [
    *         'data' => base64_encode($file_data),
    *         'filenamehash' => md5($image_path_info['filename']) . '.' . $image_path_info['extension'],
-   *       ),
-   *     ),
-   *   )
-   * @endcode
+   *       ],
+   *     ],
+   *   ]
+   *   @endcode
    * @param array $context
-   *   TODO: Define.
+   *   The request context as returned by
+   *   FillPdfLinkManipulatorInterface::parseLink().
    *
    * @return string|null
    *   The raw file contents of the new PDF, or NULL if populating failed. The
    *   caller has to handle saving or serving the file accordingly.
+   *
+   * @see \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink()
    */
   public function populateWithFieldData(FillPdfFormInterface $fillpdf_form, array $field_mapping, array $context);
 

src/FillPdfContextManagerInterface.php

@@ -17,11 +17,13 @@ interface FillPdfContextManagerInterface {
    *
    * @param array $context
    *   The FillPDF request context as returned by
-   *   \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink().
+   *   FillPdfLinkManipulatorInterface::parseLink().
    *
    * @return \Drupal\Core\Entity\EntityInterface[]
    *   An array of entity objects indexed by their IDs. Returns an empty array
    *   if no matching entities are found.
+   *
+   * @see \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink()
    */
   public function loadEntities(array $context);
 

src/FillPdfLinkManipulatorInterface.php

@@ -15,38 +15,65 @@ use Symfony\Component\HttpFoundation\Request;
 interface FillPdfLinkManipulatorInterface {
 
   /**
-   * @todo: Move this elsewhere, maybe to that current_fillpdf_link service I was thinking of or whatever it was.
+   * Parses a request.
+   *
+   * @param \Symfony\Component\HttpFoundation\Request $request
+   *   The request containing the query string to parse.
    *
-   * @param \Symfony\Component\HttpFoundation\Request $request The request
-   *  containing the query string to parse.
    * @return array
+   *   The FillPDF request context as returned by parseLink().
+   *
+   * @see \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink()
+   *
+   * @todo: Move this elsewhere, maybe to that current_fillpdf_link service I was thinking of or whatever it was.
    */
   public function parseRequest(Request $request);
 
   /**
-   * @param \Drupal\Core\Url $link
-   *   The valid URL containing the FillPDF generation metadata.
-   *   e.g. http://example.com/fillpdf?entities[]=node:1&entities[]=contact:7
-   * @todo: Document array. For now, see what FillPdfLinkManipulator::parseLink() does.
-   * @see FillPdfLinkManipulator::parseLink()
+   * Parses a root-relative URL.
+   *
+   * @param string $url
+   *   The root-relative FillPDF URL that would be used to generate the PDF.
+   *   e.g. '/fillpdf?fid=1&entity_type=node&entity_id=1'.
+   *
    * @return array
+   *   The FillPDF request context as returned by parseLink().
+   *
+   * @see \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink()
    */
-  public function parseLink(Url $link);
+  public function parseUrlString($url);
 
   /**
-   * @param string $url
-   * The root-relative FillPDF URL that would be used to generate the PDF.
-   * e.g. /fillpdf?fid=1&entity_type=node&entity_id=1
+   * Parses a Url object.
+   *
+   * @param \Drupal\Core\Url $link
+   *   The valid URL containing the FillPDF generation metadata.
+   *   e.g. 'http://example.com/fillpdf?entities[]=node:1&entities[]=contact:7'.
    *
    * @return array
+   *   An associative array representing the request context and containing the
+   *   following properties:
+   *     fid: int ID of the FillPDF form.
+   *     sample: true|null Flag indicating if a sample file is to be generated.
+   *       TRUE if yes, otherwise NULL.
+   *     entity_ids: string[] Array of entity_type:entity_id pairs to populate
+   *       the fields with. Will otherwise contain an empty array.
+   *     force_download: true|null Flag indicating if the populated file should
+   *       always be downloaded. TRUE if yes, otherwise NULL.
+   *     flatten: false|null Flag indicating if the populated file should
+   *       be flattened. FALSE if not, otherwise NULL.
    */
-  public function parseUrlString($url);
+  public function parseLink(Url $link);
 
   /**
+   * Generates a FillPdf Url from the given parameters.
+   *
    * @param array $parameters
    *   The array of parameters to be converted into a
    *   URL and query string.
+   *
    * @return \Drupal\Core\Url
+   *   Url object.
    */
   public function generateLink(array $parameters);
 

src/OutputHandler.php

@@ -57,14 +57,14 @@ class OutputHandler implements OutputHandlerInterface {
   /**
    * {@inheritdoc}
    */
-  public function savePdfToFile(array $context, $destination_path_override = NULL) {
+  public function savePdfToFile(array $configuration, $destination_path_override = NULL) {
     /** @var \Drupal\fillpdf\Entity\FillPdfForm $fillpdf_form */
-    $fillpdf_form = $context['form'];
+    $fillpdf_form = $configuration['form'];
 
     // @todo: Rename 'token_objects' to 'entities' in FillPDF 5.x. Webform
     // submissions are now entities, too.
     /** @var \Drupal\Core\Entity\EntityInterface[] $entities */
-    $entities = $context['token_objects'];
+    $entities = $configuration['token_objects'];
 
     $destination_path = 'fillpdf';
     if (!empty($destination_path_override)) {
@@ -89,8 +89,8 @@ class OutputHandler implements OutputHandlerInterface {
     }
     else {
       // Full steam ahead!
-      $saved_file = file_save_data($context['data'], "{$resolved_destination_path}/{$context['filename']}", FILE_EXISTS_RENAME);
-      $this->rememberFileContext($saved_file, $context['context']);
+      $saved_file = file_save_data($configuration['data'], "{$resolved_destination_path}/{$configuration['filename']}", FILE_EXISTS_RENAME);
+      $this->rememberFileContext($saved_file, $configuration['context']);
     }
 
     return $saved_file;
@@ -115,13 +115,16 @@ class OutputHandler implements OutputHandlerInterface {
   }
 
   /**
+   * Saves the file context.
+   *
    * @param \Drupal\file\FileInterface $fillpdf_file
+   *   File object containing the generated PDF file.
    * @param array $context
-   *   An array representing the entities that were used to generate this file.
+   *   An associative array representing the context of the generated file.
    *   This array should match the format returned by
    *   FillPdfLinkManipulator::parseLink().
    *
-   * @see FillPdfLinkManipulatorInterface::parseLink()
+   * @see \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink()
    * @see FileFieldItemList::postSave()
    */
   protected function rememberFileContext(FileInterface $fillpdf_file, array $context) {

src/OutputHandlerInterface.php

@@ -12,24 +12,30 @@ interface OutputHandlerInterface {
   /**
    * Saves merged PDF data to the filesystem.
    *
-   * @param array $context
-   *   An array containing the following properties:
+   * @param array $configuration
+   *   An array of configuration as originally passed from
+   *   HandlePdfController::handlePopulatedPdf() to the FillPdfActionPlugin,
+   *   containing the following properties:
    *     form: The FillPdfForm object from which the PDF was generated.
    *     context: The FillPDF request context as returned by
-   *       \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink().
+   *       FillPdfLinkManipulatorInterface::parseLink().
    *     token_objects: The token data from which the PDF was generated.
    *     data: The populated PDF data itself.
    *     filename: The filename (not including path) with which
    *       the PDF should be presented.
    * @param string $destination_path_override
+   *   (optional) A destination path to override the one given by the
+   *   FillPdfForm.
    *
    * @return \Drupal\file\FileInterface|false
    *   The file entity, or FALSE on error.
    *
    * @see \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink()
+   * @see \Drupal\fillpdf\Plugin\FillPdfActionPlugin\FillPdfSaveAction::savePdf()
+   *
    * @todo: Rename 'token_objects' to 'entities' in FillPDF 5.x. Webform
    *   submissions are now entities, too.
    */
-  public function savePdfToFile(array $context, $destination_path_override = NULL);
+  public function savePdfToFile(array $configuration, $destination_path_override = NULL);
 
 }

src/Plugin/BackendService/LocalService.php

@@ -110,8 +110,8 @@ class LocalService extends BackendServiceBase implements ContainerFactoryPluginI
   /**
    * {@inheritdoc}
    */
-  public function merge($pdf_content, array $field_mappings, array $options) {
-    $flatten = $options['flatten'];
+  public function merge($pdf_content, array $field_mappings, array $context) {
+    $flatten = $context['flatten'];
 
     $api_fields = [];
     foreach ($field_mappings as $key => $mapping) {

src/Plugin/BackendServiceInterface.php

@@ -40,18 +40,17 @@ interface BackendServiceInterface extends PluginInspectionInterface {
    *   An array of FieldMapping-derived objects mapping PDF field keys to the
    *   values with which they should be replaced. Strings are also acceptable
    *   and converted to TextFieldMapping objects.
-   *
    *   Example array:
-   *
-   * @code
-   * [
-   *   'Foo' => new TextFieldMapping('bar'),
-   *   'Foo2' => new TextFieldMapping('bar2'),
-   *   'Image1' => new ImageFieldMapping(base64_encode(file_get_contents($image)), 'jpg'),
-   * ]
-   * @endcode
-   * @param array $options
-   *   Additional options, usually relating to plugin-specific functionality.
+   *   @code
+   *   [
+   *     'Foo' => new TextFieldMapping('bar'),
+   *     'Foo2' => new TextFieldMapping('bar2'),
+   *     'Image1' => new ImageFieldMapping(base64_encode(file_get_contents($image)), 'jpg'),
+   *   ]
+   *   @endcode
+   * @param array $context
+   *   The request context as returned by
+   *   FillPdfLinkManipulatorInterface::parseLink().
    *
    * @return string|null
    *   The raw file contents of the new PDF, or NULL if merging failed. The
@@ -60,7 +59,8 @@ interface BackendServiceInterface extends PluginInspectionInterface {
    * @see \Drupal\fillpdf\FieldMapping
    * @see \Drupal\fillpdf\FieldMapping\TextFieldMapping
    * @see \Drupal\fillpdf\FieldMapping\ImageFieldMapping
+   * @see \Drupal\fillpdf\FillPdfLinkManipulatorInterface::parseLink()
    */
-  public function merge($pdf_content, array $field_mappings, array $options);
+  public function merge($pdf_content, array $field_mappings, array $context);
 
 }

src/Service/FillPdfLinkManipulator.php

@@ -9,13 +9,12 @@ use Drupal\fillpdf\FillPdfLinkManipulatorInterface;
 use Symfony\Component\HttpFoundation\Request;
 
 /**
- * {@inheritDoc}
+ * {@inheritdoc}
  */
 class FillPdfLinkManipulator implements FillPdfLinkManipulatorInterface {
 
   /**
-   * @param Request $request The request containing the query string to parse.
-   * @return array
+   * {@inheritdoc}
    *
    * @todo: Maybe this should return a FillPdfLinkContext object or something?
    *   Guess it depends on how much I end up needing to change it.
@@ -29,11 +28,15 @@ class FillPdfLinkManipulator implements FillPdfLinkManipulatorInterface {
   }
 
   /**
-   * @param $url
+   * Creates a URL object from an internal path or external URL.
    *
-   * @see FillPdfLinkManipulatorInterface::parseUrlString()
+   * @param string $url
+   *   The internal path or external URL string.
    *
    * @return \Drupal\Core\Url
+   *   A Url object representing the URL string.
+   *
+   * @see FillPdfLinkManipulatorInterface::parseUrlString()
    */
   protected function createUrlFromString($url) {
     $url_parts = UrlHelper::parse($url);
@@ -45,7 +48,7 @@ class FillPdfLinkManipulator implements FillPdfLinkManipulatorInterface {
   }
 
   /**
-   * {@inheritDoc}
+   * {@inheritdoc}
    */
   public function parseLink(Url $link) {
     $query = $link->getOption('query');
@@ -139,6 +142,9 @@ class FillPdfLinkManipulator implements FillPdfLinkManipulatorInterface {
     return $request_context;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function parseUrlString($url) {
     $link = $this->createUrlFromString($url);
     return $this->parseLink($link);
@@ -163,7 +169,8 @@ class FillPdfLinkManipulator implements FillPdfLinkManipulatorInterface {
     //     ['<key in query string>', <default system value>]
     //     ...
     //   ]
-    // @todo: Create a value object for FillPdfMergeContext and get the defaults here from that
+    // @todo: Create a value object for FillPdfMergeContext and get the defaults
+    // here from that.
     $parameter_info = [
       'sample' => ['sample', FALSE],
       'force_download' => ['download', FALSE],