Laravel permette di aggiungere nuove funzioni in modo semplice tramite l'aggiunta di estensioni chiamate package. In questo articolo ti racconto qual'è stata la procedura che ha portato alla creazione del mio primo package.
Recentemente ho creato (github) e pubblicato (packagist) il mio primo package per Laravel: laravel-civic-sip. L'idea alla base di questo package è quella di permettere il login attraverso Civic all'interno di applicazioni Laravel senza dover scrivere codice specifico.
NOTA: Civic è una piattaforma per il login sicuro che sfrutta la blockchain, maggiori informazioni qui.
Cos’è un package di laravel? #
Il framework Laravel integra al suo interno il codice per implementare le più comuni operazioni che possono essere richieste da una applicazione web in modo agile e veloce. Ovviamente all'interno del core di Laravel non è sempre presente tutto ciò che serve e quindi viene fornito un modo per estenderne le funzionalità importando codice scritto da altri ed evitando quindi di dover reinventare la ruota riscrivendo codice che è già stato prodotto e testato da altri. Il modo con cui Laravel permette di importare codice scritto da altri per estenderne le funzionalità è costituito dai package.
I package sono dei bundle di codice che racchiudono rotte, controller e views che permettono di estendere le funzionalità base di Laravel con nuove funzioni.
Come si crea un nuovo package? #
Benchè la creazione di un nuovo package per Laravel sia abbastanza semplice, ho trovato la documentazione ufficiale un po’ troppo scarna da questo punto di vista. Quindi ho deciso di riportare i passaggi che ho seguito per scrivere il mio primo package per Laravel.
NOTA: in questa guida ti descrivo gli step che ho seguito per creare la mia prima estensione implementando un wrapper per la libreria civic-sip-php. Naturalmente la procedura da seguire è del tutto generale ed è quindi valida per la creazione di un qualunque altro package. Naturalmente il codice che ho scritto sarà specializzato per questa libreria e dovrai modificarlo per adattarlo alle tue necessità.
Step 1: Installazione di Laravel #
La prima cosa che devi fare è creare un nuovo progetto Laravel. Ci sono diversi modi per farlo descritti dalla documentazione ufficiale.
Io ho inizializzato il mio progetto chiamato laravel-civic-sip utilizzando questi due comandi:
composer global require "laravel/installer" laravel new laravel-civic-sip
Step 2: creazione di una cartella per il package #
A questo punto, per tenere ordinato il progetto e non mischiare il codice dell’applicazione a quello del package, devi creare la cartella /package all'interno della root del progetto. All'interno di questa cartella dovrai mettere tutti i file che compongono il package che vuoi a creare.
Una volta fatto ciò devi inizializzare composer all'interno di questa nuova cartella tramite il comando composer init.
NOTA: All'interno della cartella /package io ho strutturato il codice seguendo la seguente gerarchia:
- config-- per tutti i file di configurazione
- src
- facades-- per il codice relativo alle facades
- providers-- per il codice relativo ai providers
- tests-- per tutto il codice relativo ai test
Step 3: Configurare composer #
Prima di procedere con la scrittura del codice vero e proprio del package bisogna fare in modo che composer sia in grado di riconoscere i namespace usati all'interno del codice legandoli ai path dei file utilizzati nel progetto. Per fare ciò devi solo modificare la sezione autoload del file composer.json.
Ad esempio, nel mio package io ho utilizzato il namespace LMillucci\CivicSIP per cui ho modificato la sezione autoload del file composer.json in questo modo:
Inoltre per poter sfruttare l’autodiscovery dei package introdotta con Laravel 5.5 ho registrato i provider e le facades all'interno del composer.json in questo modo:
"autoload": { "psr-4": { "LMillucci\CivicSIP\": "src/" } }
Step 3: Scrivere la logica del package #
Per l'implementazione della logica del package, Laravel richiede che vengano create due classi particolari:
- Un service provider che definisce le informazioni sul pacchetto (quali controller usa, quali rotte ecc…)
- Una Facade che permette di definire un alias con cui chiamare il service provider.
Naturalmente puoi aggiungere al package file di configurazione, views, routes ecc.. a seconda delle tue necessità.
Per il mio package ho avuto bisogno solo di un file di configurazione che ho aggiunto all'interno della cartella ./config.
Step 3.1: Creazione Service Provider #
Per la creazione del service provider basta estendere la classe Illuminate\Support\ServiceProvider. Per il mio package ho scritto questo ServiceProvider:
Come vedi il codice è molto semplice ma puoi notare:
- il metodo boot() con cui viene pubblicata la configurazione definita nel file dedicato alla configurazione.
- il metodo register() con cui viene registrato il servizio come singleton
- il metodo provides() con cui viene registrato quale servizio viene fornito dal provider
Step 3.2: creazione Facade #
Per creare una facade basta estendere la classe Illuminate\Support\Facades\Facade. In questa classe è importante che ti ricordi di fare l’override del metodo getFacadeAccessor() facendogli restituire il nome che vogliamo assegnare al package.
Come puoi vedere il codice che ho scritto è veramente banale:
A questo punto lo sviluppo del package è completo. Nel prossimo punto ti farò vedere come pubblicare il package sul sito packagist in modo da poterlo importare in un progetto sfruttando composer.
Step 4: Pubblicare il package #
La prima cosa da fare per pubblicare il package è creare un repository su github e fare il push del codice.
NOTA: ricordati di fare il push solo del contenuto della cartella ./package e di tutto il progetto!
Una volta che il codice è su github devi creare una tag. Questo passaggio è fondamentale in quanto la tag andrà ad indicare la versione del package (es 1.0.0)
Arrivato a questo punto, per rendere il package installabile tramite il comando composer require, è necessario aggiungerlo al sito packagist.com.
Per fare ciò, una volta fatto il login sulla piattaforma, ti basta visitare la pagina di submit e copiare il link del repository github confermando tramite il tasto check.
Step 5: aggiungere il pacchetto ad un progetto #
Complimenti, hai appena pubblicato la tua prima estensione per Laravel! Ora per verificare che tutto abbia funzionato correttamente devi installare il tuo package all'interno di un progetto.
La prima cosa da fare quindi è il require del pacchetto tramite il comando
composer require lmillucci/laravel-civic-sip
Siccome per il funzionamento del mio package è richiesta la creazione di un file di configurazione puoi utilizzare il comando di seguito in modo che Laravel lo crei in modo automatico:
php artisan vendor:publish
Infine, per poter fare il login con Civic devi definire le seguenti variabili d'ambiente all'interno del file .env:
CIVIC_APPLICATION_ID=app_id
CIVIC_APPLICATION_SECRET=123456abcd
CIVIC_PRIVATE_SIGNING_KEY=abcd123456
CIVIC_ENVIRONMENT=prod
Ora puoi fare il login con Civic semplicemente tramite il comando:
CivicFacade::exchangeToken($token)
Congratulazione hai appena sviluppato e pubblicato il tuo primo package laravel! #
Se c'è qualche punto in cui non sono stato sufficientemente chiaro ti prego di lasciarmi un commento qui sotto in modo che possa aiutarti a risolvere i tuoi dubbi.