---
url: /gst-manager-acellemail/guides/apply-core-patches.md
description: >-
  How GST Manager's four one-time core hook points work — applied for you when
  you activate the plugin, with an SSH fallback for hardened hosts, what they
  change, how to verify them, and how AcelleMail upgrades are handled.
---

# Apply the core hook points

GST Manager requires **four one-time extension points** in your AcelleMail installation to enable core capabilities:

* **PDF engine integration:** Replaces stock invoice rendering with GST-compliant Tax and Export PDFs.
* **Customer GSTIN capture:** Injects validated GSTIN input fields into customer contact forms.
* **Export numbering:** Triggers custom sequential `EXP-YYYY-N` export numbering upon payment.
* **Tax calculation fix:** Ensures calculated GST amounts are added to order totals during checkout.

::: warning Critical tax calculation requirement
Without core hook points, AcelleMail bills the pre-tax subtotal and ignores your configured GST rates. The plugin applies hooks automatically during activation on standard hosting setups.
:::

## Core extension points

The plugin patches the following functional areas in AcelleMail:

1. **Export numbering:** Assigns sequential `EXP-YYYY-N` numbers when international invoices are paid.
2. **GST invoice PDF:** Generates statutory **Tax Invoice** and **Export Invoice** templates for admin and customer downloads.
3. **GSTIN contact form field:** Adds validated GSTIN collection fields alongside customer Tax ID settings.
4. **Order tax calculation:** Resolves AcelleMail core total calculations so configured tax rates are billed to customers.

All modifications are fenced with `gstmgr:hook` marker comments to prevent duplicate patching.

## Automated vs manual patching

* **Automatic activation (Default):** The plugin patches core files automatically when you activate it in AcelleMail.
* **Self-healing:** The plugin automatically reapplies hooks if a core AcelleMail update overwrites modified files.
* **SSH fallback:** Required only on hardened hosting environments where web server permissions restrict write access to `app/` or `resources/views/`.

## The SSH fallback procedure

If the admin dashboard displays a banner indicating core files could not be patched, complete patching via CLI.

### Prerequisites

* **SSH access:** Command-line access to the AcelleMail web server.
* **Plugin installed:** Files present in `storage/app/plugins/relyweb/gstmanager/`.
* **PHP CLI:** Active PHP runtime matching your web environment.
* **Database backup:** Recommended prior to executing file modifications.

### Run the patcher script

From your **AcelleMail root directory** (containing `artisan` and `composer.json`):

```bash
cd /path/to/acellemail
php storage/app/plugins/relyweb/gstmanager/scripts/apply-core-patches.php .
```

Clear cached application views and routes:

```bash
php artisan view:clear && php artisan route:clear
```

### CLI output reference

The patcher reports file-level status:

* `✓ patched: <file>` — Successfully modified.
* `↺ already patched: <file>` — Marker present; skipped.
* `- not in this build, skipping: <file>` — Optional path not present in current AcelleMail release.
* `! NOT WRITABLE: <file>` — Permission error. Re-run with appropriate filesystem ownership.
* `! could not patch (unexpected file contents): <file>` — File structure differs from supported templates.

## Verification checklist

Confirm active hooks after activation and licensing:

* **Customer profile:** GSTIN field appears on the customer contact editing page.
* **Invoice downloads:** Downloaded invoices render the GST Manager layout instead of default templates.
* **Checkout totals:** Order summary totals include configured GST tax amounts.
* **International orders:** Paid export orders receive custom `EXP-` identifiers.

## Handling AcelleMail core upgrades

Core AcelleMail upgrades may overwrite patched files:

* **Auto-healing:** Visiting the GST Manager dashboard automatically checks and reapplies missing hooks.
* **Hardened hosts:** Re-run the CLI patcher script and clear caches if permissions prevent web-based patching.

## Troubleshooting patch errors

* **`ERROR: Not an AcelleMail root: …`:** Execute the command from the folder containing `artisan`, passing `.` as the target argument.
* **`! could not patch (unexpected file contents)`:** Unrecognized file layout. Contact support@relyweb.co with your AcelleMail version.
* **`! NOT WRITABLE`:** Update file permissions to allow the web user or CLI user to modify target files.
* **GST features inactive:** Clear cached views via `php artisan view:clear && php artisan route:clear`.

## Related pages

* [Installation](/gst-manager-acellemail/installation) — full installation workflow
* [Requirements](/gst-manager-acellemail/requirements) — system dependencies and ionCube Loader
* [Troubleshooting](/gst-manager-acellemail/troubleshooting) — resolving display and tax issues
* [GST classification](/gst-manager-acellemail/features/gst-classification) — tax logic details