PHP: Getting started

How to get started with PHP on Stackhero

👋 Welcome to the Stackhero documentation!

Stackhero offers a ready-to-use PHP cloud solution that provides a host of benefits, including:

  • Deploy your application in seconds with a simple git push.
  • Use your own domain name and benefit from the automatic configuration of HTTPS certificates for enhanced security.
  • Enjoy peace of mind with automatic backups, one-click updates, and straightforward, transparent, and predictable pricing.
  • Get optimal performance and robust security thanks to a private and dedicated VM.

Save time and simplify your life: it only takes 5 minutes to try Stackhero's PHP cloud hosting solution!

Deploying PHP on Stackhero is simple and powerful. In just a few steps you can have your application running online. This guide will walk you through creating, configuring, and deploying your PHP service in a friendly, step-by-step manner.

Start a PHP service

Begin by creating a PHP service on Stackhero via the dashboard. The intuitive interface makes the process quick and efficient.

Prerequisites

Before you begin, please ensure you have the following tools installed:

  1. Git. You can download it from https://git-scm.com/downloads.
  2. Windows users might find that Windows Terminal offers an enhanced experience. You can get it from the Microsoft Store.

Configure your service

The only setting you need to adjust in your service configuration is the SSH public key. You can retrieve your public key using one of the following commands:

cat ~/.ssh/id_rsa.pub

or

cat ~/.ssh/id_ed25519.pub

If you do not have a key pair yet, you can generate one using ssh-keygen on Linux and macOS or ssh-keygen.exe on Windows.

After obtaining your public key, navigate to the Stackhero dashboard, select your PHP service, go to its configuration page, and paste your key into the appropriate field.

Tip: You can define your SSH public key globally so that future services automatically include it. To do this, click your profile picture in the top right corner of the dashboard, select 'Your profile', and paste your SSH public key.

Clone the example

A simple PHP application has been prepared to demonstrate how it works on Stackhero. To get started, clone the repository with the following commands:

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

Configure the remote repository server

Stackhero simplifies deploying your application using Git. Copy the value provided by the git remote command from the first page of your PHP service in the dashboard. The command will look similar to this:

git remote add stackhero ssh://stackhero@XXXXX.stackhero-network.com:222/project.git

Deploy your PHP code

It is now time to deploy your application. Push your code with the following command:

git push stackhero main

The first time you push, you will be prompted to accept the key fingerprint. Type "yes" when prompted. After a short wait, your application should be online. You can check its status by visiting the URL provided on the Stackhero dashboard (typically something like https://XXXXX.stackhero-network.com).

To update your application, modify the www/index.php file as needed and redeploy your changes with:

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

Deploy an existing application

If you have an existing PHP application, you can easily deploy it by adding the remote repository to your project (see Configure the remote repository server). Then, push your changes using:

git push stackhero main

By default, the public directory is set to "www". This is where your PHP code is executed (including index.php) and where your static files are stored. For example, visiting yourdomain.com/myphoto.jpg retrieves the file from www/myphoto.jpg. You can update this directory in your PHP service configuration if needed.

Handle error "failed to push some refs to '[...]'"

If you encounter an error like the following when deploying:

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.

This error indicates that the remote Git repository contains changes that are not present in your local repository. To override these changes safely, you can force the push with:

git push -f stackhero main

Handle error "src refspec main does not match any"

If you see this error:

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

It means the branch main does not exist locally. In this case, try pushing the master branch instead:

git push stackhero master

Handle error "Everything up-to-date" when pushing

If Git responds with Everything up-to-date and your changes are not deployed, you might have forgotten to commit your changes. To resolve this, run:

git add -A .
git commit -m "Your commit message"
git push stackhero main

If you have not changed any code but still want to trigger a deployment, you can force an update with an empty commit:

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

Deploy a branch other than main

If you want to deploy a branch other than main (for example, a branch named "production"), you can use the following command:

git push stackhero production:main

Deploy a tag

To deploy a specific tag (for example, tag "v1.0"), use:

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

The ^{} syntax ensures that the commit associated with the tag is pushed correctly.

Roll back or deploy a specific commit

If you need to deploy a specific commit, first obtain its hash using git log. Then, force push that commit using:

git push -f stackhero <HASH>:main

Deploy to multiple environments

Often you may have separate services for different environments, such as production and staging. You can manage these by renaming and adding remote repositories.

To rename your current remote from stackhero to stackhero-staging, use:

git remote rename stackhero stackhero-staging

Next, create a new PHP service for production via the dashboard and add it using:

git remote add stackhero-production ssh://stackhero@XXXXX.stackhero-network.com:222/project.git

You can now deploy to the appropriate environment using either:

git push stackhero-production main

or

git push stackhero-staging main

Save your SSH private key password in macOS's keychain

On macOS, you might be prompted for your key password every time you push your code. Instead of removing the password from your SSH key, you can store your key password in the macOS keychain. This approach maintains security while saving time. Run the following command to add your key to the keychain:

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

Once set up, macOS will no longer ask for your key password when pushing your code.

Handle secrets

For production and staging environments it is essential to store sensitive data, such as tokens and passwords, securely. Instead of hardcoding secrets into your repository, consider using environment variables. You can add these variables on the Stackhero dashboard and access them in your code. For example, if you create an environment variable named "mySecret", you can retrieve its value in PHP using:

getenv("mySecret")

Handle PHP dependencies

When you push your code, the deployment scripts read your composer.json file and automatically install all specified dependencies via Composer.

Store files

If your application needs to store files (for example, user photos), it is advisable to use an object storage solution. This approach not only facilitates file sharing between multiple services but also separates your uploaded files from your code. We recommend exploring MinIO for a fast, reliable, and S3-compatible solution.

Alternatively, if you prefer local file storage, you can use the persistent storage provided with your PHP instance. This storage is located in the /persistent/storage/ directory.

For example, to store an uploaded file, you might use the move_uploaded_file function as follows:

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

For more details about file uploads, refer to the official PHP documentation: https://www.php.net/manual/en/features.file-upload.php.

CAUTION: Never store data outside the /persistent/storage/ folder!

If your instance reboots or if you push code changes, any data stored outside the persistent storage may be lost!

Other articles for PHP