Setting Up Your Environment with ASDF

Hi everyone! In this article, we will set up an environment with a very powerful tool called ASDF. I use this tool every day, and it is very useful. It lets you manage many versions of apps and runtimes on your computer. Imagine that you are building an application with PHP 8.3, but you also need to maintain an old project that uses an older version (we have all been there, right?). With ASDF, you can have many versions of PHP on your computer. And it is not only PHP: you can also use it for Node.js, Docker Compose, .NET Core, Python, Terraform, AWS CLI, and much more.

What is ASDF?

ASDF is a tool version manager. All the versions are saved in a file called .tool-versions. You can add this file to your Git project and share it with your team, so everyone uses the same versions.

In the past, we needed many different version managers (nvm, n, rbenv, and phpbrew). Each one had its own commands, its own config files, and its own way of working (for example, how it changes $PATH and environment variables). ASDF gives you one simple interface and one config file for everything, which makes your work easier. You can also use it with almost any tool or runtime.

Advantages

ASDF makes sure that everyone on the team uses exactly the same tool versions. It supports many tools through plugins, and it is simple because it is a single executable.

• You only need one tool to manage your versions
• The community writes the plugins
• A config file manages the versions for each folder

Let’s get started!

In this article, I will set up a development environment from scratch with ASDF. Let’s go! We will install these tools:

• PHP 8.3
• PHP 8.2
• PHP 8.1

Installing the ASDF dependencies

In this article, we will install everything on Linux. You can find more information about ASDF in the official documentation: https://asdf-vm.com/

Before we start, we need to install the dependencies for ASDF. https://asdf-vm.com/manage/dependencies.html

sudo apt-get install curl git

Installing ASDF

Installing ASDF is very simple: you just download the binary file and put it in a folder that is in your $PATH.

Note: The command below uses version v0.20.2 for Linux x86_64. This version may be out of date, so check the latest version at this link: https://github.com/asdf-vm/asdf/releases

mkdir -p ~/.local/bin
curl -fsSL https://github.com/asdf-vm/asdf/releases/download/v0.20.2/asdf-v0.20.2-linux-amd64.tar.gz | tar -xz -C ~/.local/bin asdf

Next, we need to add this folder and the ASDF shims folder to the $PATH. If you use bash, add the line below to the ~/.bash_profile file. If you use zsh, add it to the ~/.zshrc file. Then open a new terminal.

export PATH="$HOME/.local/bin:${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"

If you use another shell, like fish or Elvish, follow the steps for your shell: https://asdf-vm.com/guide/getting-started.html#_2-configure-asdf

After you install ASDF, run this command to check that everything worked.

asdf --version

Now that ASDF is installed, we need to understand how it works.

First, you need to add a plugin for each tool that you want to install. In this article, we want to install PHP, so we need an ASDF plugin for PHP. You do the same for other tools and programming languages.

Installing PHP 8.1, 8.2, 8.3

To install PHP, we will use asdf-php, which is an ASDF plugin for PHP. https://github.com/asdf-community/asdf-php

First, we need to add this plugin to ASDF with this command:

asdf plugin add php https://github.com/asdf-community/asdf-php.git

After we add the plugin, we need to install some dependencies on our operating system. The plugin repository explains which dependencies you need to install first.

Note: These dependencies are for PHP, not for ASDF, because ASDF compiles PHP on your computer. To make things easier, here is the list.

sudo apt-get install -y \
    autoconf \
    bison \
    build-essential \
    gettext \
    libgd-dev \
    libcurl4-openssl-dev \
    libedit-dev \
    libicu-dev \
    libjpeg-dev \
    libmysqlclient-dev \
    libonig-dev \
    libpng-dev \
    libpq-dev \
    libreadline-dev \
    libsqlite3-dev \
    libssl-dev \
    libxml2-dev \
    libzip-dev \
    openssl \
    pkg-config \
    re2c \
    zlib1g-dev

When all the dependencies are installed, we can install PHP. To see which versions are available, run this command.

asdf list all php

This command shows a list of all the PHP versions. It also shows versions that are still in development, so you can test new features. Let’s start with version 8.1.26. Run this command.

asdf install php 8.1.26

The installation can take some time because PHP is compiled on your computer. Also, each PHP version comes with the Composer package manager and PECL.

Now we need to do the same for the other PHP versions:

asdf install php 8.2.13

asdf install php 8.3.0

When the last installation finishes, we need to choose the default version for our environment. To do this, run this command.

asdf set -u php 8.3.0

This command sets the default PHP version for our environment and saves it in the .tool-versions file in our home folder. Now you can run php -v from anywhere on your system, and you will see this output.

PHP 8.3.0 (cli) (built: Dec 17 2023 11:09:15) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.0, Copyright (c) Zend Technologies

Now for the best part: we will create three folders. Imagine that each folder is a project you are working on, and each project needs a different version of PHP.

Let’s go to our home folder and create a folder called Code. Inside it, we will create one folder for each project.

# Go to our home folder
cd ~

# Create the Code folder
mkdir Code

# Go to the Code folder
cd Code

# Create a folder for each project
mkdir project-1
mkdir project-2
mkdir project-3

After we create the folders, let’s go to each one and set the PHP version that we want.

# Go to project-1
cd ~/Code/project-1

# Set version 8.1.26 for project-1
asdf set php 8.1.26

# Check the PHP version
php -v

# Output
PHP 8.1.26 (cli) (built: Dec 17 2023 11:09:15) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.0, Copyright (c) Zend Technologies

# Go to project-2
cd ~/Code/project-2

# Set version 8.2.13 for project-2
asdf set php 8.2.13

# Check the PHP version
php -v

# Output
PHP 8.2.13 (cli) (built: Dec 17 2023 11:09:15) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.3.0, Copyright (c) Zend Technologies

As you can see, when you run php -v, it shows the version for that folder. If you run it from any other folder, it shows the default PHP version (8.3.0). This way, you can set a different version for each folder.

Conclusion

ASDF is a great tool. When I need to install something on my operating system, I always check if there is an ASDF plugin for it. There are many plugins for ASDF, so there is probably one for your favorite language. This Git repository has a list of ASDF plugins: https://github.com/asdf-vm/asdf-plugins .

Thank you, everyone! If you have any questions or feedback, please feel free to leave a comment.