diff --git a/src/Controller/HandlePdfController.php b/src/Controller/HandlePdfController.php
index 43f7d7c95b70c6d2c7281785f264edd445ec865a..99d9b4be4b167f59064ad84d8a68765da3b73688 100644
--- a/src/Controller/HandlePdfController.php
+++ b/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;
diff --git a/src/FillPdfBackendPluginInterface.php b/src/FillPdfBackendPluginInterface.php
index d38acb846db399e9b30bfd34e3e0b1c16ee38a1a..af5e0e4b46ec95d163e24b477ad1e8ef4e4492fc 100644
--- a/src/FillPdfBackendPluginInterface.php
+++ b/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);
diff --git a/src/FillPdfContextManagerInterface.php b/src/FillPdfContextManagerInterface.php
index bf22f61b269e03728a9bf535aba31b520112fefd..45481303d0fc642e5b8590fd63d5d2165f4ec9ea 100644
--- a/src/FillPdfContextManagerInterface.php
+++ b/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);
diff --git a/src/FillPdfLinkManipulatorInterface.php b/src/FillPdfLinkManipulatorInterface.php
index 9e7d491799d39a5987c184b4e835064d47472a9e..4ba98bb415d04e60242035b4fc4f268d8e8c3ba5 100644
--- a/src/FillPdfLinkManipulatorInterface.php
+++ b/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);
diff --git a/src/OutputHandler.php b/src/OutputHandler.php
index 84c5bb634664eef73528adc2243e50f8dd82be02..9428cf7fbadfc45a8ce4e1444a95d589fd351fb9 100644
--- a/src/OutputHandler.php
+++ b/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) {
diff --git a/src/OutputHandlerInterface.php b/src/OutputHandlerInterface.php
index edb1b70341c336efa1b0ca828c69a0c8fc88e48b..8fb7fce657f75fadc41b0545557f64f57410b3c3 100644
--- a/src/OutputHandlerInterface.php
+++ b/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);
}
diff --git a/src/Plugin/BackendService/LocalService.php b/src/Plugin/BackendService/LocalService.php
index d42f34a9d390e8f7e68868c67529319f12cf395e..e2a21f8b3e360123f5317fd3d110f6f134991f4e 100644
--- a/src/Plugin/BackendService/LocalService.php
+++ b/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) {
diff --git a/src/Plugin/BackendServiceInterface.php b/src/Plugin/BackendServiceInterface.php
index fb2d68537db2774ca38407a0fce4e78f7cd5a380..78b4aaa0767eff836092e491ef2302d1b0f69367 100644
--- a/src/Plugin/BackendServiceInterface.php
+++ b/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);
}
diff --git a/src/Service/FillPdfLinkManipulator.php b/src/Service/FillPdfLinkManipulator.php
index 402ac1485465c173a2ca2576fd40b2dddf947bbf..d8980971159bb9052f70ae5a3c7b37805c3c0b69 100644
--- a/src/Service/FillPdfLinkManipulator.php
+++ b/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],