Skip to main content

Servizi e Facades globali

In questa sezione viene presentata una panoramica dei servizi e delle facades di piattaforma che sono utilizzati globalmente all'interno dell'applicazione. Questi componenti rappresentano funzionalità comuni e trasversali, fornendo un'interfaccia standardizzata per operazioni frequentemente utilizzate in diverse parti del sistema. La documentazione di seguito elenca e descrive questi strumenti essenziali, facilitando il loro utilizzo coerente attraverso l'intera applicazione.

🔑 Access​

La facade \App\Shared\Services\Access\Access (servizio \App\Shared\Services\Access\AccessService) fornisce un'interfaccia semplificata per la gestione degli access token, permettendo di creare token di accesso con i quali è possibile entrare in piattaforma loggati come un determinato utente. Il servizio supporta diversi tipi di token con caratteristiche specifiche per la sicurezza e la flessibilità d'uso.

Metodi disponibili​

  • generateAccessToken(AccessTokenOptionsDto $options): Genera un access token con le opzioni specificate
  • checkAccessToken(string $token): Verifica la validità di un token e restituisce l'utente associato
  • checkAccessTokenFromRequest(Request $request): Verifica il token dalla richiesta HTTP e restituisce l'utente associato

Opzioni del token​

Le opzioni del token possono essere configurate tramite il DTO AccessTokenOptionsDto che include:

  • type: Tipo di token (AccessTokenTypeEnum) - OneShot, Expiring, etc.
  • loginAs: Utente come cui effettuare il login dopo la verifica del token (UserDto)
  • expiresIn: Scadenza in secondi (opzionale, default: 3600 per token expiring)
  • enabledPath: Percorso abilitato dal token (opzionale)
  • enabledMethod: Metodo HTTP abilitato dal token (opzionale)

Tipi di token​

Il servizio supporta diversi tipi di token tramite AccessTokenTypeEnum:

  • OneShot: Token utilizzabile una sola volta, memorizzato in cache
  • Expiring: Token con scadenza temporale, memorizzato nel database

Meccanismi di sicurezza​

Il servizio implementa diversi livelli di sicurezza:

  • Payload crittografato: Il payload del token viene crittografato e contiene informazioni di verifica
  • Verifica integrità: Il token nella richiesta viene confrontato con quello nel payload crittografato
  • Controllo scadenza: I token expiring vengono automaticamente invalidati alla scadenza
  • Pulizia automatica: I token scaduti vengono rimossi automaticamente dal database
  • Controllo percorso: Possibilità di limitare l'accesso a percorsi specifici
  • Controllo metodo: Possibilità di limitare l'accesso a metodi HTTP specifici

Utilizzo del middleware​

Il servizio può essere utilizzato tramite il middleware AccessMiddleware che:

  • Intercetta le richieste HTTP
  • Cerca il token nell'header X-Access-Token o nel query parameter at
  • Verifica la validità del token
  • Effettua il login automatico come utente associato

Esempio di utilizzo​

// Genera un token OneShot per un utente specifico
$token = Access::generateAccessToken(
    AccessTokenOptionsDto::from([
        'type' => AccessTokenTypeEnum::OneShot,
        'loginAs' => UserDto::from($user),
    ])
);

// Genera un token Expiring con scadenza personalizzata
$token = Access::generateAccessToken(
    AccessTokenOptionsDto::from([
        'type' => AccessTokenTypeEnum::Expiring,
        'loginAs' => UserDto::from($user),
        'expiresIn' => 7200, // 2 ore
        'enabledPath' => '/api/users',
        'enabledMethod' => HttpMethodEnum::Get,
    ])
);

// Verifica un token
$user = Access::checkAccessToken($token);

// Verifica un token dalla richiesta HTTP
$user = Access::checkAccessTokenFromRequest($request);

📸 Screenshot​

La facade \App\Shared\Services\Print\Screenshot fornisce un'interfaccia semplificata per il PrintService, permettendo di generare screenshot e PDF da URL o contenuto HTML. Il servizio è configurabile con diversi driver, attualmente supportando solo browsershot.

Metodi disponibili​

  • processUrl(string $url, ?PrintProcessOptionsDto $options = null): Genera screenshot/PDF da un URL
  • processHtml(string $content, ?PrintProcessOptionsDto $options = null): Genera screenshot/PDF da contenuto HTML
  • saveUrl(string $url, ?string $filename = null, ?PrintProcessOptionsDto $options = null): Salva screenshot/PDF da URL su disco
  • saveHtml(string $content, ?string $filename = null, ?PrintProcessOptionsDto $options = null): Salva screenshot/PDF da HTML su disco

Opzioni di stampa​

Le opzioni di stampa possono essere configurate tramite il DTO PrintProcessOptionsDto che include:

  • printAs: Utente come cui eseguire la stampa (effettuerà il login come questo utente)
  • savePath: Percorso di salvataggio del file (default: valore da config print.default_save_path)
  • disk: Disco di storage su cui salvare (default: valore da config print.default_disk)
  • outputFormat: Formato di output (pdf, png, jpg) (default: valore da config print.default_format)
  • pageFormat: Formato pagina (A4, Letter, etc) (default: valore da config print.default_page_format)
  • pageOrientation: Orientamento pagina (portrait/landscape) (default: valore da config print.default_page_orientation)
  • margins: Margini pagina tramite PrintMarginsDto (default: valori da config print.default_margins)
  • viewport: Dimensioni viewport tramite PrintViewportDto
  • delay: Ritardo in millisecondi prima della cattura

