Services

Un servizio è un oggetto PHP che svolge una responsabilità specifica e riutilizzabile. Il core di Drupal mette a disposizione servizi per operazioni come:

accedere alla configurazione (ConfigFactoryInterface)
caricare e salvare entità
eseguire query sul database
inviare richieste HTTP (ClientInterface)
scrivere messaggi nel log (LoggerInterface)
gestire la cache (CacheBackendInterface)
inviare email
recuperare l'utente corrente
tradurre stringhe

I servizi forniti dal core sono definiti nel file core/core.services.yml, se è installato il modulo Devel è possibile utilizzare il comando drush devel:services che restituisce l'elenco dei servizi presenti nel container del sito corrente

Anche un modulo custom può definire un proprio servizio e anche renderlo disponibile ad altri componenti.

Tutti i servizi vengono raccolti nel Dependency Injection Container (o Service Container) che è responsabile di:

conservare le definizioni dei servizi
conoscere le dipendenze di ogni servizio
costruire gli oggetti necessari
passare le dipendenze ai loro costruttori
restituire i servizi ai componenti che li richiedono

Quando viene richiesto un servizio il container:

recupera o costruisce ciascuna dipendenza
crea un oggetto
passa le dipendenze al costruttore
restituisce l'oggetto al componente che lo ha richiesto

Dipendenze

Una classe ha una dipendenza quando ha bisogno di un altro oggetto per svolgere il proprio lavoro, ad esempio un sevizio che deve recuperare dati dal server non può effettuare autonomamente una richiesta HTTP senza utilizzare il client HTTP ClientInterface $httpClient.

Ha quindi una dipendenza da un oggetto che implementa ClientInterface:

public function __construct( 
  private readonly ClientInterface $httpClient, 
) {}

//esempio SCORRETTO
public function getForecast(): ?array { 
  $httpClient = new Client(); 
  // ... 
}

Interfaccia del servizio

L'interfaccia definisce il contratto del servizio, cioè:

quali metodi sono disponibili
quali parametri ricevono
quali dati restituiscono

L'interfaccia sarà contenuta nel file src/Service/ForecastClientInterface.php:

<?php 

declare(strict_types=1);

namespace Drupal\nome_modulo\Service; 

/** 
 * Provides access to weather forecast data. 
*/
interface ForecastClientInterface { 
    
/** 
 * Returns the current weather forecast. 
 * 
 * @return array{ 
 * location: string, 
 * timezone: string, 
 * temperature_unit: string, 
 * days: list<array{ 
 *  date: string, 
 *  weather_code: int, 
 *  high: float, 
 *  low: float 
 *  }> 
 * }|null 
 * The normalized forecast data, or NULL when it cannot be retrieved. 
 */
    public function getForecast(): ?array;
}

Il controller dipenderà quindi da ForecastClientInterface e non direttamente da ForecastClient.

Il file .services.yml

services: 
  cache.nome_modulo: # cache bin dedicato al modulo
    class: Drupal\Core\Cache\CacheBackendInterface 
    tags:
      - { name: cache.bin } # etichetta il servizio come cache bin
    factory: ['@cache_factory', 'get'] # indica che che il container non deve costruire direttamente un oggetto attraverso new
    arguments: [nome_modulo] 

 logger.channel.nome_modulo: 
    parent: logger.channel_base 
    arguments:
      - nome_modulo

  nome_modulo.forecast_client: # service ID
    class: Drupal\nome_modulo\Service\ForecastClient # Fully Qualified Class Name della classe che il container deve costruire
    arguments:
      - '@http_client' # la @ indica che si tratta di un sevizio
      - '@config.factory' 
      - '@cache.nome_modulo' 
      - '@logger.channel.nome_modulo' 
      - '@datetime.time' 

  nome_modulo.forecast_status_storage: 
    class: Drupal\nome_modulo\ForecastStatusStorage 
    arguments: 
      - '@state'

Drupal\nome_modulo\Service\ForecastClientInterface: '@nome_modulo.forecast_client' # crea un'alias

Implementazione del servizio

<?php 

