[11.x] Optimize commands registry

[erikgaal]

Motivation

From the docs:

When deploying your application to production, there are a variety of files that should be cached, including your configuration, events, routes, and views. Laravel provides a single, convenient optimize Artisan command that will cache all of these files.

Other than the caching commands the framework uses by default, third-party packages often also have similar commands:

• blade-ui-kit/blade-icons: icons:cache && icons:clear
• spatie/laravel-event-sourcing: event-sourcing:cache-event-handlers && event-sourcing:clear-event-handlers
• spatie/laravel-data: data:cache-structures

Of course, developers are expected to read integration guides so they can install and configure packages accordingly. However, sometimes deployment optimization steps like these are forgotten about (I'm personally the prime example of that 🙈). Packages usually just work if you forget this but are running with sub-optimal performance costing more compute time ⏱️ , energy ⚡ and money 💰 as a result.

Wouldn't it be great that every package you install does these optimization steps automatically?

Implementation

This addition surfaces an extension point packages can use to run their own optimization handlers to be automatically run when the artisan optimize and artisan optimize:clear commands run.

It works by having an event be dispatched (Optimizing and OptimizeClearing) whenever the artisan optimize command runs. Packages can then register an event listener in their service providers that run the optimization step they need to do.

A previous implementation worked by dispatching special events that package developers could hook into. After consideration, I've taken a different approach similar to how publishes are registered in Service Providers.

The ServiceProvider class now offers a registerOptimizeCommands() method that can be used to register a command that should run during the optimize and optimize:clear commands. It also allows you to provide a key which is used to show the step in the command output.

Example:

class PackageServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $this->commands([
            MyPackage\CacheCommand::class,
            MyPackage\ClearCommand::class
        ]);

        $this->registerOptimizeCommands(
            key: 'my package',
            optimize: 'my_package:cache',
            optimizeClear: 'my_package:clear',
        );
    }
}

Running the optimize command will now also output all the optimization commands that ran:

$ php artisan optimize

   INFO  Caching framework bootstrap, configuration, and metadata.  

  config .................................................................... 39.29ms DONE
  events ..................................................................... 2.28ms DONE
  routes .................................................................... 36.46ms DONE
  views .................................................................... 647.20ms DONE
  my package ................................................................. 0.23ms DONE

Todo

• Find a way to show progress/tasks of packages doing their caching/clearing in the output of the command.
• The optimize and optimize:clear commands were backported to earlier versions of Laravel, do we want to do that with this PR too?

[ollieread]

Nice idea @erikgaal! I'd be inclined to have the third-party packages have the commands register as optimisation and optimisation clearing commands, similar to how you can register publishable assets.

$this->registerOptimizationCommands(
    optimization: 'icons:cache', 
    optimizationClearing: 'icons:clear'
);

That way it's not silent, and then it opens you up to an interactive command, something like

php artisan optimize --select

That lets you select specifically which things you want to optimise.

That's my thinking on this, for whatever it's worth. Either way, good work so far and good luck with the PR.

[erikgaal]

Hey @ollieread, thanks for the suggestion. I think it aligns perfectly with what I had in mind earlier. I've updated the PR with the new implementation! 🚀

[erikgaal]

These could be registered in the respective service providers that are responsible for adding these commands/functionalities?

[ollieread]

These could be registered in the respective service providers that are responsible for adding these commands/functionalities?

Good call, but, the order may be important

[MahdiSaremi]

This is so useful

[taylorotwell]

I would actually prefer just having the events like you originally had. 🫠 Please mark as ready for review when the requested changes have been made.

[erikgaal]

That would mean

• not having any output (the original implementation), or;
• leaking the command $components through the event and having to use Artisan::callSilently manually, or;
• providing something on the Optimizing and OptimizeClearing events that abstracts away the command $components. $event->task(key: 'my-package', fn () => Artisan::callSilently('my-package:cache'))

Let me know what option you prefer and I'll get it done.

[shaedrich]

$ php artisan optimize

   INFO  Caching framework bootstrap, configuration, and metadata.  

  config .................................................................... 39.29ms DONE
  events ..................................................................... 2.28ms DONE
  routes .................................................................... 36.46ms DONE
  views .................................................................... 647.20ms DONE
  my package ................................................................. 0.23ms DONE

I would actually prefer something like this:

$ php artisan optimize

   INFO  Caching framework bootstrap, configuration, and metadata.  

  config .................................................................... 39.29ms DONE
  events ..................................................................... 2.28ms DONE
  routes .................................................................... 36.46ms DONE
  views .................................................................... 647.20ms DONE
  my package:config .......................................................... 0.13ms DONE
  my package:routes .......................................................... 0.09ms DONE

or

$ php artisan optimize

   INFO  Caching framework bootstrap, configuration, and metadata.  

  config .................................................................... 39.29ms DONE
  events ..................................................................... 2.28ms DONE
  routes .................................................................... 36.46ms DONE
  views .................................................................... 647.20ms DONE
  my package ................................................................. 0.22ms DONE
      config ................................................................. 0.13ms DONE
      routes ................................................................. 0.09ms DONE

Alternatively, couldn't classes just implement something like a Cachable contract (or an attribute like #[Cachable] like what @GianfriAur suggested in #52971) and all classes that have it, are collected for caching? 🤔

[taylorotwell]

Thanks @erikgaal - tweaked a few things. 👍