Creare e pubblicare un package Laravel in 5 step

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.

aggiunta a packagist

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.

La bolla dei 25 amici di facebook

In questi giorni nel mio news feed di facebook ho visto condividere  questa notizia diverse volte:

Notando che non vedo più i post di tanti conoscenti ed amici, anch’io ho deciso di tentare di bypassare la modifica dell’algoritmo di Facebook, che ha creato questa anomalia.

Ecco come evitare di sentire gli stessi 25 amici di fb e nessun altro.

La sezione notizie mostra di recente solo i post delle stesse poche persone, circa 25, più volte lo stesso, su scelta di facebook

Il nuovo algoritmo evidenzia solo le persone che leggono i reciproci post.

Si tratta di una decisione arbitraria,unilaterale, dovuta a mera convenienza gestionale, perchè risparmia enorme sovraccarico ai server dell’attività Facebook.

Perciò, volendo invece mantenere la propria libertà di scelta, scambiamoci un favore:

chi sta leggendo questo messaggio lasci un commento veloce, un “ciao”, un adesivo, qualsiasi cosa, che sarà visualizzata nella sezione notizie del destinatario.

Replicando questa azione, tutto tornerà come prima, non lasciando a Facebook la libertà di scegliere i rispettivi amici ( assurdo).

I social media aiutano la comunicazione, non devono limitare la libertà degli individui, qualsiasi sia stata la ragione del loro iniziale contatto.

( Perciò, copie incolla questo testo sulla tua bacheca in modo da poter godere di più interazione con tutti i tuoi contatti e bypassare il sistema.

Grazie per la dritta da chi ha già copiato e incollato quanto sopra.

Premi il dito’ ovunque in questo post e compare “Copia”. Clicca su “Copia”, poi accedi alla tua pagina, avvia un nuovo post e metti il dito ovunque nel campo bianco. Compare “incolla”, clicca e voilà, hai appena copiato.)

La cosa interessante di questo post è che parte da dei presupposti veri per generare una notizia sensazionalistica ma di fatto sbagliata.

Facebook non ha alcun interesse a scegliere i miei amici per limitare con lo scopo di limitare le mia libertà ma vuole  semplicemente massimizzare il tempo che posso sulla sua piattaforma così da farmi vedere più pubblicità.

Da questa esigenza è nato il famigerato algoritmo di facebook (ma c’è anche su instagram e twitter) con lo scopo di farmi vedere i contenuti che secondo lui sono più interessanti per me. Figurati se Facebook ha problemi di gestione dei server.

Questo algoritmo è molto complesso ed è tenuto segreto ma a grandi linee si può dire che segue due regole principali:

  • gli interessi: ad esempio se ho un interesse per la cucina è inutile che l’algoritmo mi mostri i post degli amici che condividono videogiochi. Passerei oltre questi post senza pensarci due volte.
  • l’interazione: se lascio un commento o un like ad un post di un amico è molto probabile che io interagirà di nuovo con lui. Di conseguenza facebook proverà

In virtù del punto 2 è vero che se un amico lascia un commento al post in questione io vedrò più post suoi. Ma se poi io e questo amico non abbiamo interessi in comune nel giro di poco tempo facebook se ne accorgerà e non mi mostrerò più post di questa persona.

Come installare Docker e Docker Compose su Ubuntu 18.04

Ubuntu + Docker

In questo breve post ti voglio spiegare come installare e configurare Docker e Docker Compose su Ubuntu 18.04 Bionic Beaver.

Installazione di Docker

Il primo passo da compiere è assicurarsi di aver installato tutte le dipendenze necessarie lanciando da terminale:

sudo apt-get install apt-transport-https ca-certificates curl software-properties-common

Dopodichè devi importare la chiave GPG del repository di Docker tramite il comando:

 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

A questo punto puoi aggiungere il repository di Docker:

sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

Infine se tutto ha funzionato correttamente sarà sufficiente installare il pacchetto di docker tramite i comandi:

sudo apt update
sudo apt install docker-ce

(opzionale) Eseguire Docker senza sudo

Di default per poter eseguire docker è necessario avere i privilegi di root preponendo ad ogni comando sudo. Infatti se hai provato ad eseguire docker senza i giusti privilegi avrai sicuramente ricevuto questo messaggio d’errore:

ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?
If it's at a non-standard location, specify the URL with the DOCKER_HOST environment variable.

Per poter aggirare questa limitazione ti basta aggiungere il tuo utente al gruppo docker tramite questo comando: 

sudo usermod -aG docker ${USER}

NOTA: Per rendere effettiva la modifica dovrai prima eseguire il log-out dalla tua sessione.

Per verificare che il tuo account sia stato effettivamente aggiunto al gruppo docker ti basta digitare:

id -nG
L’utente lorenzo appartiene al gruppo docker

Installazione di Docker Compose

La prima cosa da fare è scaricare l’ultima versione di docker-compose tramite il comando:

sudo curl -L https://github.com/docker/compose/releases/download/1.24.1/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose

NOTA: Questo comando installa docker-compose 1.24.1 che è l’ultima release al momento in cui scrivo, quando usciranno nuove versioni per installarle ti basterà visitare questa pagina e sostituire il numero di versione con quello più recente.

Ora devi fornire i permessi di esecuzione allo script di docker-compose

sudo chmod +x /usr/local/bin/docker-compose

Per verificare che l’installazione sia andata a buon fine ti basterà eseguire questo comando:

docker-compose --version
Docker-compose installato correttamente (al momento in cui scrivo la versione più recente è la 1.21.1)

Conclusioni

Con questi pochi passi potrai installare Docker e Docker Compose sull’ultima versione LTS di Ubuntu ed essere pronto per esplorare le infinite potenzialità di Docker.
Se questo post ti è stato utile puoi farmelo sapere con un commento qui sotto oppure scrivendomi direttamente a t.me/lorenzomillucci. Inoltre ti invito ad iscriverti al mio canale Telegram per non perderti nemmeno un post.

Hello world!

Benvenuti sul mio nuovo blog!

Il vecchio blog è ancora raggiungibile a questo url:  https://didatticamillu.blogspot.com

Gli inizi del vecchio blog

Per commemorare l’abbandono di questo blog voglio ricapitolare brevemente le origini di questo blog.
Questo blog infatti nacque nell’ormai lontano 2008. All’epoca io ero un giovane studente del terzo anno dell’istituto tecnico Alessandro Volta di Perugia felicissimo che nel corso di quell’anno scolastico avrei iniziato a studiare i linguaggi di programmazione. Non potete immaginare quanto attendessi quell’anno scolastico, in pratica avevo scelto le scuole superiori e in particolare il corso di elettronica solo per poter arrivare il 3° anno a studiare la programmazione.
Alla prima lezione del corso ero al settimo cielo. E quando il prof. Natalizi annunciò che in quell’anno anziché utilizzare un comune quaderno per gli appunti, avremmo dovuto utilizzare il blog per svolgere gli esercizi e condividerli con lui accolsi con entusiasmo la cosa. Così il 26 Settembre 2008 pubblicai il primo post di questo blog.

Da allora questo blog ne ha fatta di strada e oggi conta più di 75000 pagine visualizzate da visitatori provenienti da tutto il mondo.

Statistiche maggio 2010 - agosto 2018
Statistiche maggio 2010 – agosto 2018