Work environment

PODCAST

Before you start working on the project, you need to set up your work environment.
This includes installing the necessary software and configuring it to work with the project.

Tool	Software	Description
Git	Git Bash	Command line tool for version control
PHP	Herd	PHP development server
Nginx	Herd	Web server for local development
Node	Herd	JavaScript runtime environment
Composer	Herd	PHP dependency manager
Database manager	SQlite	Database for local development
Mail server	Mailpit	Mail server for local development

Git Bash

Download and install a recent version of Git Bash from https://git-scm.com/downloads
Open a new terminal window ("Git Bash Here") and check your configuration

bash

$ git --version
git version 2.45.1.windows.1

Herd

Laravel Herd is a first-citizen development environment for Laravel projects. It's very easy to install and use.
In this course, we will use the free version of Herd, withs includes:

Different PHP versions (where every project can have its own PHP version)
Composer (PHP dependency manager)
NVM or Node Version Manager (a tool to manage multiple Node versions)

IMPORTANT

You probably already have node.js installed on your computer and some global installed packages.
Use the command npm list -g --depth=0 to check the installed packages.
It's recommended to uninstall node.js and add those packages again after installing Herd.

Installation

Download Herd from https://herd.laravel.com/
Install Herd by running the installer (with administrator privileges!)
Open Herd:
- Herd will download the necessary files and install them
- When asked for a license key for Herd Pro, click on Skip for now
- Check the option "Automatically start Herd on system startup" and click on Let's get started
Herd is now accessible from the system tray (menu bar) on the right side of the screen

Herd configuration

Open the Herd configuration by right-clicking on the Herd icon in the system tray and selecting Settings icon at the bottom of the menu

Dashboard

The dashboard shows the default PHP versions and the Nginx server status
If both are green, everything is working correctly

General

The default folder where Herd stores the configuration is %USERPROFILE%\.config\herd. This is also the default folder for your PHP-projects. To avoid losing your projects when you uninstall Herd, it's recommended to add a new folder (outside the Herd folder) to store your projects.

Create, at the root of your C-drive, a new folders C:\sites_laravel (where you store your Laravel projects)
Creat, inside the C:\sites_laravel folder, a new folder info.
Add the C:\sites_laravel folder to the Herd configuration by clicking on the Add path button and selecting the folder C:\sites_laravel
Check the option Update Herd automatically to ensure that Herd is always up-to-date
Create, inside the C:\sites_laravel\info folder, a new file index.php with the following content:

php

<?php
phpinfo();

Herd will automatically detect the new folder and add a host for it with the name info.test (the folder name with the extension .test)
Open your browser and go to http://info.test to see the PHP info page

IMPORTANT

If the PHP info page is not displayed, go to the known issues section on the bottom of this section to see how to solve this problem.

Dashboard -> Sites

Click on Dashboard tab and open the Sites section
In this section, you can add changes to the PHP version that will be used for a specific project
Click on the Secured icon next to the site name to update the connection to HTTPS (secured) instead of HTTP (unsecured)

PHP

In this section, you can install additional PHP versions
We will use the default PHP versions (8.3.x) for all our Laravel projects

Node

Herd installs the latest version of Node.js by default
If you need a specific version of Node.js for a project, you can install it here
If you want, for example, Node.js version 20.x.x, as the default version, click on the Install button to download this version
After the installation, you can switch between the different versions of Node.js from the cmd prompt by using the command nvm use XX where XX is the MAJOR version number
Use the command nvm list to check the installed version of Node.js
(The version with the * is the active version)

bash

C:\Users\Patrick>nvm use 20
Now using node v20.14.0 (64-bit)

C:\Users\Patrick>node -v
v20.14.0

C:\Users\Patrick>nvm list

    22.3.0
  * 20.14.0 (Currently using 64-bit executable)

NO * IN FRONT OF THE VERSION?

If node is not installed correctly, go the Uninstall section:

Follow the steps to uninstall nvm
Quit Herd by right-clicking on the icon in the menu bar and selecting Quit
Restart Herd and now you can install the Node.js version you want

Expose (optional)

Expose is a tool that allows you to share your local websites with the outside world.