declare(strict_types=1);

namespace Drupal\nome_modulo\Service;

use Drupal\Component\Datetime\TimeInterface;
use Drupal\Core\Cache\CacheBackendInterface;
use Drupal\Core\Config\ConfigFactoryInterface;
use GuzzleHttp\ClientInterface;
use GuzzleHttp\Exception\GuzzleException;
use Psr\Log\LoggerInterface;

/** 
 * Retrieves and normalizes weather forecast data. 
*/
final class ForecastClient implements ForecastClientInterface { 
    
/** 
 * Weather provider endpoint. 
 */
    private const API_ENDPOINT = 'https://api.open-meteo.com/v1/forecast'; 
    
    /** 
    * Cache lifetime in seconds. 
    */
    private const CACHE_MAX_AGE = 1800; 
    
    /** 
     * Cache tag used for forecast data. 
     */
    private const CACHE_TAG = 'nome_modulo:forecast'; 
    
    /** 
     * Constructs a ForecastClient object. 
     */
    public function __construct(
        private readonly ClientInterface $httpClient, // l’HTTP client utilizzato per comunicare con il provider esterno
        private readonly ConfigFactoryInterface $configFactory, // permette di recuperare nome_modulo.settings
        private readonly CacheBackendInterface $cache, // Senza cache, ogni visualizzazione della pagina produrrebbe una nuova richiesta HTTP
        private readonly LoggerInterface $logger, //per scrivere i log
        private readonly TimeInterface $time, // Permette di ottenere il timestamp corrente
        )
    { } 
    
    /** 
     * {@inheritdoc} 
     */
    public function getForecast(): ?array {
        $config = $this->configFactory->get('nome_modulo.settings'); // qui i dati li leggiamo dalla tabella config del db, non dal file nome_modulo.settings

        $latitude = $config->get('latitude'); // in nome_modulo.settings avremo la voce latitude
        $longitude = $config->get('longitude'); // in nome_modulo.settings avremo la voce longitude

        if (!is_numeric($latitude) || !is_numeric($longitude)) {
            $this->logger->error('The weather forecast cannot be retrieved because the coordinates are missing or invalid.', );
            return NULL;
        }

        $location = (string) ($config->get('location') ?? '');
        $timezone = (string) ($config->get('timezone') ?? 'UTC');

        $forecastDays = (int) ($config->get('forecast_days') ?? 5);
        $forecastDays = max(1, min(16, $forecastDays));

        $temperatureUnit = (string) ($config->get('temperature_unit') ?? 'celsius');

        if (!in_array($temperatureUnit, ['celsius', 'fahrenheit'], TRUE)) {
            $temperatureUnit = 'celsius';
        }

        $cacheId = $this->buildCacheId(
            (float) $latitude, 
            (float) $longitude, 
            $timezone, 
            $forecastDays, 
            $temperatureUnit, );

        $cached = $this->cache->get($cacheId);

        if ($cached !== FALSE && is_array($cached->data)) {
            return $cached->data;
        }

        try {
            $response = $this->httpClient->request('GET', self::API_ENDPOINT, [
                'query' => [
                    'latitude' => (float) $latitude, 
                    'longitude' => (float) $longitude, 
                    'daily' => implode(',', [
                        'weather_code', 
                        'temperature_2m_max', 
                        'temperature_2m_min',
                        ]), 
                        'timezone' => $timezone, 
                        'forecast_days' => $forecastDays, 
                        'temperature_unit' => $temperatureUnit,
                    ], 
                    'headers' => [
                        'Accept' => 'application/json',
                    ], 
                    'timeout' => 10,
                ]);

            $data = json_decode(
                (string) $response->getBody(), 
                TRUE, 
                512, 
                JSON_THROW_ON_ERROR, 
            );

            if (!is_array($data)) {
                throw new \UnexpectedValueException('The weather provider returned an invalid response.', );
            }

            $forecast = $this->normalizeForecast($data);

            $forecast['location'] = $location;

            $this->cache->set(
                $cacheId, 
                $forecast, 
                $this->time->getCurrentTime() + self::CACHE_MAX_AGE, 
                [self::CACHE_TAG], 
            );

            return $forecast;
        } catch (GuzzleException | \JsonException | \UnexpectedValueException $exception) {
             // GuzzleException è un errore HTTP, rete, timeout o risposta non valida
             // JsonException quando il corpo della risposta non è decodificabile come JSON
             // UnexpectedValueException  quando il JSON è valido ma la struttura non è conforme a quella attesa
            $this->logger->error(
                'The weather forecast could not be retrieved: @message', 
                ['@message' => $exception->getMessage()], 
            );

            return NULL;
        }
    } 
    
