Developing Laravel packages is a task that requires a lot of attention to detail. One of the most common problems that Laravel package developers face is not properly documenting their facades or maintaining the docs. This can lead to warnings and errors in the IDEs that are used by developers when trying to use the package's methods using Laravel Facade.

Fortunately, there is a solution to this problem: Introducing Docgen for Laravel Facade This package automatically generates documentation for your Laravel package facade, eliminating the tedious task of maintaining it yourself. With this package, IDEs will provide you and the developers using your package with method suggestions, making your development journey a breeze.

In this tutorial, we will walk through the process of installing and using Docgen for Laravel Facade, and how it can help solve the "Method Not Found" warnings in IDEs due to the lack of phpdoc blocks in the facade.

Prerequisites

Before we start, make sure you have the following installed:

• Composer

• A Laravel Package to work with.

• PHP 8.0+

Installation

To get started, you'll need to install the package via composer. Run the following command in your Laravel package's root directory:

composer require irazasyed/docgen --dev

Basic Usage

The basic usage of Docgen for Laravel Facade is quite simple. You just need to call the command with the name of the facade you want to generate documentation for.

vendor/bin/docgen -f "Namespace\Path\To\Laravel\Facade::class"

Replace Namespace\Path\To\Laravel\Facade::class with the actual namespace and class of your package facade.

Advanced Usage

If your Laravel facade is linked to a chain of classes that require documentation, you can use Docgen's advanced features. Here's how you can create a new config file in your package's root directory named docgen.php and add the following code:

<?php

return [
    'facade' => Namespace\Path\To\Laravel\Facade::class,

    // Optional
    // Path\To\Class::class => [Excluded Methods Array]
    'classes' => [],

    // Global Excluded Methods
    'excludedMethods' => [],
];

You can provide an array of class names in the classes key, and an array of excluded methods for each class. The excludedMethods key can be used to globally exclude certain methods from the documentation.

To generate the documentation and apply it to the facade, run the following command:

vendor/bin/docgen

By default, it's smart to exclude the magic methods and constructor but there may be cases where you'd want to manually exclude them.

Docgen is designed to only document public methods, so anything private or protected will by default not be documented.

If your docgen.php config file is stored elsewhere, you can provide the path using the -c or --config option:

vendor/bin/docgen -c path/to/docgen.php

Generate Docs for Multiclass Facade

If you have a Laravel facade that is linked to a chain of classes that require documentation, you can provide an array of class names to Docgen's classes key. You can also exclude certain methods from the documentation of a specific class, by passing an array containing the names of those methods.

Here's an example of how to use this approach with the Telegram Bot SDK's Laravel Facade:

// docgen.php

return [
    'facade' => Telegram\Bot\Laravel\Facades\Telegram::class,

    'classes' => [
        \Telegram\Bot\BotsManager::class,
        \Telegram\Bot\Api::class => [
            'setContainer',
            'getWebhookUpdates',
        ],
        \Telegram\Bot\Commands\CommandBus::class => [
            'getTelegram',
            'setTelegram',
        ],
    ],

    // Global Excluded Methods
    'excludedMethods' => [],
];

To generate and apply the docs, simply run the command:

vendor/bin/docgen

Adding CLI Command to composer.json

To make using Docgen for Laravel Facade even easier, you can add the following CLI command to your composer.json file:

"scripts": {
    "docgen": "docgen",
    "test:docgen": "docgen -d",
}

With this command in place, you can run composer docgen to generate and apply the facade documentation, or composer test:docgen to dry-run and display the generated docblock assuming docgen.php config file exists in the root of the project.

Conclusion

With Docgen for Laravel Facade, you can streamline your Laravel package development by automatically generating documentation for your facade.

If you like the tutorial and the tool, come ⭐️ star it on GitHub :)