Backend guidelines

Project installation

After all the preparations, we are finally ready to set up our project on our local machine.

Cloning the project from Bitbucket

Our company uses Bitbucket to house its projects and we use Git to communicate with bitbucket and manage the version control of our code.

The first thin we should do is clone the remote repository on our local machine.
Create the directory where your project will be on your machine.

WARNING

For Linux based systems, you should put the project under a directory named exactly as your virtual host in order to make the virtual host creation easier. Also, you must create this directory under the public directory of your system (the one which belongs to the www-data group).
So, if you are cloning a project named "Maxshop", create a directory named site.maxshop.test.

Open a terminal, and navigate to the newly created directory, for example:

cd C:\wamp\www\guidelines\erdsoft-guidelines

Clone the remote repository into the local directory by running:

git clone https://your-username@bitbucket.org/erdsoft-team/repository_name.git .

WARNING

The . at the end of the above command is not a typo. It tells git that you want to use the current directory and don't want to make a new directory under it.

Changing branches

A repository usually have more than one branch. A branch represents an independent line of development. Branches serve as an abstraction for the edit/stage/commit process. You can think of them as a way to request a brand new working directory, staging area, and project history. New commits are recorded in the history for the current branch, which results in a fork in the history of the project.

Our project usually have these branches right from the start:

• master: This one is the live/production version of the code and should never be modified directly.
• staging: This is our staging version of the code which is usually used to present new features to our clients. This branch should not be edited directly either.
• develop: This is the branch we use for the main development process of the code, and this is the branch we will usually commit our changes into.

After we clone a repository, we end up on the master branch by default, so we need to change to the develop branch (before we forget it).
First, lets fetch all the remote branches from the repository by running the following command:

git fetch -a

INFO

git fetch updates the remote tracking branches under .git/refs/remotes. It does not change anyting on your local codebase.

Now lets change our branch and also create a local branch for ourselves. You can change a branch by using the checkout command in git and you can make a new local branch from the remote branch by using the -b option.
So, to change to the develop branch, run this command:

git checkout -b develop

Now we got ourselves a nice little develop branch.
We can check all remote and local branches by running this command:

git branch -a

This should give us an output similar to this:

* develop
  feature/webshop
  master
  remotes/origin/HEAD -> origin/master
  remotes/origin/develop
  remotes/origin/master
  remotes/origin/staging

Where the * shows us our currently selected local branch.
All branches starting with remotes/origin/ are remote branches.

To make sure we are tracking the branch we want, we can also run this command:

git branch --set-upstream-to=remotes/origin/develop develop

INFO

This is probably more useful, if you already have a local branch and want to set up that local branch to track a remote branch, but I am a man of habit, so I always run this command even if I just cloned the project and changed to a new branch with git checkout -b branchname.

To check all our local branches and the tracking status of them, we can run this command:

git remote show origin

This will get us an output similar to this:

* remote origin
  Fetch URL: https://your-username@bitbucket.org/erdsoft-team/repository_name.git
  Push  URL: https://your-username@bitbucket.org/erdsoft-team/repository_name.git
  HEAD branch: master
  Remote branches:
    develop                             tracked
    master                              tracked
    staging                             tracked
  Local branches configured for 'git pull':
    develop         merges with remote develop
    master          merges with remote master
  Local refs configured for 'git push':
    develop pushes to develop (local out of date)
    master  pushes to master  (up to date)

We can see that our local master and develop branches are set up for git pull and git push with the respective remote branches, which is good.

We can also see that our local develop branch is "out of date", which is not so good.
In this case, we need to pull the latest version from the remote repository before we do anything else. We can do that by running this command:

git pull --rebase

INFO

Because we did not explicitly tell git pull the source branch and the destination branch, it will use the currently selected local branch as destination and the remote branch being tracked by the current local branch as the source branch.

As you can see, we do not simply pull the changes, but rather rebase our local code to update our local branch. This means, that if we have a conflict during our pull, git would mark all conflicting files and ask us to fix each conflict in them (more about this later).
Since we did not make any changes at all on our local files yet, you should not get any conflicts this time.

