PHP: Primi passi

Come iniziare con PHP su Stackhero

👋 Benvenuti nella documentazione di Stackhero!

Stackhero offre una soluzione PHP cloud pronta all'uso che fornisce una serie di vantaggi, tra cui:

Distribuisci la tua applicazione in pochi secondi con un semplice git push.

Usa il tuo nome di dominio e beneficia della configurazione automatica dei certificati HTTPS per una sicurezza migliorata.

Goditi la tranquillità con backup automatici, aggiornamenti con un clic, e una tariffazione semplice, trasparente e prevedibile.

Ottieni prestazioni ottimali e una sicurezza robusta grazie a una VM privata e dedicata.

Risparmia tempo e semplificati la vita: ci vogliono solo 5 minuti per provare la soluzione di PHP cloud hosting di Stackhero!

Mettere online la vostra applicazione PHP su Stackhero è semplice e potente. In pochi passaggi, il vostro progetto sarà online e pronto all'uso. Questa guida vi accompagnerà passo dopo passo nella creazione, configurazione e distribuzione del vostro servizio PHP in modo chiaro e guidato.

Avviare un servizio PHP

Per iniziare, potete creare un servizio PHP su Stackhero direttamente dalla dashboard. L'interfaccia è progettata per rendere questa operazione rapida e intuitiva.

Prerequisiti

Prima di iniziare, assicuratevi di avere a disposizione i seguenti strumenti:

Git. Potete scaricarlo da https://git-scm.com/downloads.
Windows Terminal (opzionale per utenti Windows). Questo terminale offre un'esperienza migliorata. È disponibile tramite Microsoft Store.

Configurare il servizio

La configurazione principale richiesta è la vostra chiave pubblica SSH. Potete recuperare la chiave pubblica eseguendo uno dei seguenti comandi:

cat ~/.ssh/id_rsa.pub

oppure

cat ~/.ssh/id_ed25519.pub

Se non avete ancora una coppia di chiavi SSH, potete generarne una con ssh-keygen su Linux e macOS oppure con ssh-keygen.exe su Windows.

Una volta ottenuta la chiave pubblica, accedete alla dashboard di Stackhero, selezionate il vostro servizio PHP, andate nella pagina di configurazione e incollate la chiave nel campo dedicato.

Tip: Se desiderate impostare la vostra chiave pubblica SSH per tutti i servizi futuri, potete farlo a livello globale. Basta cliccare sulla vostra immagine del profilo in alto a destra nella dashboard, andare su "Il tuo profilo" e incollare lì la chiave pubblica SSH.

Clonare l'esempio

Per facilitarvi l'avvio, abbiamo preparato un'applicazione PHP di esempio. Potete clonare il repository con:

git clone https://github.com/stackhero-io/phpGettingStarted.git stackhero-php-getting-started
cd stackhero-php-getting-started

Configurare il repository remoto

Stackhero semplifica il deployment della vostra applicazione tramite Git. Copiate il comando git remote fornito nella prima pagina del vostro servizio PHP nella dashboard. Sarà simile a questo:

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Deploy del codice PHP

Ora siete pronti a distribuire la vostra applicazione. Potete inviare il codice con:

git push stackhero main

