How to use spatie's commonmark-highlighter Laravel package

Welcome to this tutorial, today we are going to create a Laravel application with the new Laravel Sail package.

What is Laravel Sail?

In the previous versions of Laravel you had to install software on your local computer for development. Laravel 8.x comes with Laravel Sail. This package is a build in solution to run your Laravel project using docker.

Docker is a tool that makes it easy to create and run applications by using containers. All the software that the application needs lives in a container and is separated from the system OS. Let's look what that means for Laravel development.

Install & setup Laravel Sail

We are going to install and setup Laravel Sail in windows. Please look at the documentation if you want to install it on macOS or Linux.

Install Docker Desktop

The first step is to install Docker Desktop. Docker Desktop is a visual tool that lets you manage your Docker containers.

Install WSL2

Next, we must ensure that Windows Subsystem for Linux 2 (WSL2) is installed. With WSL2 let you run Linux on Windows.

First, we enable the "WSL" optional feature. Open PowerShell as Administrator and run the following command:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

Next, we need to update WSL to WSL2. Before installing WSL2 we need to enable the "Virtual Machine Platform" optional feature. Open PowerShell as Administrator and run the following command:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Restart your machine to complete the WSL install and update to WSL2.

Now you need to download & install the Linux kernel update package. Download the package and double-click to run the installer.

Next run the following command to set WSL2 as your default version:

wsl --set-default-version 2

The last step is to download a Linux distribution from the Microsoft Store. I choose to download & install Ubuntu 20.04 LTS.

After installation, a console windows will open. You will then need to create a user account.

Configure Docker Desktop

Open Docker Desktop and click on the gear icon on the top. Then select the Settings > Generaltab.

Select the Use the WSL 2 based engine check box.

Then click on the Apply & Restart button.

That is it!! Now you are ready to create a Laravel project.

Create a new Laravel project

Launch Windows Terminal and open a new tab with a session for your Linux OS. Then run the following command:

curl -s https://laravel.build/example-app | bash

This command will create a new Laravel application in a directory named example-app. Of course, you can change "example-app" in this URL to anything you like.

When the project has been created, you can navigate to the application directory and start Laravel Sail:

cd example-app

./vendor/bin/sail up

The first time you run the Sail up command, Sail's application containers will be built on your machine. This could take several minutes. After that you can access the application in your web browser at: http://localhost.

Developing within WSL2

I use Visual Studio Code for developing. To modify the Laravel application files within WSL2 you must install the extension: Remote Development. After the installation you can open Docker Desktop and click on the Open in Visual Studio Code button on the Containers / Apps screen.

To run artisan commands, you must run the commands using Laravel Sail.

# Running Artisan commands locally...
php artisan queue:work

# Running Artisan commands within Laravel Sail...
./vendor/bin/sail artisan queue:work

Install for existing application

When you host a Laravel project on GitHub and want to install it, follow the steps below.

First launch Windows Terminal and open a new tab with a session for your Linux OS. Then clone a repository:

git clone <your repository.git>

Then run the following Docker command:

docker run --rm \
    -v $(pwd):/opt \
    -w /opt \
    laravelsail/php80-composer:latest \
    composer install

This command uses a small Docker container containing PHP and Composer to install the application's dependencies. After that you can run the following command to copy the .env file, generate an application key and run the database migrations.

cp .example.env .env

./vendor/bin/sail php artisan key:generate

./vendor/bin/sail php artisan migrate

Round up

In this tutorial we have learned how to create a project in Laravel 8.x. If you want to get updates about new blog posts, follow me on twitter!