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 up and running on Stackhero is both simple and powerful. In just a few steps, you will have your project online and ready to go. This guide will walk you through creating, configuring, and deploying your PHP service in a friendly, step-by-step way.

Start a PHP service

To begin, you can create a PHP service on Stackhero right from the dashboard. The interface is designed to make this process quick and straightforward.

Prerequisites

Before getting started, make sure you have the following tools set up:

Git. You can download it from https://git-scm.com/downloads.
Windows Terminal (optional for Windows users). This terminal can provide an enhanced experience. It is available via the Microsoft Store.

Configure your service

The primary configuration you will need is your SSH public key. You can retrieve your public key by running one of these commands:

cat ~/.ssh/id_rsa.pub

cat ~/.ssh/id_ed25519.pub

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

Once you have your public key, head over to the Stackhero dashboard, select your PHP service, navigate to the configuration page, and paste your key into the designated field.

Tip: If you would like to set your SSH public key for all future services, you can do so globally. Just 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 something 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. You can 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 asked. After a short wait, your application should 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), and 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 would like to deploy, you just need to add the remote repository to your project (see Configure the remote repository server). Then, you can push your changes using:

git push stackhero main

By default, Stackhero looks for your PHP code and static files in the www directory. For instance, when someone visits yourdomain.com/myphoto.jpg, the file will be 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 run into 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 has changes that are not present in your local copy. If you are sure you want to override 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 that the main branch does not exist locally. In that case, you might want to push the master branch instead:

git push stackhero master

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

If Git says Everything up-to-date and you do not see your changes deployed, it is likely you forgot to commit your changes. You can resolve this by running:

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), you can use:

git push stackhero production:main

Deploy a tag

To deploy a particular tag (like v1.0), you can run:

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

The ^{} ensures the commit related to the tag is pushed properly.

Roll back or deploy a specific commit

If you ever need to deploy a specific commit, first find its hash using git log. Then, you can 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, just run:

git remote rename stackhero stackhero-staging

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

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

Now, you can deploy to either environment with:

git push stackhero-production main

git push stackhero-staging main

Save your SSH private key password in macOS's keychain

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

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

After this, macOS will not ask for your key password when pushing your code.

Handle secrets

For production and staging environments, it is important to store sensitive data, like tokens and passwords, securely. Rather than hardcoding secrets in your repository, you might want to use environment variables. You can add these variables in the Stackhero dashboard, and then access them in your code. For example, if you create an environment variable called mySecret, you can retrieve 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 you specify using Composer.

Store files

If your application needs to store files (such as user-uploaded photos), it is often a good idea 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 might want to explore MinIO for a fast, reliable, and S3-compatible solution.

If you would rather use local file 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, you can 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, you can check the official documentation: https://www.php.net/manual/en/features.file-upload.php.

CAUTION: Always store data inside the /persistent/storage/ folder.

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