Tutorial: How to Resolve Method Not Found Warnings in Laravel Packages using Docgen
Tags: laravel, php, tutorial, opensource
Published: 2023-03-18 19:48:00

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](https://github.com/irazasyed/docgen)** 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 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:


```bash
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.


```bash
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
<?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:

```bash
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:


```bash
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](https://github.com/irazasyed/telegram-bot-sdk/blob/3.x/docgen.php)'s Laravel Facade:


```php
// 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:

```bash
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:


```json
"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](https://github.com/irazasyed/docgen) :)