Getting started with Laravel Zero

Published in Laravel Zero, PHP on Apr 17, 2020

Laravel Zero is a micro-framework based on Laravel for creating PHP command-line applications.

You can take a look at the laravel-zero/laravel-zero repository for the core code that we'll be using for this tutorial.

We'll be building a simple application that displays Ecologi statistics for a user by utilising the new Http component that was added in version 7 of Laravel Zero. If you don't have Ecologi, we'll be using the Laravel community username (laravel) for this tutorial.

Setting up your application

To initialise a new Laravel Zero project, you can either use the laravel-zero installer, or directly via Composer. I'll demonstrate how to install with both of these tools (however, the Laravel Zero installer requires Composer to be installed under the hood). If you don't already have Composer installed, check out the installation instructions on the Composer site.

For installations with Composer, you can use the create-project command as follows:

$ composer create-project --prefer-dist laravel-zero/laravel-zero application

For installations with the Laravel Zero installer, first install the package globally and then run the new command.

$ composer global require laravel-zero/installer

$ laravel-zero new application

You can now browse to your newly created application/ directory and run php application to check that it has been installed as expected.

Renaming the application binary

By default, the binary to run your commands is named application, we'll rename this to ecologi using the following rename command:

$ php application app:rename ecologi

You should be able to access the binary using php ecologi from now on.

Installing the Http Component

One of the new features of Laravel Zero 7 was being able to pull in the Http component from Laravel's core.

This adds a simplified wrapper around Guzzle, with a great syntax and easy faking/mocking support.

Laravel Zero provides an easy command for installing components, for the Http Component we'll use the following and then type http for the input:

$ php ecologi app:install

This command will also display any of the other available components which you can find more information about in the documentation.

The Http Component will install the Guzzle and Illuminate Http packages, and once installed, we'll get started on our first command.

Adding a console command

Adding commands to a Laravel Zero application only involves adding a new Command class to the app/Commands directory. By default, the InspiringCommand is included and can be removed. Laravel Zero has a helpful command to assist with creating new commands.

$ php ecologi make:command StatsCommand

You can now open the newly created app/Commands/StatsCommand.php file in your editor. Once opened, the class should contain a few properties and methods.

The $signature property is one of the core components of a command. This defines the name of the command, as well as any arguments and/or options. For this application we will specify the following value:

protected $signature = 'stats {username}';

This definition states that the command should be called using the stats keyword, and specifies an argument with the name username which can then be accessed anywhere in the command class.

Next is the $description property, this is pretty self-explanatory and I personally tend to remove it, but we will set this to the following:

protected $description = 'Retrieve the Ecologi statistics for a user';

And finally, for this command, we will use the handle method. This is where any actual code to run during the command is added.

We'll update this to add the following code which grabs the statistics for a user from the Ecologi API, and outputs them in the terminal. Remember to import the Illuminate\Support\Facades\Http class.

public function handle(): void
{
    $username = $this->argument('username');

    $response = Http::get("https://public.ecologi.com/users/{$username}/impact");

    if (! $response->ok()) {
        $this->warn('Failed to retrieve user statistics');
        return 1;
    }

    ['trees' => $trees, 'carbonOffset' => $carbonOffset] = $response->json();

    $this->info("@{$username} has planted {$trees} trees, and offset {$carbonOffset} tonnes of CO2");
}

We also have another method by default called schedule, I won't go into detail on how this works, but it allows you to schedule your command to be run at intervals. More details on this is available on the documentation.

Testing the command

To check that the command works, you should now be able to run the following in your terminal.

$ php ecologi stats laravel

Or replace laravel with your Ecologi username.

You should receive the following output:

Preview of output from command line

Compiling to a standalone app

As well as the usual installation through Composer, Laravel Zero also supports distribution through compiled Phar files. This allows your app to be packaged into a single file that can be executed from any path.

To do this, we'll be using the build command as follows:

$ php ecologi app:build

This will prompt for a version number (the default is the latest tag in the Git repository), and then compile the app to the builds/ directory.

You can then run php builds/ecologi to use your compiled application, or copy it to your global path so it can be run from anywhere using ecologi (note that PHP does need to be available in your path to execute it, or on Windows a Batch file may also be required).

Summary

This is a really basic example, but it displays some of the new key features of Laravel Zero 7. For the full code that was used in this tutorial, check out the repository on GitHub.

Check out the documentation site for more features of the Laravel Zero framework, and feel free to open an issue for any problems that you experience.

0
0
0
0