    /** 
     * Builds a cache ID for the requested forecast. 
     */
    private function buildCacheId(
        float $latitude, 
        float $longitude, 
        string $timezone, 
        int $forecastDays, 
        string $temperatureUnit, 
    ): string
    {
        $parameters = implode(':', [
            $latitude, 
            $longitude, 
            $timezone, 
            $forecastDays, 
            $temperatureUnit,
        ]);
        return 'nome_modulo:forecast:' . hash('sha256', $parameters);
    } 
    
    /** 
     * Converts the provider response into the module's internal format. 
     * 
     * @param array<string, mixed> $data 
     * The decoded provider response. 
     * 
     * @return array{ 
     *  timezone: string, 
     *  temperature_unit: string, 
     *  days: list<array{ 
     *      date: string, 
     *      weather_code: int, 
     *      high: float, 
     *      low: float 
     *  }> 
     * } 
     * 
     * The normalized forecast. 
     */
    private function normalizeForecast(array $data): array {
        $daily = $data['daily'] ?? NULL;
        $dailyUnits = $data['daily_units'] ?? NULL;

        if (!is_array($daily) || !is_array($dailyUnits)) {
            throw new \UnexpectedValueException('The response does not contain daily forecast data.', );
        }

        $dates = $daily['time'] ?? NULL;
        $weatherCodes = $daily['weather_code'] ?? NULL;
        $highs = $daily['temperature_2m_max'] ?? NULL;
        $lows = $daily['temperature_2m_min'] ?? NULL;

        if (
            !is_array($dates) || 
            !is_array($weatherCodes) || 
            !is_array($highs) || 
            !is_array($lows)
        ) {
            throw new \UnexpectedValueException('The daily forecast has an invalid structure.', );
        }

        $numberOfDays = count($dates);

        if (
            count($weatherCodes) !== $numberOfDays || 
            count($highs) !== $numberOfDays || 
            count($lows) !== $numberOfDays
        ) {
            throw new \UnexpectedValueException('The daily forecast contains inconsistent data.', );
        }

        $days = [];

        foreach ($dates as $index => $date) {
            if (
                !is_string($date) || 
                !is_numeric($weatherCodes[$index]) || 
                !is_numeric($highs[$index]) || 
                !is_numeric($lows[$index])
            ) {
                throw new \UnexpectedValueException('The daily forecast contains an invalid value.', );
            }

            $days[] = [
                'date' => $date, 
                'weather_code' => (int) $weatherCodes[$index], 
                'high' => (float) $highs[$index], 
                'low' => (float) $lows[$index],
            ];
        }

        return [
            'timezone' => (string) ($data['timezone'] ?? 'UTC'), 
            'temperature_unit' => (string) (
                $dailyUnits['temperature_2m_max'] ?? ''
            ), 
            'days' => $days,
        ];
    }
}

Dependency Injection

Il costruttore riceve il servizio attraverso la sua interfaccia, non utilizza new ForecastClient(...), :

public function __construct( 
    private readonly ForecastClientInterface $forecastClient, 
) {}

Il metodo statico create() recupera il servizio dal container, riceve il Service Container, richiede l'oggetto associato all'interfaccia, passa l'oggetto al costruttore e restituisce il controller inizializzato:

public static function create(ContainerInterface $container): static { 
  return new static( 
    $container->get(ForecastClientInterface::class), // restituisce Drupal\nome_modulo\Service\ForecastClientInterface
  ); 
}

Modules - Testing