Hook `actionSeigiGpsrEntityModify`

Hook actionSeigiGpsrEntityModify jest udostępniany przez moduł SEIGI GPSR. Pozwala innym modułom na dynamiczną modyfikację listy podmiotów odpowiedzialnych przypisanych do produktu.

Za pomocą hooka można:

modyfikować istniejące wpisy,
usuwać wpisy,
dodawać nowe wpisy,
wykonywać zmiany zależne od produktu, producenta lub dostawcy.

Wywołanie hooka

Hook jest wywoływany przez moduł SEIGI GPSR w następujący sposób:

Hook::exec('actionSeigiGpsrEntityModify', [
    'id_product' => $id_product,
    'id_manufacturer' => $id_manufacturer,
    'id_supplier' => $id_supplier,
    'responsibleEntities' => &$responsibleEntities,
]);

Tablica responsibleEntities jest przekazywana przez referencję. Oznacza to, że zmiany wykonane przez moduł obsługujący hook zostaną bezpośrednio zastosowane do listy podmiotów odpowiedzialnych wykorzystywanej przez SEIGI GPSR.

Parametry

Parametr	Typ	Opis
`id_product`	`int`	Identyfikator produktu, dla którego pobierane są podmioty odpowiedzialne.
`id_manufacturer`	`int`	Identyfikator producenta przypisanego do produktu.
`id_supplier`	`int`	Identyfikator dostawcy przypisanego do produktu.
`responsibleEntities`	`array`	Lista podmiotów odpowiedzialnych. Tablica jest przekazywana przez referencję i może być modyfikowana.

Struktura pojedynczego wpisu zależy od danych obsługiwanych przez moduł SEIGI GPSR. W poniższych przykładach wykorzystywane są pola:

external_id – zewnętrzny identyfikator podmiotu,
name – nazwa podmiotu.

Rejestracja hooka

Moduł korzystający z hooka powinien zarejestrować go podczas instalacji:

public function install()
{
    return parent::install()
        && $this->registerHook('actionSeigiGpsrEntityModify');
}

Obsługa hooka

W module obsługującym hook należy utworzyć metodę:

public function hookActionSeigiGpsrEntityModify(array $params)
{
    // Modyfikacja listy podmiotów odpowiedzialnych.
}

Modyfikacja istniejącego wpisu

Poniższy przykład dodaje prefiks do nazwy podmiotu o identyfikatorze IMP001:

public function hookActionSeigiGpsrEntityModify(array $params)
{
    foreach ($params['responsibleEntities'] as $key => $entity) {
        if (
            isset($entity['external_id'])
            && $entity['external_id'] === 'IMP001'
        ) {
            $params['responsibleEntities'][$key]['name'] =
                'Zmodyfikowany: ' . $entity['name'];
        }
    }
}

Usuwanie wpisu

Aby usunąć podmiot odpowiedzialny, należy użyć funkcji unset():

public function hookActionSeigiGpsrEntityModify(array $params)
{
    foreach ($params['responsibleEntities'] as $key => $entity) {
        if (
            isset($entity['external_id'])
            && $entity['external_id'] === 'IMP001'
        ) {
            unset($params['responsibleEntities'][$key]);
        }
    }
}

Po usunięciu wpisów można opcjonalnie ponownie uporządkować indeksy tablicy:

$params['responsibleEntities'] = array_values(
    $params['responsibleEntities']
);

Jest to przydatne, gdy dalsza część kodu oczekuje tablicy indeksowanej kolejno od zera.

Dodawanie nowego wpisu

Nowy podmiot można dodać przez dopisanie kolejnego elementu do tablicy:

public function hookActionSeigiGpsrEntityModify(array $params)
{
    $params['responsibleEntities'][] = [
        'external_id' => 'CUSTOM001',
        'name' => 'Dodatkowy podmiot odpowiedzialny',
    ];
}

Dodawany wpis powinien posiadać strukturę zgodną z wpisami zwracanymi przez moduł SEIGI GPSR.

Modyfikacja zależna od produktu

Parametr id_product pozwala ograniczyć zmiany do konkretnego produktu:

public function hookActionSeigiGpsrEntityModify(array $params)
{
    if ((int) $params['id_product'] !== 123) {
        return;
    }

    foreach ($params['responsibleEntities'] as $key => $entity) {
        $params['responsibleEntities'][$key]['name'] =
            'Produkt 123: ' . $entity['name'];
    }
}

Modyfikacja zależna od producenta

Zmiany mogą być wykonywane tylko dla produktów określonego producenta:

public function hookActionSeigiGpsrEntityModify(array $params)
{
    $manufacturerId = 10;

    if ((int) $params['id_manufacturer'] !== $manufacturerId) {
        return;
    }

    $params['responsibleEntities'][] = [
        'external_id' => 'MANUFACTURER-10',
        'name' => 'Podmiot odpowiedzialny producenta',
    ];
}

Modyfikacja zależna od dostawcy

Analogicznie można sprawdzić identyfikator dostawcy:

public function hookActionSeigiGpsrEntityModify(array $params)
{
    $supplierId = 20;

    if ((int) $params['id_supplier'] !== $supplierId) {
        return;
    }

    foreach ($params['responsibleEntities'] as $key => $entity) {
        $params['responsibleEntities'][$key]['name'] =
            'Dostawca 20: ' . $entity['name'];
    }
}

Kompletny przykład

Poniższy przykład pokazuje jednocześnie modyfikowanie, usuwanie oraz dodawanie wpisów:

public function hookActionSeigiGpsrEntityModify(array $params)
{
    if (
        !isset($params['responsibleEntities'])
        || !is_array($params['responsibleEntities'])
    ) {
        return;
    }

    foreach ($params['responsibleEntities'] as $key => $entity) {
        $externalId = $entity['external_id'] ?? null;

        // Usunięcie wskazanego podmiotu.
        if ($externalId === 'IMP001') {
            unset($params['responsibleEntities'][$key]);
            continue;
        }

        // Modyfikacja pozostałych wpisów.
        if (isset($entity['name'])) {
            $params['responsibleEntities'][$key]['name'] =
                'Dozwolony: ' . $entity['name'];
        }
    }

    // Dodanie własnego podmiotu.
    $params['responsibleEntities'][] = [
        'external_id' => 'CUSTOM001',
        'name' => 'Własny podmiot odpowiedzialny',
    ];

    // Ponowne uporządkowanie indeksów po użyciu unset().
    $params['responsibleEntities'] = array_values(
        $params['responsibleEntities']
    );
}

Uwagi

Tablica responsibleEntities jest przekazywana przez referencję, dlatego nie trzeba zwracać jej z metody hooka.
Przed odczytaniem pól wpisu warto sprawdzić ich istnienie za pomocą isset() lub operatora ??.
Przy usuwaniu elementów podczas wykonywania pętli należy operować na oryginalnej tablicy:
```
unset($params['responsibleEntities'][$key]);
```
Dodawane wpisy powinny posiadać strukturę zgodną z formatem obsługiwanym przez moduł SEIGI GPSR.
Hook może zostać obsłużony przez wiele modułów. Każdy z nich może zmodyfikować listę podmiotów odpowiedzialnych.
Kolejność wykonania modułów podpiętych do hooka może mieć wpływ na końcową zawartość tablicy.

GPSR Modyfikacja podmiotów odpowiedzialnych

Hook actionSeigiGpsrEntityModify