PHP: Primeiros passos

Como começar com PHP na Stackhero

👋 Bem-vindo à documentação do Stackhero!

Stackhero oferece uma solução PHP cloud pronta a usar que proporciona uma série de benefícios, incluindo:

Implemente a sua aplicação em segundos com um simples git push.

Utilize o seu próprio nome de domínio e beneficie da configuração automática de certificados HTTPS para uma segurança reforçada.

Desfrute de tranquilidade com backups automáticos, atualizações com um clique, e uma tarifação simples, transparente e previsível.

Obtenha performance ótima e segurança robusta graças a uma VM privada e dedicada.

Poupe tempo e simplifique a sua vida: só leva 5 minutos para experimentar a solução de PHP cloud hosting do Stackhero!

Colocar a sua aplicação PHP online na Stackhero é simples e poderoso. Em apenas alguns passos, terá o seu projeto disponível e pronto a funcionar. Este guia irá acompanhá-lo na criação, configuração e deployment do seu serviço PHP de forma clara e passo a passo.

Iniciar um serviço PHP

Para começar, pode criar um serviço PHP na Stackhero diretamente a partir do dashboard. A interface foi desenhada para tornar este processo rápido e intuitivo.

Pré-requisitos

Antes de começar, certifique-se de que tem as seguintes ferramentas instaladas:

Git. Pode descarregá-lo em https://git-scm.com/downloads.
Windows Terminal (opcional para utilizadores Windows). Este terminal proporciona uma experiência melhorada e está disponível na Microsoft Store.

Configurar o seu serviço

A configuração principal de que irá precisar é a sua chave pública SSH. Pode obter a sua chave pública executando um dos seguintes comandos:

cat ~/.ssh/id_rsa.pub

cat ~/.ssh/id_ed25519.pub

Se ainda não tiver um par de chaves SSH, pode gerar um utilizando ssh-keygen em Linux e macOS ou ssh-keygen.exe em Windows.

Depois de obter a sua chave pública, aceda ao dashboard da Stackhero, selecione o seu serviço PHP, navegue até à página de configuração e cole a sua chave no campo indicado.

Tip: Se pretender definir a sua chave pública SSH para todos os serviços futuros, pode fazê-lo de forma global. Basta clicar na sua foto de perfil no canto superior direito do dashboard, ir a "O seu perfil" e colar aí a sua chave pública SSH.

Clonar o exemplo

Para facilitar o início, preparámos uma aplicação PHP de exemplo. Pode clonar o repositório com:

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

Configurar o repositório remoto

A Stackhero facilita o deployment da sua aplicação através do Git. Copie o comando git remote fornecido na primeira página do seu serviço PHP no dashboard. O comando será semelhante a:

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

Fazer deploy do seu código PHP

Agora está pronto para fazer o deployment da sua aplicação. Pode enviar o seu código com:

git push stackhero main