Configurazione​

Il servizio è configurato tramite il file config/print.php:

return [
    // Driver predefinito
    'driver' => env('PRINT_DRIVER', 'browsershot'),

    // Disco di storage per i file
    'default_disk' => env('PRINT_DEFAULT_DISK', 'local'),

    // Percorso di salvataggio predefinito
    'default_save_path' => env('PRINT_DEFAULT_SAVE_PATH', 'prints'),

    // Formato di output predefinito (pdf, html, png, jpg)
    'default_format' => env('PRINT_DEFAULT_FORMAT', 'pdf'),

    // Formato pagina predefinito
    'default_page_format' => env('PRINT_DEFAULT_PAGE_FORMAT', 'A4'),

    // Orientamento pagina predefinito
    'default_page_orientation' => env('PRINT_DEFAULT_PAGE_ORIENTATION', 'portrait'),

    // Margini predefiniti
    'default_margins' => [
        'top' => env('PRINT_DEFAULT_MARGIN_TOP', 10),
        'right' => env('PRINT_DEFAULT_MARGIN_RIGHT', 10),
        'bottom' => env('PRINT_DEFAULT_MARGIN_BOTTOM', 10),
        'left' => env('PRINT_DEFAULT_MARGIN_LEFT', 10),
    ],

    // Configurazioni specifiche per driver
    'drivers' => [
        'browsershot' => [
            'timeout' => env('PRINT_BROWSERSHOT_TIMEOUT', null),
            'show_background' => env('PRINT_BROWSERSHOT_SHOW_BACKGROUND', false),
            'wait_until' => env('PRINT_BROWSERSHOT_WAIT_UNTIL', false),
            'delay' => env('PRINT_BROWSERSHOT_DELAY', null),
            'user_agent' => env('PRINT_BROWSERSHOT_USER_AGENT', null),
            'no_sandbox' => env('PRINT_BROWSERSHOT_NO_SANDBOX', true),
        ],
    ],
];

Esempio di utilizzo​

// Genera PDF da URL
$pdf = Screenshot::processUrl('https://example.com');

// Salva screenshot da HTML
Screenshot::saveHtml('<h1>Hello World</h1>', 'output.png');

// Salva PDF da URL con opzioni personalizzate
Screenshot::saveUrl(
    'https://google.com',
    'test.pdf',
    PrintProcessOptionsDto::from([
        'outputFormat' => PrintOutputFormatEnum::Pdf,
        'pageOrientation' => 'landscape',
    ])
);
Autenticazione per la stampa

Per semplificare l'accesso alle pagine in stampa, anche quelle protette da autenticazione, viene utilizzata la facade Access. Se non viene specificato un utente tramite l'opzione printAs nel DTO di input, il sistema effettuerà automaticamente il fallback su un utente "god" di sistema per garantire l'accesso a tutte le risorse necessarie per la stampa.

È fondamentale effettuare tutti i controlli di autenticazione e autorizzazione necessari prima di utilizzare questa facade. L'utilizzo del "god user" è pensato solo per il processo tecnico di stampa e non deve bypassare le normali verifiche di sicurezza dell'applicazione.

Route disponibili​

Il servizio di stampa è accessibile anche tramite le seguenti route nel namespace shared con middleware di autenticazione:

/*
|--------------------------------------------------------------------------
| Print
|--------------------------------------------------------------------------
*/
Route::middleware('auth')->prefix('print')->name('print.')->group(function () {
    Route::post('/save-url', [\App\Shared\Http\Controllers\PrintController::class, 'saveUrl'])->name('save-url');
    Route::post('/download-url', [\App\Shared\Http\Controllers\PrintController::class, 'downloadUrl'])->name('download-url');
    Route::post('/download-html', [\App\Shared\Http\Controllers\PrintController::class, 'downloadHtml'])->name('download-html');
});

Queste route permettono di:

  • POST /print/save-url: Salvare screenshot/PDF da URL su disco
  • POST /print/download-url: Scaricare screenshot/PDF da URL
  • POST /print/download-html: Scaricare screenshot/PDF da contenuto HTML

Tutte le route richiedono autenticazione tramite il middleware auth e sono raggruppate sotto il prefisso shared.print con naming shared.print.*.

Request Classes​

Le route utilizzano due classi FormRequest per la validazione dei dati:

  • PrintUrlRequest: Per le route che processano URL (save-url, download-url)
  • PrintHtmlRequest: Per le route che processano HTML (download-html)

Entrambe le classi condividono le stesse regole di validazione, con l'unica differenza nel campo principale:

// PrintUrlRequest
'url' => 'required|string',

// PrintHtmlRequest
'content' => 'required|string',

Campi comuni validati:​

  • fileName: Nome del file di output (required)
  • savePath: Percorso di salvataggio (nullable)
  • disk: Disco di storage (nullable)
  • outputFormat: Formato di output (pdf, png, jpg) (nullable)
  • pageFormat: Formato pagina (A4, Letter, etc) (nullable)
  • pageOrientation: Orientamento (portrait/landscape) (nullable)
  • margins: Margini pagina con sottocampi top, right, bottom, left (nullable)
  • viewport: Dimensioni viewport con sottocampi width, height (nullable)