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!

Getting your PHP application online with Stackhero is both simple and powerful. In just a few steps, your project will be up and running. This guide will walk you through creating, configuring, and deploying your PHP service in a clear, step-by-step manner.

Start a PHP service

To get started, you can create a PHP service on Stackhero directly from the dashboard. The interface is designed to make this process quick and intuitive.

Prerequisites

Before you begin, make sure you have the following tools:

Git. Download it from https://git-scm.com/downloads.
Windows Terminal (optional for Windows users). This terminal provides an enhanced experience and is available from the Microsoft Store.

Configure your service

The main configuration required is your SSH public key. You can retrieve it by running one of the following commands:

cat ~/.ssh/id_rsa.pub

cat ~/.ssh/id_ed25519.pub

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

Once you have your public key, go to the Stackhero dashboard, select your PHP service, access the configuration page, and paste your key into the appropriate field.

Tip: If you want to set your SSH public key for all future services, you can do this globally. Simply click your profile picture in the top right corner of the dashboard, go to "Your profile", and paste your SSH public key there.

Clone the example

To help you get started, we have prepared a sample PHP application. You can clone the repository with:

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

Configure the remote repository server

Stackhero makes it easy to deploy your application using Git. Copy the git remote command provided on the first page of your PHP service in the dashboard. It will look like this:

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

Deploy your PHP code

You are now ready to deploy your application. Push your code with:

git push stackhero main

During your first push, you will be prompted to accept the key fingerprint. Simply type "yes" when prompted. After a short moment, your application will be online. You can check its status at the URL provided in your Stackhero dashboard (usually https://<XXXXXX>.stackhero-network.com).

To update your application, just modify the www/index.php file (or any other file you need), then redeploy your changes with:

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

Deploy an existing application

If you already have a PHP application you want to deploy, simply add the remote repository to your project (see Configure the remote repository server). Then, push your changes with:

git push stackhero main

By default, Stackhero looks for your PHP code and static files in the www directory. For example, when someone visits yourdomain.com/myphoto.jpg, the file is served from www/myphoto.jpg. If your application uses a different public directory, you can update this setting in your PHP service configuration.

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

If you encounter an error like this during 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.

This message means the remote Git repository contains changes that are not present in your local copy. If you want to overwrite the remote with your local version, 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'

This usually means the main branch does not exist locally. In that case, you can push the master branch instead:

git push stackhero master

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

If Git displays Everything up-to-date and you do not see your changes deployed, you likely forgot to commit your changes. To fix 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 use 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 different branch (for example, production), use:

git push stackhero production:main

Deploy a tag

To deploy a specific tag (such as v1.0), run:

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

The ^{} ensures the commit associated with the tag is properly pushed.

Roll back or deploy a specific commit

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

git push -f stackhero <HASH>:main

Deploy to multiple environments

It is common to have separate services for different environments, such as production and staging. You can manage this by renaming and adding remote repositories.

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

git remote rename stackhero stackhero-staging

Next, create a new PHP service for production via the dashboard, then add it with:

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

You can now deploy to the environment of your choice with:

git push stackhero-production main

git push stackhero-staging main

Save your SSH private key password in the macOS keychain

If you are on macOS and are prompted for your SSH key password each time you push, you do not need to remove the password from your SSH key. You can securely store this password in the macOS keychain. Simply run:

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

After this, macOS will no longer ask for your key password when you push your code.

Handle secrets

For production and staging environments, it is essential to store sensitive data, such as tokens and passwords, securely. Rather than hardcoding secrets in your repository, it is best to use environment variables. You can add these variables in the Stackhero dashboard, and then retrieve them in your code. For example, if you create an environment variable called mySecret, you can access it in PHP like this:

getenv("mySecret")

Handle PHP dependencies

When you push your code, Stackhero's deployment scripts will read your composer.json file and automatically install any dependencies specified via Composer.

Store files

If your application needs to store files (such as user-uploaded photos), it is often recommended to use an object storage solution. This approach makes it easier to share files between multiple services and keeps your uploaded files separate from your code. You may want to explore MinIO for a fast, reliable, and S3-compatible solution.

If you prefer to use local storage, you can take advantage of the persistent storage included with your PHP instance. This storage is available at /persistent/storage/.

For example, to save an uploaded file, use the move_uploaded_file function like this:

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

For more information about file uploads in PHP, see the official documentation: https://www.php.net/manual/en/features.file-upload.php.

CAUTION: Always store your data in the /persistent/storage/ folder.

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