Create an account on https://expose.dev/
Copy the Expose Token from the dashboard and paste it in the Herd configuration
Open a new cmd prompt and run the command expose share http://info.test to share your local info.test site with the outside world
Your site is now available on the internet at the URL's provided by Expose

Git Bash aliases

By default, most the Herd commands are only available in the cmd prompt and in PowerShell. To make those commands available in the Git Bash terminal, you need to add aliases that point to the Herd executables.

Open your user folder (C:\Users\<Username> or paste %USERPROFILE% in the Windows navigation bar)
Create a new file .bash_profile and add the following aliases:

bash

if [ -f ~/.bashrc ]; then
   source ~/.bashrc
fi

Create a new file .bashrc and add the following aliases:

bash

alias composer='composer.bat'
alias expose='expose.bat'
alias herd='herd.bat'
alias laravel='laravel.bat'
alias php='php.bat'

Custom Valet drivers

Herd recognizes by default installations of Laravel, WordPress, and many other PHP frameworks. For our PHP8 course, we use another setup that is not recognized by Herd. Therefore, we need to create a custom Valet driver.

Go to the Valet directory in the Herd configuration (%USERPROFILE%\.config\herd\config\valet)
Create a new folder Drivers (with a capital D!)
Create a new file BasicWithPublicHtmlValetDriver.php in the Drivers folder with the following content:

BasicWithPublicHtmlValetDriver.php

php

<?php

namespace Valet\Drivers\Custom;

use Valet\Drivers\BasicWithPublicValetDriver;

class BasicWithPublicHtmlValetDriver extends BasicWithPublicValetDriver
{
    private $path = '/public_html';

    /**
     * Determine if the driver serves the request.
     */
    public function serves(string $sitePath, string $siteName, string $uri): bool
    {
        return is_dir($sitePath . $this->path . '/');
    }

    /**
     * Determine if the incoming request is for a static file.
     */
    public function isStaticFile(string $sitePath, string $siteName, string $uri)/*: string|false */
    {
        $publicPath = $sitePath . $this->path . '/' . trim($uri, '/');

        if ($this->isActualFile($publicPath)) {
            return $publicPath;
        } elseif (file_exists($publicPath.'/index.php')) {
            return $publicPath.'/index.php';
        }

        return false;
    }

    /**
     * Get the fully resolved path to the application's front controller.
     */
    public function frontControllerPath(string $sitePath, string $siteName, string $uri): ?string
    {
        $_SERVER['PHP_SELF'] = $uri;
        $_SERVER['SERVER_ADDR'] = '127.0.0.1';
        $_SERVER['SERVER_NAME'] = $_SERVER['HTTP_HOST'];

        $docRoot = $sitePath . $this->path;
        $uri = rtrim($uri, '/');

        $candidates = [
            $docRoot.$uri,
            $docRoot.$uri.'/index.php',
            $docRoot.'/index.php',
            $docRoot.'/index.html',
        ];

        foreach ($candidates as $candidate) {
            if ($this->isActualFile($candidate)) {
                $_SERVER['SCRIPT_FILENAME'] = $candidate;
                $_SERVER['SCRIPT_NAME'] = str_replace($sitePath . $this->path, '', $candidate);
                $_SERVER['DOCUMENT_ROOT'] = $sitePath . $this->path;

                return $candidate;
            }
        }

        return null;
    }
}

Uninstall Herd

Quit Herd by right-clicking on the icon in the menu bar and selecting Quit.
Uninstall Herd via the Windows uninstaller
Delete the Herd config directory at %USERPROFILE\.config\herd
Uninstall nvm if you've installed it via Herd
- Go to the C:\Program Files directory and delete the nodejs shortcut
- remove the System variables (Systeemvariabelen) NVM_HOME and NVM_SYMLINK
- remove the related Environment variables (Omgevingsvariabelen) by double-clicking on the Path variable and deleting the two entries that point to the nvm directory and to the nodejs shortcut

Known issues

One of the issues that your website is not working correctly is that the HerdHelper isn't running (Status is red instead of green) because de default port is already in use.

Change the port number under the General tab to another port number (e.g. 5555)
Quit Herd by right-clicking on the icon in the menu bar and selecting Quit
Restart Herd and check if the HerdHelper is running correctly (Status is green)

