bfg/doc

Php doc block generator

1.0.3 2023-05-22 20:52 UTC

Requires

• php: ^8.0
• bfg/entity: ^1.1.5
• bfg/object: *
• bfg/text: *

MIT

• bfg

• doc
• block
• laravel

README

A system for describing the behavior of classes where magic methods are used so as not to lose connection with the classes.

What is it for?

Its main purpose is to use it to describe your magic methods or properties that are accumulated in the properties of the class.

Install

composer require bfg/doc

Principle of operation

For a convenient description of properties, I wrote this logic on the attribute system that was added to php 8.

The kernel searches for files in all project folders, except for the following: {base_path}/public, {base_path}/vendor, {base_path}/routes, {base_path}/resources, {base_path}/storage, {base_path}/runtimes, {base_path}/database.

And it ignores all named folders: node_modules, css, js.

Searches for files with the *.php extension and checks for the existence of a class in the file.

To avoid difficulties, it is necessary to create a separate file for each class.

Usage

In total, for generating helpers, I created 2 main attributes:

/**
 * @props string $type Doc var type: "@method" 
 * @props array|string|null $var_type Doc type of var
 * @props string|null $name Doc name of var
 * @props string|null $description Doc description of the var
 */
use Bfg\Doc\Attributes\Doc($type, $var_type, $name|null, $description|null);

The first attribute Bfg\Doc\Attributes\Doc is needed just to designate a property that will extend the capabilities of the class.

/**
 * @props string $name Class namespace for mixin helper
 */
use Bfg\Doc\Attributes\DocClassName($name);

The second attribute Bfg\Doc\Attributes\DocClassName is needed to indicate the name of the class into which these properties will be added.

This can be useful if you are making a package that can extend its properties as needed.

I also added several aliases for the Bfg\Doc\Attributes\Doc attribute:

// To generate method helpers
use Bfg\Doc\Attributes\DocMethods($var_type, $name|null, $description|null);

// To generate property helpers
use Bfg\Doc\Attributes\DocProperties($var_type, $name|null, $description|null);

// To generate method helpers from array
use Bfg\Doc\Attributes\DocMethodsFromArray($var_type, $description|null);

// To generate property helpers from array
use Bfg\Doc\Attributes\DocPropertiesFromArray($var_type, $description|null);

Macro strings:

• Global:
  • {name} - The name of variable
• Array:
  • {key} - Key of array
  • {value} - Value of array
• Variable:
  • {value} - Value of variable
  • {type} - Type of variable
  • {value_construct} - The value class construct props
• Class name:
  • {class} - The name of class
  • {namespace} - The namespace of class

Example

use Bfg\Doc\Attributes\DocMethodsFromArray;
use Bfg\Doc\Attributes\DocPropertiesFromArray;
use Bfg\Doc\Attributes\DocClassName;

/**
 * Class PropsData
 * 
 * Result:
 * @method PropsData|static test() From inputs property for test method
 * @[type] [var_type]       [name] [description]
 * @property-read PropsData $simple_form
 * @[type]       [var_type] [name]
 *
 * And if you want you can add the "DocClassName" and created this class like mixin
 * @mixin \Bfg\Doc\Attributes\PropDataBlocks
 */
class PropsData
{
    /**
     * @var array|string[]
     */
    #[DocMethodsFromArray(['{value}', 'static'], 'From {name} property for {key} method')]
    static array $inputs = [
        'test' => PropsData::class
    ];

    /**
     * @var array|string[]
     */
    #[DocPropertiesFromArray]
    protected array $forms = [
        'simple_form' => PropsData::class
    ];

    /**
     * @var array|string[]
     */
    #[DocPropertiesFromArray, DocClassName('PropDataBlocks')]
    protected array $blocks = [
        'simple_block' => PropsData::class
    ];
}

Run

To start the generator, just call the artisan command:

php artisan make:docs

or

composer dump-autoload