Introducing Trunk

13 Sep 2024

Learn about Trunk and how it makes developing and switching between multiple PHP projects easier than ever!

As somebody who is constantly switching between various PHP projects, I've always found it annoying trying to remember what testing framework, code formatter or other utility tools each project uses.

In most projects, I setup Composer scripts with names such as format or fmt to run the correct formatter, or analyse and check to run a static analyser. This makes the process a little less painful but it does mean I need to have these scripts configured in every single project for them to be used confidently and consistently. That's just not something I want to spend time doing, especially on older projects that I rarely touch.

I'd like to introduce Trunk. A new tool that provides a single, unified command-line interface for running essential utilities inside of PHP projects.

To get started with Trunk, install the command using Composer:

composer global require pxp/trunk

Assuming you've got Composer's global binary directory inside of $PATH, you can run the following command to verify everything is installed correctly.

trunk -V

Commands

Trunk's goal is to make things as simple and consistent as possible. Inspired by Rust's excellent Cargo tool, Trunk provides a set of commands that execute your underlying utility tools.

Here's an overview of the various commands that are available at the time of writing this.

info

The info command outputs a list of information about the current project. It includes the PHP version, the type of project you're working on, as well as a list of installed packages with their respective versions.

Here's an example of the output from a fresh Laravel project.

The info command currently supports the following project types:

Working inside of these frameworks, then you'll see the current version installed. If you're not using one of these frameworks, the "Type" entry will appear as "Unknown".

Please feel free to contribute to the project and add support for other frameworks.

fmt

The fmt command, short for format, runs a code formatting tool.

Right now, Trunk supports the following tools:

It's possible to format a single file or directory of files by passing a path to the command.

trunk fmt ./app/Models/User.php

check

The check command performs static analysis. It has support for the following tools:

Some projects have multiple tools installed for various reasons, but by default the check command will run the first one that it finds based on the order above.

Despite it going against the goal of Trunk, it is possible to execute multiple checkers by passing a comma-separated list to the command.

trunk check --using=phpstan,phan

It will still check to see if they exist. If they do, they'll be executed.

test

The test command executes any sort of test you have in your project. It supports the following tools:

In some scenarios, you might want to pass additional flags to the underlying test runner. You can do this after -- in the command.

trunk test -- --parallel

Future

At the time of writing this post, Trunk has just hit v0.1.0. I'm still refining the command-line interface and adding support for more frameworks and tools, but I've been using it myself for a couple of weeks at this point and already my muscle memory has changed.

As the PXP project itself develops, my goal is to directly integrate some of the tools developed there into Trunk so that you can format and statically analyse your code with zero additional dependencies.

Until then, Trunk will continue receiving new commands and tool support!