Al primo push, vi verrà chiesto di accettare l'impronta della chiave. Digitate semplicemente "yes" quando richiesto. Dopo pochi istanti, la vostra applicazione sarà online. Potete verificarne lo stato all'URL fornito nella dashboard di Stackhero (di solito https://<XXXXXX>.stackhero-network.com).

Per aggiornare la vostra applicazione, modificate semplicemente il file www/index.php (o qualsiasi altro file necessario), quindi ridistribuite le modifiche con:

git add -A .
git commit -m "Update www/index.php"
git push stackhero main

Deploy di un'applicazione esistente

Se avete già un'applicazione PHP che desiderate distribuire, dovete solo aggiungere il repository remoto al vostro progetto (vedi Configurare il repository remoto). Poi potete inviare le modifiche con:

git push stackhero main

Per impostazione predefinita, Stackhero cerca il vostro codice PHP e i file statici nella cartella www. Ad esempio, quando qualcuno visita yourdomain.com/myphoto.jpg, il file verrà servito da www/myphoto.jpg. Se la vostra applicazione utilizza una directory pubblica diversa, potete aggiornare questa impostazione nella configurazione del servizio PHP.

Gestire l'errore "failed to push some refs to '[...]'"

Se durante il deployment riscontrate un errore come questo:

error: failed to push some refs to '[...]'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Questo messaggio indica che il repository Git remoto contiene modifiche che non sono presenti nella vostra copia locale. Se siete sicuri di voler sovrascrivere il repository remoto con la vostra versione locale, potete forzare il push con:

git push -f stackhero main

Gestire l'errore "src refspec main does not match any"

Se visualizzate questo errore:

error: src refspec main does not match any
error: failed to push some refs to 'ssh://<XXXXXX>.stackhero-network.com:222/project.git'

Questo di solito significa che il branch main non esiste localmente. In tal caso, potete inviare il branch master invece:

git push stackhero master

Gestire l'errore "Everything up-to-date" durante il push

Se Git mostra Everything up-to-date e non vedete le vostre modifiche distribuite, probabilmente avete dimenticato di effettuare il commit delle modifiche. Potete risolvere eseguendo:

git add -A .
git commit -m "Il vostro messaggio di commit"
git push stackhero main

Se non avete modificato il codice ma volete comunque forzare un deployment, potete usare un commit vuoto:

git commit --allow-empty -m "Force update"
git push stackhero main

Deploy di un branch diverso da main

Se desiderate distribuire un branch diverso (ad esempio, production), potete usare:

git push stackhero production:main

Deploy di un tag

Per distribuire un tag specifico (ad esempio v1.0), eseguite:

git push stackhero 'v1.0^{}:main'

Il ^{} garantisce che il commit associato al tag venga inviato correttamente.

Rollback o deploy di uno specifico commit

Se avete bisogno di distribuire uno specifico commit, prima recuperate il suo hash con git log. Poi potete forzare il push di quel commit con:

git push -f stackhero <HASH>:main

Deploy su più ambienti

È comune avere servizi separati per diversi ambienti, come produzione e staging. Potete gestire questa esigenza rinominando e aggiungendo repository remoti.

Per rinominare il vostro attuale remote da stackhero a stackhero-staging, eseguite:

git remote rename stackhero stackhero-staging

Successivamente, potete creare un nuovo servizio PHP per la produzione tramite la dashboard e aggiungerlo con:

git remote add stackhero-production ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Ora potete distribuire su entrambi gli ambienti con:

git push stackhero-production main

oppure

git push stackhero-staging main

Salvare la password della chiave privata SSH nel portachiavi di macOS

Se utilizzate macOS e vi viene chiesta la password della chiave SSH ogni volta che inviate il codice, non è necessario rimuovere la password dalla chiave SSH. Potete invece memorizzare la password in modo sicuro nel portachiavi di macOS. Basta eseguire:

/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_rsa

Dopo questa operazione, macOS non vi chiederà più la password della chiave quando inviate il codice.

Gestire i secrets

Per gli ambienti di produzione e staging, è fondamentale conservare in modo sicuro i dati sensibili come token e password. Invece di inserire i secrets direttamente nel repository, è preferibile utilizzare variabili d'ambiente. Potete aggiungere queste variabili dalla dashboard di Stackhero e poi accedervi nel vostro codice. Ad esempio, se create una variabile d'ambiente chiamata mySecret, potete recuperarla in PHP così:

getenv("mySecret")

Gestire le dipendenze PHP

Quando inviate il vostro codice, gli script di deployment di Stackhero leggeranno il file composer.json e installeranno automaticamente tutte le dipendenze specificate tramite Composer.

Archiviare file

Se la vostra applicazione deve archiviare file (ad esempio foto caricate dagli utenti), spesso è consigliabile utilizzare una soluzione di object storage. Questo approccio facilita la condivisione dei file tra più servizi e mantiene separati i file caricati dal vostro codice. Potreste valutare MinIO per una soluzione veloce, affidabile e compatibile S3.

Se preferite utilizzare lo storage locale, potete sfruttare lo storage persistente incluso con la vostra istanza PHP. Questo storage è disponibile nel percorso /persistent/storage/.

Ad esempio, per salvare un file caricato, potete usare la funzione move_uploaded_file in questo modo:

move_uploaded_file($_FILES['image']['tmp_name'], '/persistent/storage/image.jpg');

Per maggiori informazioni sul caricamento dei file in PHP, consultate la documentazione ufficiale: https://www.php.net/manual/en/features.file-upload.php.

ATTENZIONE: Conservate sempre i dati all'interno della cartella /persistent/storage/.

Se la vostra istanza viene riavviata o se inviate modifiche al codice, tutti i dati archiviati al di fuori dello storage persistente potrebbero andare persi.