If you have more problems with Herd, go to the Herd repository and check the issues.

Mailpit

The Pro version of Herd includes a mail server for local development but the free version does not. Therefore, we need to install a mail server separately.
We will use Mailpit as a mail server for local development. Mailpit is a free and open-source mail server that can be installed on Windows, macOS, and Linux.

Download the latest version (mailpit-windows-amd64.zip) of Mailpit from https://github.com/axllent/mailpit/releases/
Extract the zip file in the root of your C-drive and rename the folder to mailpit
(The path to the Mailpit executable should be C:\mailpit\mailpit.exe)
Add the Mailpit executable to the system path
- Open the Environment Variables (Omgevingsvariabelen) window by searching for Environment Variables in the Windows search bar
- Click on the Environment Variables button at the bottom of the window
- In the System variables section, select the Path variable and click on the Edit button
- Click on the New button and add the path to the Mailpit executable (C:\mailpit)
- Click on the OK button to save the changes
Open a new cmd prompt and run the command mailpit to start the Mailpit mail server (Ctrl+C to stop the server)

bash

C:\Users\Patrick>mailpit version
mailpit v1.18.5 compiled with go1.22.4 on windows/amd64

C:\Users\Patrick>mailpit
time="2024/06/18 10:34:25" level=info msg="[smtpd] starting on [::]:1025 (no encryption)"
time="2024/06/18 10:34:25" level=info msg="[http] starting on [::]:8025"
time="2024/06/18 10:34:25" level=info msg="[http] accessible via http://localhost:8025/"

Open your browser and go to http://localhost:8025 to access the Mailpit web interface

SQLite (optional)

SQLite is a lightweight database that is used for local development and is also the default database for Laravel 11.
(Before Laravel 11, the default database was MySQL.)
SQLite is a serverless database that stores the data in a single file. To manage the database, we can use the built-in database manager from PhPStorm.
Because SQLite files are not readable by humans, we can install SQLite to dump the database to a readable format.

Download the latest version of SQLite from https://www.sqlite.org/download.html
(The download sqlite-tools-win-x64-XXXXXXX.zip)
Extract the zip file in the root of your C-drive and rename the folder to sqlite
(The path to the SQLite executable should be C:\sqlite\sqlite3.exe)
Add the SQLite executables to the system path
- Open the System environment Variables (Omgevingsvariabelen van het systeem) window by searching for Environment Variables in the Windows search bar
- Click on the Environment Variables button at the bottom of the window
- In the System variables section, select the Path variable and click on the Edit button
- Click on the New button and add the path to the SQLite executable (C:\sqlite)
- Click on the OK button to save the changes
Open a new cmd prompt and run the command sqlite3 to start the SQLite database manager (Ctrl+C to stop the manager)

bash

C:\Users\Patrick>sqlite3
SQLite version 3.46.1 2024-08-13 09:16:08 (UTF-16 console I/O)
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
sqlite>

USEFUL COMMANDS

Because we don't have a database yet, we can't use the SQLite manager for now, but here are some useful commands you can use later in the course:

sqlite3 database/database.sqlite .dump > database/backup_XXXX_XX_XX.sql to backup the database database.sqlite and dump to a readable format (backup_XXXX_XX_XX.sql)
sqlite3 database/database.sqlite < database/backup_XXXX_XX_XX.sql to restore the backup back to a usable database

PhpStorm

Ensure that you have an up-to-date version of PhpStorm on your machine
Follow the installation guide on our Full Stack Essentials course

Work environment ​

Git Bash ​

Herd ​

Installation ​

Herd configuration ​

Dashboard ​

General ​

Dashboard -> Sites ​

PHP ​

Node ​

Expose (optional) ​

Git Bash aliases ​

Custom Valet drivers ​

Uninstall Herd ​

Known issues ​

Mailpit ​

SQLite (optional) ​

PhpStorm ​

Work environment

Git Bash

Herd

Installation

Herd configuration

Dashboard

General

Dashboard -> Sites

PHP

Node

Expose (optional)

Git Bash aliases

Custom Valet drivers

Uninstall Herd

Known issues

Mailpit

SQLite (optional)

PhpStorm