After the successful pull, if we run git remote show origin again, we should see something like this:

* remote origin
  Fetch URL: https://your-username@bitbucket.org/erdsoft-team/repository_name.git
  Push  URL: https://your-username@bitbucket.org/erdsoft-team/repository_name.git
  HEAD branch: master
  Remote branches:
    develop                             tracked
    master                              tracked
    staging                             tracked
  Local branches configured for 'git pull':
    develop         merges with remote develop
    master          merges with remote master
  Local refs configured for 'git push':
    develop pushes to develop (up to date)
    master  pushes to master  (up to date)

This means that our local version is up to date with the remote version of the code, which is what we wanted, so all is good.

Creating a virtual host

Creating a virtual host is essential for making your local development environment to be as close to the real thing as it can be. You should always setup your virtual host to use https for that same reason, because some services require you to use a secure domain even for testing.

INFO

If you use Laragon, you can do this whole process in a few clicks.

Before we dive into the specifics of this task, we will make a certificate which we will use to secure our domain.
The easiest way I found to do this is using mkcert, which is a zero config command line tool for making locally-trusted development certificates. So, before you continue reading, install mkcert on your system following the installation instructions here.

After a successful installation of mkcert, you can make a certificate for any domain, by running a command like this:

mkcert site.maxwerk.test "*.maxwerk.test" maxwerk.test localhost 127.0.0.1 ::1

This will give us a response similar to this:

Created a new certificate valid for the following names 📜
 - "site.maxwerk.test"
 - "*.maxwerk.test"
 - "maxwerk.test"
 - "localhost"
 - "127.0.0.1"
 - "::1"

Reminder: X.509 wildcards only go one level deep, so this won't match a.b.maxwerk.test ℹ️

The certificate is at "./site.maxwerk.test+5.pem" and the key at "./site.maxwerk.test+5-key.pem" ✅

WARNING

Make sure you do not generate the certificate in the directory of the repository you are working on. You do not want to push that up into the remote repository.

Make sure you remember where you created the certificate and key files, cause you will need them later.

With that out of the way, we can start creating our virtual host.

Windows

If your development environment does not support setting up virtual hosts in a few click, you can always add them manually by editing the httpd-vhosts.conf apache configuration file for virtual hosts.
This file is located under:

• XAMPP: C:\xampp\apache\conf\extra\httpd-vhosts.conf, if you installed XAMPP in C:\xampp\
• WampServer: C:\wamp\bin\apache\apache2.4.41\conf\httpd-vhosts.conf, if you installed WAMP in C:\wamp\ and the installed apache version is 2.4.41.

Keeping our example from the above certificate generation, we should add something like this in the config file:

<VirtualHost *:443>
    ServerName site.maxwerk.test
    ServerAlias site.maxwerk.test
    DocumentRoot "c:/wamp/www/maxwerk/site/public"
    <Directory "c:/wamp/www/maxwerk/site/public/">
        Options +Indexes +Includes +FollowSymLinks -MultiViews
        AllowOverride All
        Require local
    </Directory>
    AllowEncodedSlashes NoDecode
    SSLEngine on
    SSLCertificateFile "c:/wamp/bin/apache/apache2.4.41/conf/keys/site.maxwerk.test+5.pem"
    SSLCertificateKeyFile "c:/wamp/bin/apache/apache2.4.41/conf/keys/site.maxwerk.test+5-key.pem"
    SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
    Protocols h2 http/1.1
</VirtualHost>

Lets break this up a bit. The first 2 highlighted lines contain our domain name which will be site.maxwerk.test.

INFO

If you want to know the difference between ServerName and ServerAlias, feel free to read the official documentation about it here.

The next 2 highlighted rows define the public path of our site. In this example, we cloned our repository into c:/wamp/www/maxwerk/site/ and Laravel uses the public directory to bootstrap the site, so we need to point our virtual host to this directory, which gives us c:/wamp/www/maxwerk/site/public as our document root.

WARNING

