Automatic Docblock Generation on Facades

The Laravel team has been working on a tool to automatically generate docblock generation on Facades in the Laravel framework.

.@timacdonald87 has automated docblock generation on facades.

Facade docblocks are now automatically updated when new methods are added to their underlying targets or when methods change.

This helps IDEs provide a more accurate, up-to-date experience when using facades. ❤️

— Taylor Otwell 🪐 (@taylorotwell) January 5, 2023

What this means for the Laravel community is improved IDE support for Facades, providing more accurate code completion:

Here's another example from the Storage facade—it was updated along with the FilesystemAdapter and FilesystemManager in Pull Request #45517:

If you update to a recent version of Laravel 9, you should see improvements across most Facades (multiple were updated in Pull Request #45504), such as App, Cache, DB, Date, File, Http, Request, and Vite, to name a few.

The process started in December last year with the first pull request introducing this tool, with improvements over subsequent releases to hone the script. Facades can be generated and kept up to date by running the following:

php -f bin/facades.php

This tool was built for Facades that ship with the Laravel framework. If you follow along with weekly framework releases, you might have seen pull requests to add Facade Docblocks for particular methods or groups of methods developers might see needing to be added. Now they can mostly be kept up to date automatically (with a human eye for correctness) thanks to this script!

A shout out to Tim MacDonald and those who helped review the generated Docblocks to make this possible!