No primeiro push, ser-lhe-á pedido para aceitar a impressão digital da chave. Basta escrever "yes" quando solicitado. Após alguns instantes, a sua aplicação ficará online. Pode verificar o estado na URL indicada no seu dashboard Stackhero (normalmente https://<XXXXXX>.stackhero-network.com).

Para atualizar a sua aplicação, basta modificar o ficheiro www/index.php (ou qualquer outro ficheiro necessário) e voltar a fazer o deployment das alterações com:

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

Fazer deploy de uma aplicação existente

Se já tem uma aplicação PHP que pretende colocar online, só precisa de adicionar o repositório remoto ao seu projeto (ver Configurar o repositório remoto). Depois, pode enviar as suas alterações com:

git push stackhero main

Por predefinição, a Stackhero procura o seu código PHP e ficheiros estáticos na pasta www. Por exemplo, quando alguém acede a yourdomain.com/myphoto.jpg, o ficheiro será servido a partir de www/myphoto.jpg. Se a sua aplicação utilizar uma pasta pública diferente, pode alterar esta configuração no painel do seu serviço PHP.

Resolver o erro "failed to push some refs to '[...]'"

Se encontrar um erro como este durante o deployment:

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.

Esta mensagem indica que o repositório Git remoto tem alterações que não existem na sua cópia local. Se tiver a certeza de que pretende sobrescrever o remoto com a sua versão local, pode forçar o envio com:

git push -f stackhero main

Resolver o erro "src refspec main does not match any"

Se vir este erro:

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

Isto normalmente significa que a branch main não existe localmente. Nesse caso, pode querer enviar a branch master em alternativa:

git push stackhero master

Resolver o erro "Everything up-to-date" ao fazer push

Se o Git indicar Everything up-to-date e não vir as suas alterações online, provavelmente esqueceu-se de fazer commit das alterações. Pode resolver isto executando:

git add -A .
git commit -m "A sua mensagem de commit"
git push stackhero main

Se não alterou nenhum código mas pretende, ainda assim, forçar um deployment, pode usar um commit vazio:

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

Fazer deploy de uma branch diferente de main

Se quiser fazer deploy de outra branch (por exemplo, production), pode usar:

git push stackhero production:main

Fazer deploy de uma tag

Para fazer deploy de uma tag específica (como v1.0), execute:

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

O ^{} garante que o commit associado à tag é enviado corretamente.

Reverter ou fazer deploy de um commit específico

Se precisar de fazer deploy de um commit específico, primeiro encontre o seu hash com git log. Depois, pode forçar o envio desse commit com:

git push -f stackhero <HASH>:main

Fazer deploy para múltiplos ambientes

É comum ter serviços separados para diferentes ambientes, como produção e staging. Pode gerir isto renomeando e adicionando repositórios remotos.

Para renomear o seu remoto atual de stackhero para stackhero-staging, execute:

git remote rename stackhero stackhero-staging

De seguida, crie um novo serviço PHP para produção através do dashboard e adicione-o com:

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

Agora pode fazer deploy para qualquer ambiente com:

git push stackhero-production main

git push stackhero-staging main

Guardar a password da sua chave privada SSH no keychain do macOS

Se está a utilizar macOS e lhe é pedido o password da sua chave SSH sempre que faz push do código, não precisa de remover a password da sua chave. Em vez disso, pode guardar a password de forma segura no keychain do macOS. Basta executar:

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

Depois disto, o macOS deixará de pedir a password da chave ao enviar o seu código.

Gerir secrets

Para ambientes de produção e staging, é fundamental guardar dados sensíveis, como tokens e passwords, de forma segura. Em vez de incluir secrets diretamente no repositório, utilize variáveis de ambiente. Pode adicionar estas variáveis no dashboard da Stackhero e acedê-las no seu código. Por exemplo, se criar uma variável de ambiente chamada mySecret, pode obtê-la em PHP assim:

getenv("mySecret")

Gerir dependências PHP

Quando faz push do seu código, os scripts de deployment da Stackhero vão ler o seu ficheiro composer.json e instalar automaticamente as dependências especificadas através do Composer.

Armazenar ficheiros

Se a sua aplicação precisar de armazenar ficheiros (como fotos enviadas por utilizadores), é recomendável utilizar uma solução de object storage. Esta abordagem facilita a partilha de ficheiros entre vários serviços e mantém os ficheiros enviados separados do seu código. Pode, por exemplo, explorar o MinIO para uma solução rápida, fiável e compatível com S3.

Se preferir utilizar armazenamento local, pode aproveitar o armazenamento persistente incluído na sua instância PHP. Este armazenamento está disponível em /persistent/storage/.

Por exemplo, para guardar um ficheiro enviado, pode usar a função move_uploaded_file desta forma:

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

Para mais informações sobre uploads de ficheiros em PHP, consulte a documentação oficial: https://www.php.net/manual/en/features.file-upload.php.

ATENÇÃO: Guarde sempre os dados dentro da pasta /persistent/storage/.

Se a sua instância reiniciar ou se fizer push de alterações de código, quaisquer dados guardados fora do armazenamento persistente podem ser perdidos.