Note that while we have a trailing slash in the value of the Directory, there is no trailing slash after the DocumentRoot. The official apache documentation states that the DocumentRoot should be specified without a trailing slash here.
Also, the quotes are not required for the Directory part, unless you have spaces in the defined path. We will just default to using quotes.

In the Options directive inside the Directory part, make sure you turn off the MultiViews option by setting a - before the name of the option.

The last highlighted block is all about enabling https.
For this, we need to turn the SSLEngine on and specify our SSLCertificateFile and SSLCertificateKeyFile (the ones we made with mkcert a little while ago). We decided to store our certificates and keys right in the apache conf directory in a key subdirectory.

INFO

The last 2 lines in the above example turns on the HTTP/2 protocol version for our site. For this to work, you will need Apache version 2.4.17 or above and TLS 1.2 or above (the latter comes with OpenSSL 1.0.1 or newer).

After you save the file, you will need to restart apache for the changes to take effect. For information about how to restart apache, consult the documentation of your chosen development environment.

WARNING

I feel the need to emphasize that you absolutely must restart apache to make your changes effective.

We also need to add our domain name into the hosts file in C:\Windows\System32\drivers\etc\hosts. In our example, we want to add something like this:

127.0.0.1	site.maxwerk.test
::1	site.maxwerk.test

This will tell our operating system to look for site.maxwerk.test on the 127.0.0.1 IP address.

WARNING

You need administrative rights to edit the hosts file, so make sure you run a text editor as administrator and open/save the file in that editor.

Ubuntu

You need to make a directory in the www directory of your system which includes the domain name of your choosing:

sudo mkdir -p /var/www/site.maxwerk.test/public_html

To avoid permission errors later on, make everything under the /var/www/site.maxwerk.test/ directory belong to the www-data group by running the following command:

sudo chown -R www-data: /var/www/site.maxwerk.test

This is the directory you should clone your project into ???.

Next, we will need to create the configuration file for our virtual host. Open a text editor as a sudo user, and create a .conf file named exactly as your domain name under the /etc/apache2/sites-available directory. Doing that, you will end up with this filepath:
/etc/apache2/sites-available/site.maxwerk.test.conf
You will need to put something like this in that file:

<VirtualHost *:443>
    ServerName site.maxwerk.test
    ServerAlias site.maxwerk.test
    DocumentRoot /var/www/site.maxwerk.test/public_html/public
    <Directory /var/www/site.maxwerk.test/public_html/public>
        Options +Indexes +FollowSymLinks -MultiViews
        AllowOverride All
    </Directory>
    SSLEngine on
    SSLCertificateFile "c:/wamp/bin/apache/apache2.4.41/conf/keys/site.maxwerk.test+5.pem"
    SSLCertificateKeyFile "c:/wamp/bin/apache/apache2.4.41/conf/keys/site.maxwerk.test+5-key.pem"
    SSLProtocol all -SSLv3 -TLSv1 -TLSv1.1
    Protocols h2 http/1.1
</VirtualHost>

For a description of the highlighted rows, please refer to the explanation in the Windows section above.

Next, we need to enable the site by running this command:

sudo a2ensite site.maxwerk.test

You can test if everything is right by running the following command, which will give you some pointers to correct the possible errors:

sudo apachectl configtest

If everything is ok, you should see these 2 lines at the end of the output:

Output
Syntax OK

You should also restart the apache service for the changes to take effect by running the following command:

sudo systemctl restart apache2

Project setup

Now that we have our files in place and our server settings taken care of, we can focus on getting our site up and running.

Database

We will need to create a database that our site will use.
Some general guidelines that you should follow:

• The database engine should be InnoDB.
• The collation should be utf8mb4_unicode_ci in order to support 4 byte characters such as emojis.

You will need the following details about your newly created database, so make sure you save it somewhere:

• Host: in case of local development, this will be 127.0.0.1 or localhost.
• Port: the default mysql port is 3306.
• Database username: if you use the default "root" user, this will be root.
• Database password: the password for the aforementioned username.
• Database name: the name of the database you just created.

Environmental file

