Quickstart PHP

Questo tutorial costruisce tre piccole applicazioni PHP che lavorano sulla risorsa Nazione: una le elenca, una ne crea una nuova e una aggiorna una esistente gestendo il controllo di concorrenza.

Prerequisiti

• PHP 7.4+ e Composer.
• Hai registrato un'app e ottenuto client_id e client_secret (per gli esperimenti conviene un'app privata).
• L'SDK PHP di Amica installato via Composer come repository VCS (vedi Installazione). Aggiungi al tuo composer.json il repository vcs https://github.com/amica-dev/php-sdk e "amica/php-sdk": "^3.0", poi esegui composer update. L'SDK usa Guzzle come client HTTP.

autoload

<?php
require_once __DIR__ . '/vendor/autoload.php';

Ottenere un access token

L'API è protetta da OAuth 2.0. Per uno script server-to-server il flusso più diretto è Client Credentials. La risorsa Nazione fa parte delle anagrafiche, coperte dallo scope comune.

auth.php

<?php
function getAccessToken(): string
{
    $client = new GuzzleHttp\Client();
    $response = $client->post('https://auth.amica20.it/connect/token', [
        'form_params' => [
            'grant_type' => 'client_credentials',
            'client_id' => 'IL_TUO_CLIENT_ID',
            'client_secret' => 'IL_TUO_CLIENT_SECRET',
            'scope' => 'read write comune',
        ],
    ]);
    $data = json_decode((string) $response->getBody(), true);
    return $data['access_token'];
}

Custodisci il client secret

Non scrivere mai client_id/client_secret nel codice versionato: leggili da variabili d'ambiente o da un gestore di segreti.

Configurare l'SDK

Configurare l'SDK

<?php
$config = Amica\Sdk\Configuration::getDefaultConfiguration()
    ->setHost('https://customerws1.amica20.it')
    ->setAccessToken(getAccessToken());

Elenca

I metodi PHP ricevono i parametri in modo posizionale. Recuperiamo prima le aziende (per il companyId), poi le prime nazioni dell'azienda 1:

elenca.php

<?php
$guzzle = new GuzzleHttp\Client();

try {
    // Elenco delle aziende disponibili per le credenziali in uso
    $aziende = new Amica\Sdk\Api\AziendaApi($guzzle, $config);
    foreach ($aziende->apiVversionConfigAziendaGet('3') as $azienda) {
        print_r($azienda);
    }

    // Prime 5 nazioni dell'azienda 1 (i parametri intermedi non usati restano null)
    $nazioni = new Amica\Sdk\Api\NazioneApi($guzzle, $config);
    $result = $nazioni->apiVversionCompanyIdNazioneGet('3', '1', null, 5);
    foreach ($result as $nazione) {
        echo $nazione->getId() . ': ' . $nazione->getNome() . ' (' . $nazione->getCodice() . ')' . PHP_EOL;
    }
} catch (Exception $e) {
    echo "Errore nella chiamata all'API: ", $e->getMessage(), PHP_EOL;
}

Cosa abbiamo imparato

1. La configurazione si costruisce in fluent: setHost() e setAccessToken().
2. Le classi API si istanziano con un client Guzzle e la configurazione.
3. I metodi seguono il pattern apiVversionCompanyIdNazioneGet($version, $companyId, $skip, $take, ...): i parametri opzionali non usati si passano come null.

Crea

crea.php

<?php
$guzzle = new GuzzleHttp\Client();

try {
    $nazioni = new Amica\Sdk\Api\NazioneApi($guzzle, $config);
    $nuova = new Amica\Sdk\Model\Nazione(['nome' => 'Atlantide', 'codice' => 'AT']);
    $creata = $nazioni->apiVversionCompanyIdNazionePost('3', '1', null, $nuova);
    echo 'Creata la nazione ' . $creata->getNome() . ' con id ' . $creata->getId() . PHP_EOL;
} catch (Exception $e) {
    echo "Errore nella chiamata all'API: ", $e->getMessage(), PHP_EOL;
}

Il modello Nazione espone nome e codice (un codice ISO 3166-1 alpha-2), oltre a id e concurrencyToken valorizzati dall'API nella risposta.

Aggiorna

L'aggiornamento segue il flusso leggi → modifica → scrivi, riusando il concurrencyToken ricevuto in lettura (vedi Controllo della concorrenza):

aggiorna.php

<?php
$guzzle = new GuzzleHttp\Client();

try {
    $nazioni = new Amica\Sdk\Api\NazioneApi($guzzle, $config);

    // 1. Leggi
    $nazione = $nazioni->apiVversionCompanyIdNazioneIdGet('3', '1', 1176);

    // 2. Modifica (mantenendo il concurrencyToken ricevuto)
    $nazione->setNome('Atlantide (rev. 2)');

    // 3. Scrivi
    $aggiornata = $nazioni->apiVversionCompanyIdNazioneIdPut('3', '1', $nazione->getId(), null, $nazione);
    echo 'Aggiornata: ' . $aggiornata->getNome() . ', nuovo token ' . $aggiornata->getConcurrencyToken() . PHP_EOL;
} catch (Exception $e) {
    echo "Errore nella chiamata all'API: ", $e->getMessage(), PHP_EOL;
}

Conflitto di concorrenza

Un 422 Unprocessable Entity indica che qualcun altro ha modificato la nazione dopo la tua lettura: rileggila per ottenere il concurrencyToken aggiornato, riapplica le modifiche e riprova.

Cosa abbiamo imparato

1. L'oggetto restituito porta con sé il concurrencyToken (getConcurrencyToken()): rileggi, modifica e rispediscilo.
2. In aggiornamento si usa apiVversionCompanyIdNazioneIdPut($version, $companyId, $id, null, $nazione); in creazione apiVversionCompanyIdNazionePost($version, $companyId, null, $nazione).
3. Un 422 segnala un conflitto di concorrenza, non un errore di validazione.

Codice sorgente dell'SDK

L'SDK PHP è open-source su github.com/amica-dev/php-sdk.