Cleanup for parsing field stacks

app/Services/Template/TemplateService.php

@@ -13,6 +13,7 @@ namespace App\Services\Template;
 
 use App\Models\Quote;
 use App\Utils\Number;
+use Twig\Error\Error;
 use App\Models\Client;
 use App\Models\Credit;
 use App\Models\Design;
@@ -23,8 +24,12 @@ use App\Models\Payment;
 use App\Models\Project;
 use App\Utils\HtmlEngine;
 use League\Fractal\Manager;
+use Twig\Error\LoaderError;
+use Twig\Error\SyntaxError;
+use Twig\Error\RuntimeError;
 use App\Models\PurchaseOrder;
 use App\Utils\VendorHtmlEngine;
+use Twig\Sandbox\SecurityError;
 use App\Models\RecurringInvoice;
 use App\Utils\PaymentHtmlEngine;
 use App\Utils\Traits\MakesDates;
@@ -40,7 +45,8 @@ use League\Fractal\Serializer\ArraySerializer;
 
 class TemplateService
 {
-    use MakesDates, PdfMaker;
+    use MakesDates;
+    use PdfMaker;
 
     private \DomDocument $document;
 
@@ -78,7 +84,6 @@ class TemplateService
     private function init(): self
     {
 
-
         $this->commonmark = new CommonMarkConverter([
             'allow_unsafe_links' => false,
         ]);
@@ -111,7 +116,7 @@ class TemplateService
 
     /**
      * Iterate through all of the
-     * ninja nodes
+     * ninja nodes, and field stacks
      *
      * @param array $data - the payload to be passed into the template
      * @return self
@@ -128,6 +133,12 @@ class TemplateService
         return $this;
     }
 
+    /**
+     * Initialized a set of HTMLEngine variables
+     *
+     * @param  array | Collection $data
+     * @return self
+     */
     private function processVariables($data): self
     {
         $this->variables = $this->resolveHtmlEngine($data);
@@ -135,6 +146,11 @@ class TemplateService
         return $this;
     }
 
+    /**
+     * Returns a Mock Template
+     *
+     * @return self
+     */
     public function mock(): self
     {
         $tm = new TemplateMock($this->company);
@@ -165,9 +181,9 @@ class TemplateService
     /**
      * Returns the PDF string
      *
-     * @return mixed
+     * @return string
      */
-    public function getPdf(): mixed
+    public function getPdf(): string
     {
 
         if (config('ninja.invoiceninja_hosted_pdf_generation') || config('ninja.pdf_generator') == 'hosted_ninja') {
@@ -193,7 +209,7 @@ class TemplateService
     /**
      * Process data variables
      *
-     * @param  mixed $data
+     * @param  array | Collection $data
      * @return self
      */
     public function processData($data): self
@@ -221,19 +237,19 @@ class TemplateService
 
             try {
                 $template = $this->twig->createTemplate(html_entity_decode($template));
-            } catch(\Twig\Error\SyntaxError $e) {
+            } catch(SyntaxError $e) {
                 nlog($e->getMessage());
                 throw ($e);
-            } catch(\Twig\Error\Error $e) {
+            } catch(Error $e) {
                 nlog("error = " . $e->getMessage());
                 throw ($e);
-            } catch(\Twig\Error\RuntimeError $e) {
+            } catch(RuntimeError $e) {
                 nlog("runtime = " . $e->getMessage());
                 throw ($e);
-            } catch(\Twig\Error\LoaderError $e) {
+            } catch(LoaderError $e) {
                 nlog("loader = " . $e->getMessage());
                 throw ($e);
-            } catch(\Twig\Error\SecurityError $e) {
+            } catch(SecurityError $e) {
                 nlog("security = " . $e->getMessage());
                 throw ($e);
             }
@@ -340,6 +356,7 @@ class TemplateService
      * Resolves the labels and values needed to replace the string
      * holders in the template.
      *
+     * @param  array $data
      * @return array
      */
     private function resolveHtmlEngine(array $data): array
@@ -371,6 +388,13 @@ class TemplateService
 
     }
 
+    /**
+     * Pre Processes the Data Blocks into
+     * Twig consumables
+     *
+     * @param  array | Collection $data
+     * @return array
+     */
     private function preProcessDataBlocks($data): array
     {
         return collect($data)->map(function ($value, $key) {
@@ -394,6 +418,12 @@ class TemplateService
         })->toArray();
     }
 
+    /**
+     * Process Invoices into consumable form for Twig templates
+     *
+     * @param  array | Collection $invoices
+     * @return array
+     */
     public function processInvoices($invoices): array
     {
         $invoices = collect($invoices)
@@ -472,6 +502,13 @@ class TemplateService
 
     }
 
+    /**
+     * Pads Line Items with raw and formatted content
+     *
+     * @param  array $items
+     * @param  mixed $client
+     * @return array
+     */
     public function padLineItems(array $items, Client $client): array
     {
         return collect($items)->map(function ($item) use ($client) {
@@ -499,6 +536,12 @@ class TemplateService
         })->toArray();
     }
 
+    /**
+     * Transforms a Payment into consumable for twig
+     *
+     * @param  Payment $payment
+     * @return array
+     */
     private function transformPayment(Payment $payment): array
     {
 
@@ -625,6 +668,12 @@ class TemplateService
 
     }
 
+    /**
+     * @todo refactor
+     *
+     * @param  mixed $quotes
+     * @return array
+     */
     public function processQuotes($quotes): array
     {
         $it = new QuoteTransformer();
@@ -649,7 +698,7 @@ class TemplateService
      * Pushes credits through the appropriate transformer
      * and builds any required relationships
      *
-     * @param  mixed $credits
+     * @param  array | Collection $credits
      * @return array
      */
     public function processCredits($credits): array
@@ -723,12 +772,10 @@ class TemplateService
 
     }
 
-
-
     /**
      * Pushes payments through the appropriate transformer
      *
-     * @param  mixed $payments
+     * @param  array | Collection $payments
      * @return array
      */
     public function processPayments($payments): array
@@ -740,9 +787,14 @@ class TemplateService
 
         return $payments;
 
-
     }
 
+    /**
+     * @todo refactor
+     *
+     * @param  mixed $tasks
+     * @return array
+     */
     public function processTasks($tasks): array
     {
         $it = new TaskTransformer();
@@ -765,6 +817,12 @@ class TemplateService
 
     }
 
+    /**
+     * @todo refactor
+     *
+     * @param  mixed $projects
+     * @return array
+     */
     public function processProjects($projects): array
     {
 
@@ -778,6 +836,12 @@ class TemplateService
 
     }
 
+    /**
+     * @todo refactor
+     *
+     * @param  mixed $purchase_orders
+     * @return array
+     */
     public function processPurchaseOrders($purchase_orders): array
     {
 
@@ -791,6 +855,12 @@ class TemplateService
 
     }
 
+    /**
+     * Set Company
+     *
+     * @param  mixed $company
+     * @return self
+     */
     public function setCompany(Company $company): self
     {
         $this->company = $company;
@@ -798,11 +868,23 @@ class TemplateService
         return $this;
     }
 
+    /**
+     * Get Company
+     *
+     * @return Company
+     */
     public function getCompany(): Company
     {
         return $this->company;
     }
 
+    /**
+     * Setter that allows external variables to override the
+     * resolved ones from this class
+     *
+     * @param  mixed $variables
+     * @return self
+     */
     public function overrideVariables($variables): self
     {
         $this->variables = $variables;
@@ -811,7 +893,7 @@ class TemplateService
     }
 
     /**
-     * Parses and finds any stacks to replace
+     * Parses and finds any field stacks to inject into the DOM Document
      *
      * @return self
      */
@@ -860,6 +942,12 @@ class TemplateService
         return $this;
     }
 
+    /**
+     * Inject the Company Details into the DOM Document
+     *
+     * @param  bool $include_labels
+     * @return self
+     */
     private function companyDetails(bool $include_labels): self
     {
         $var_set = $this->getVarSet();
@@ -869,8 +957,10 @@ class TemplateService
             ->filter(function ($variable) use ($var_set) {
                 return isset($var_set['values'][$variable]) && !empty($var_set['values'][$variable]);
             })
-            ->map(function ($variable) {
+            ->when(!$include_labels, function ($collection) {
+                return $collection->map(function ($variable) {
                     return ['element' => 'p', 'content' => $variable, 'show_empty' => false, 'properties' => ['data-ref' => 'company_details-' . substr($variable, 1)]];
+                });
             })->toArray();
 
         $company_details = $include_labels ? $this->labelledFieldStack($company_details) : $company_details;
@@ -880,7 +970,7 @@ class TemplateService
         return $this;
     }
 
-    private function companyAddress(): self
+    private function companyAddress(bool $include_labels = false): self
     {
 
         $var_set = $this->getVarSet();
@@ -890,19 +980,30 @@ class TemplateService
             ->filter(function ($variable) use ($var_set) {
                 return isset($var_set['values'][$variable]) && !empty($var_set['values'][$variable]);
             })
-            ->map(function ($variable) {
+            ->when(!$include_labels, function ($collection) {
+                return $collection->map(function ($variable) {
                     return ['element' => 'p', 'content' => $variable, 'show_empty' => false, 'properties' => ['data-ref' => 'company_address-' . substr($variable, 1)]];
+                });
             })->toArray();
 
+        $company_address = $include_labels ? $this->labelledFieldStack($company_address) : $company_address;
+
         $this->updateElementProperties('company-address', $company_address);
 
         return $this;
     }
 
-    private function shippingDetails(): self
+    /**
+     * Injects the Shipping Details into the DOM Document
+     *
+     * @param  bool $include_labels
+     * @return self
+     */
+    private function shippingDetails(bool $include_labels = false): self
     {
-        if(!$this->entity->client)
+        if(!$this->entity->client) {
             return $this;
+        }
 
         $this->client = $this->entity->client;
 
@@ -929,7 +1030,13 @@ class TemplateService
         return $this;
     }
 
-    private function clientDetails(): self
+    /**
+     * Injects the Client Details into the DOM Document
+     *
+     * @param  bool $include_labels
+     * @return self
+     */
+    private function clientDetails(bool $include_labels = false): self
     {
         $var_set = $this->getVarSet();
 
@@ -938,16 +1045,26 @@ class TemplateService
             ->filter(function ($variable) use ($var_set) {
                 return isset($var_set['values'][$variable]) && !empty($var_set['values'][$variable]);
             })
-            ->map(function ($variable) {
+            ->when(!$include_labels, function ($collection) {
+                return $collection->map(function ($variable) {
                     return ['element' => 'p', 'content' => $variable, 'show_empty' => false, 'properties' => ['data-ref' => 'client_details-' . substr($variable, 1)]];
+                });
             })->toArray();
 
+        $client_details = $include_labels ? $this->labelledFieldStack($client_details) : $client_details;
 
         $this->updateElementProperties('client-details', $client_details);
 
         return $this;
     }
 
+    /**
+     * Resolves the entity.
+     *
+     * Only required for resolving the entity-details stack
+     *
+     * @return string
+     */
     private function resolveEntity(): string
     {
         $entity_string = '';
@@ -1031,7 +1148,13 @@ class TemplateService
 
     }
 
-    private function vendorDetails(): self
+    /**
+     * Inject Vendor Details into DOM Document
+     *
+     * @param  bool $include_labels
+     * @return self
+     */
+    private function vendorDetails(bool $include_labels = false): self
     {
 
         $var_set = $this->getVarSet();
@@ -1040,11 +1163,13 @@ class TemplateService
         collect($this->company->settings->pdf_variables->vendor_details)
             ->filter(function ($variable) use ($var_set) {
                 return isset($var_set['values'][$variable]) && !empty($var_set['values'][$variable]);
-            })
+            })->when(!$include_labels, function ($collection) {
-            ->map(function ($variable) {
+                return $collection->map(function ($variable) {
                     return ['element' => 'p', 'content' => $variable, 'show_empty' => false, 'properties' => ['data-ref' => 'vendor_details-' . substr($variable, 1)]];
+                });
             })->toArray();
 
+        $vendor_details = $include_labels ? $this->labelledFieldStack($vendor_details) : $vendor_details;
 
         $this->updateElementProperties('vendor-details', $vendor_details);