Environmental files make it possible to use different database connections, SMTP setups and other configuration variables across different environments.
For example, you can use your own database in your local development environment, while the staging and/or production environments use their own respective databases, making it easy to set up the project in multiple places without the need to change anything in the core codebase.

These environmental configuration values are stored in .env files, so we will need to create this file in our projects' root folder.
This file is not present after cloning a repository into our local machine. Instead, we have a .env.example file, which should contain all the available options needed for the project, with some dummy data for the values of the settings.
You need to copy this file, rename it to .env and then fill in your details.

WARNING

It is imperative that you copy the file first and then rename it. If you just rename the .env.example file, it will be deleted from the remote repository, which is a big no-no.

In the .env file, you will see stomething like this (this is just a partial example):

APP_NAME=Laravel
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost

LOG_CHANNEL=stack

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

INFO

Each project can have some extra options in its .env.example file, so you should not be surprised to see options you did not see before on other projects.

We will go over the most important options here:

Variable	Details
APP_NAME	You should enter the project name here.
APP_ENV	This can be one of 3 options: local, staging or production
APP_KEY	We will talk about this one a bit later. Leave it empty for now.
APP_DEBUG	Can be true or false. Should be set to false on a production environment.
APP_URL	The URL of the site. Put the URL you created the virtual host for in the "Createing a virtual host" sectino of this guide. The URL should not have a trailing slash!
APP_LOCALE	The default language of the site. Supported values: https://github.com/Laravel-Lang/lang/tree/master/locales
DB_HOST DB_PORT DB_USERNAME DB_PASSWORD DB_DATABASE	The details of the database you just created.
CACHE_DRIVER	Our latest projects require this to be redis because of its tagging support, so make sure you installed Redis properly. If you get a Class 'Redis' not found error, there is something wrong with the installation of Redis or the Redis PHP extension. Note: Using redis is highly recommended even if the project works with a simple file driver in order to get a development environment as close to the server environment as possible.
SESSION_DRIVER	Should be the same as your CACHE_DRIVER.
REDIS_HOST REDIS_PASSWORD REDIS_PORT	You Redis details come here. If you did not change the default settings for Redis, your host will be 127.0.0.1, your port will be 6379 and your password will be null (as in not set).
MAIL_DRIVER MAIL_HOST MAIL_PORT MAIL_USERNAME MAIL_PASSWORD MAIL_ENCRYPTION	In order to test outgoing emails, you will need to set up a mailtrap, gmail or any other email account you prefer. In case of gmail, you can use the following details: MAIL_DRIVER=smtp MAIL_HOST=smtp.gmail.com MAIL_PORT=465 MAIL_USERNAME=youremail@gmail.com MAIL_PASSWORD="yourpassword" MAIL_ENCRYPTION=ssl

INFO

If you need to define an environment variable with a value that contains spaces, you may do so by enclosing the value in double quotes.

WARNING

If you decide to use gmail for your outgoing mails, you will need to turn on the "allow less secure apps" option for your email address.
You can change this option here: https://myaccount.google.com/lesssecureapps

Composer

Now that we have our configuration ready, we can install the packages that our project is depending on. For this, we will use Composer.
If you still don't have this PHP package dependency manager installed check back into the respective section of the guidelines here.

Open up a terminal and go to the projects' root directory:

cd C:\path\to\your\project

Once you are in the right directory, you can install the PHP package dependencies by runnin the following command:

C:\wamp\bin\php\php7.4.4\php -d memory_limit=4G C:\ProgramData\ComposerSetup\bin\composer.phar install

You might notice that we used the fullpath to both PHP and Composer. This is to ensure that composer uses the right PHP version for the given project, cause if you have multiple PHP versions installed (I, personally have 5), running a simple composer install will use the PHP version which is stored in your operating system's PATH environmental variable (which might be an older version than you need).
From this point forward, we will always use the fullpath to our PHP version.

We also increased the memory_limit for PHP since Composer can eat up a lot of memory and we would most probably get an Allowed memory size exceeded error otherwise.

INFO

Composer v2.0 made a huge improvement around the memory usage, but we are still using the v1.0 branch of Composer, cause some of the packages we use are not yet compatible with Composer v2.0.

