<?php

/**
 * Hutko - Платіжний сервіс, який рухає бізнеси вперед.
 *
 * Запускайтесь, набирайте темп, масштабуйтесь – ми підстрахуємо всюди.
 *
 * @author    panariga
 * @copyright 2025 Hutko
 * @license   http://opensource.org/licenses/afl-3.0.php Academic Free License (AFL 3.0)
 */


if (!defined('_PS_VERSION_')) {
    exit;
}

/**
 * HutkoReturnModuleFrontController handles the return URL from an external service.
 *
 * This controller is responsible for receiving a specially encoded parameter
 * (`hutkoPV`) from a payment gateway or external system after a transaction.
 * It decodes this parameter, validates its content, and redirects the customer
 * to the standard PrestaShop order confirmation page if the data is valid.
 *
 * The `hutkoPV` parameter is expected to be a URL-safe encoded JSON string
 * containing critical order details like `id_cart`, `id_module`, `id_order`,
 * and the customer's `secure_key`.
 *
 * If the `hutkoPV` parameter is missing, cannot be decoded/parsed, or fails
 * validation (specifically the secure key check against the current customer),
 * it throws a PrestaShopException.
 *
 * @property \Hutko $module The instance of the main module class (\Hutko).
 * @property \Context $context The current PrestaShop context.
 * @property \Smarty $context->smarty The Smarty instance for templating (though not used here).
 * @property \Customer $context->customer The currently logged-in customer.
 * @property \Link $context->link The PrestaShop Link class instance for URL generation.
 * @extends ModuleFrontController
 * @package Modules\Hutko
 * @author Panariga
 * @copyright Hutko
 * @license http://opensource.org/licenses/afl-3.0.php Academic Free License (AFL 3.0) // Adjust if using a different license
 * @version 1.0.0 // Start with a version number
 */
class HutkoReturnModuleFrontController extends ModuleFrontController
{
    /**
     * Initializes the content for the controller.
     *
     * This method is the main entry point for this controller. It retrieves
     * the `hutkoPV` parameter from the request, decodes and parses it,
     * validates the required data, and redirects the customer to the
     * order confirmation page if successful.
     *
     * @throws PrestaShopException If the `hutkoPV` parameter is missing,
     *                             invalid, or the secure key validation fails.
     *                             The exception message indicates the nature
     *                             of the failure.
     */
    public function initContent()
    {
        // Retrieve the 'hutkoPV' parameter from the GET or POST request.
        // It is expected to be a URL-safe encoded string.
        $hutkoPV = Tools::getValue('hutkoPV');

        // Decode the URL-safe string using the module's custom function.
        // If the decoding fails or the input is empty, $hutkoPV will be false or empty.
        $decodedHutkoPV = $this->module->urlSafeDecode($hutkoPV);

        // Check if decoding was successful and the result is not empty.
        if ($decodedHutkoPV) {
            // Attempt to decode the JSON string into a PHP array.
            $decodedPV = json_decode($decodedHutkoPV, true);


            // Validate the decoded JSON:
            // 1. Check if json_decode returned an array.
            // 2. Check if all expected keys ('id_cart', 'id_module', 'id_order', 'key') exist in the array.
            if (
                is_array($decodedPV)
                && isset($decodedPV['id_cart'])
                && isset($decodedPV['id_module'])
                && isset($decodedPV['id_order'])
                && isset($decodedPV['key'])
            ) {

                // If validation passes, generate the URL for the standard order confirmation page.
                // The URL includes the validated parameters necessary for the order-confirmation controller
                // to load and display the correct order details.
                $orderConfirmationUrl = $this->context->link->getPageLink(
                    'order-confirmation', // The controller to redirect to
                    true,                 // Use SSL
                    $this->context->language->id, // Current language ID
                    [                     // Parameters for the order-confirmation page
                        'id_cart' => (int)$decodedPV['id_cart'], // Cast to int for safety
                        'id_module' => (int)$decodedPV['id_module'], // Cast to int
                        'id_order' => (int)$decodedPV['id_order'], // Cast to int
                        'key' => pSQL($decodedPV['key']), // Sanitize key before using in URL (though link generation does some)
                    ]
                );

                // Redirect the customer to the order confirmation page.
                Tools::redirect($orderConfirmationUrl);

                // Stop script execution after redirection.
                return;
            }
            // If decoding was successful but validation failed:
            else {
                // Throw an exception indicating a validation failure (broken data).
                throw new PrestaShopException('hutkoPV data validation failed or structure is incorrect.');
            }
        }

        // If hutkoPV parameter was missing or decoding failed:
        // Throw an exception indicating the parameter is missing or unusable.
        throw new PrestaShopException('hutkoPV parameter is missing or broken.');
    }
}