> For the complete documentation index, see [llms.txt](https://wonder-image.gitbook.io/wonder-image-gestionale/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wonder-image.gitbook.io/wonder-image-gestionale/concetti/hook.md).

# Hook del sito

Un sito può agganciarsi al gestionale senza toccarne il codice: scrive una classe, la dichiara nella configurazione del modulo e riscrive solo i metodi che gli servono.

```php
// custom/class/Gestionale/NotificheMagazzino.php
final class NotificheMagazzino extends Wonder\Plugin\Gestionale\Extensions\GestionaleExtension
{
    public function onStatusChanged(string $entity, int $entityId, string $field, string $from, string $to): void
    {
        // avvisa il capo magazzino
    }
}
```

```php
// custom/config/modules/gestionale.php
'extensions' => [
    App\Gestionale\NotificheMagazzino::class,
],
```

## Hook di G1

| Hook                                                      | Quando                                                        | Può bloccare |
| --------------------------------------------------------- | ------------------------------------------------------------- | ------------ |
| `onStatusChanged($entity, $entityId, $field, $from, $to)` | dopo un cambio di stato registrato da `StatusLogger`          | no           |
| `beforeEmailSend($key, $message): array`                  | prima di mandare un'email; torna il messaggio, anche cambiato | no           |

Gli altri hook nascono con il sotto-progetto che li usa.

### Le email che passano da `beforeEmailSend`

| Chiave            | Email                             | Messaggio                                                       |
| ----------------- | --------------------------------- | --------------------------------------------------------------- |
| `stock.low_stock` | i prodotti sotto la scorta minima | `['to' => list<string>, 'subject' => string, 'body' => string]` |

* `to` può tornare come lista o come stringa separata da virgole: il gestionale lo rilegge e scarta gli indirizzi non validi.
* Un `to` vuoto **ferma l'invio**, e gli avvisi contano come mandati: è una scelta del sito, non un guasto.
* Un `to` fatto solo di indirizzi non validi ferma l'invio allo stesso modo, ma lascia una segnalazione per lo sviluppatore (`error_reports`) con gli indirizzi scartati: somiglia più a uno sbaglio che a una scelta.
* Un'estensione che solleva un'eccezione finisce nel log e l'email parte con il messaggio com'era prima di lei.

```php
public function beforeEmailSend(string $key, array $message): array
{
    if ($key === 'stock.low_stock') {
        $message['to'][] = 'magazzino@example.com';
    }

    return $message;
}
```

## Regole

* Le estensioni girano **nell'ordine in cui sono dichiarate**.
* Una classe che non esiste, o che non estende la base, viene saltata: la configurazione di un sito non deve poter rompere il gestionale.
* Un hook che solleva un'eccezione finisce nel log e **non ferma** il flusso: gli hook `on…` arrivano a operazione già fatta, tirarla indietro sarebbe peggio.
* Gli hook `before…` che arriveranno potranno fermare l'operazione sollevando un `UserError`.
* `Extensions::run()` avvisa e basta; `Extensions::filter()` fa passare un valore da un'estensione all'altra.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wonder-image.gitbook.io/wonder-image-gestionale/concetti/hook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.