Finally, we added the fullpath to our Composer PHP archive file (hence the .phar) so our selected PHP version can run it.

INFO

If you are unsure where your composer.phar file is installed, you can find it by running this command:

which composer

If you are running on Windows, you can install the which command for your terminal by downloading it from the GnuWin package repository here.

By running Composer's install command, we are installing the required dependencies according to the package-lock.json file, which prevents automatic major version upgrades during installation. This ensures, that we do not get unexpected behaviour due to possible breaking changes in some of the required packages.

Artisan

Laravel comes with a command line interface called artisan. You can use this tool to run various commands.
We also need to run some of these command before our site is fully usable.

We will start with running our database migrations, so that we have our tables created automatically for us. We can do this by running the following command:

C:\wamp\bin\php\php7.4.4\php artisan migrate

This takes all the migration files we have under the database\migrations directory of our project and runs them one after the other.
If you check your database after running this command, you can see that your database is filled with wonderful tables.

If, for any reason, you want to wipe the contents of your whole database, you can do so by running this command:

C:\wamp\bin\php\php7.4.4\php artisan migrate:fresh

This drops all tables and runs all the migration files again.

Next, we will generate an encryption key which is used to encrypt the cookie and session content of our site. We can do this by running this command:

C:\wamp\bin\php\php7.4.4\php artisan key:generate

Once you ran this command and open up your .env file, you will notice that your APP_KEY configuration variable is not empty anymore, but has a value like base64:G8qBnNZP2TTjEWon9t6MQv9GiO0npqZdnTIjoGqtqT8=.
This is why I told you to leave that empty in the environment section of this guide.

Next, we will create a symlink to our storage/app/public directory in order to actually see our uploaded images on our site. We do this by running one of the following commands depending on our operating system:

Windows

C:\wamp\bin\php\php7.4.4\php artisan files:link app/public files

Linux

C:\wamp\bin\php\php7.4.4\php artisan files:link ../storage/app/public ./public/files yes

Now, we basically have our site ready, but we will need an administrator account in order to access our admin panel and optionally make some extra dummy data for our site.
We can do this by running our seeder with the following command:

C:\wamp\bin\php\php7.4.4\php artisan db:seed

Running this command will prompt us to answer some questions, for example:

Do you wish to refresh migration before seeding? It will clear all old data. [yes, no]

If we say yes to this question, the underlying code will call the previously mentioned migrate:fresh command.

Next, we will get some questions about roles and users in this order:

Do you want to create some roles for users? [y|N]
Enter roles in comma separated format. [developer,admin,editor,user]
Create users for role developer? [y|N]
How many users do you want to seed for role developer? [0]

The options you can choose from or the default arguments for each command are presented after the question between brackets.
If the question is a yes/no type, the default answer is in capital letters.

WARNING

The questions during a full seeding process can vary depending on which version of the codebase you are on. There can be as few as 10 questions, but we have some projects for which the seeder will ask even a whoopping 100 questions.

WARNING

During the role generation question, if you see the developer, admin, editor and user roles listed as defaults, you should keep at least those roles in the list you provide. Some of our projects need those roles in order to function properly.

You can also run specific seeders independently by specifying the seeder class to run.
For example, if you only wish to seed the user roles, permissions and some users, you can run this command:

C:\wamp\bin\php\php7.4.4\php artisan db:seed --class UserSeeder

You can find the list of all existing seeder classes if you open up the database\seeds\DatabaseSeeder.php file and search for $this->call in there.

WARNING

The available seeder classes may vary depending on the version of the codebase you are using. It is even possible that the project you are working on does not have any individual seeders available. In that case, just use the command for a full seed: db:seed

Now, if you followed this guide, you should be able to visit your site on the URL you specified in your virtual host file.
For example, in our virtual host creation examples, we used site.maxwerk.test as our ServerName, so if we enter that URL in our favourite browser, we should see our site working as intended.
You can also access the administration panel if you append /admin after your URL, for example site.maxwerk.test/admin.