andy87/yii2-file-crafter

PHP library for Yii2 - developed by and_y87

1.2.1 2024-11-16 10:18 UTC

Requires

• php: >=8.0
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10.5
• symfony/browser-kit: ^6.0
• symfony/dom-crawler: ^6.0
• yiisoft/yii2: ~2.0.45
• yiisoft/yii2-gii: ~2.2.0

CC-BY-SA-4.0

• Kidin Andrey

• generator
• php
• library
• yii2
• and_y87
• crafter

README

Yii2 File Crafter - library for generating a many templates with minimal differences

Content

• Setup
• Config
• Using

Setup

Requirements

• php >=8.0
• Yii2

Composer

Add package to project

Using console

(Recommended)

• Composer ( global setup )

composer require andy87/yii2-file-crafter:dev-master --dev

• Composer.phar ( local setup )

php composer.phar require andy87/yii2-file-crafter:dev-master --dev

Using: file `composer.json`

Open file composer.json, in section with key require add line:
"andy87/yii2-file-crafter": "dev-master"

dont forget update composer

composer update

- - - - -

Config

Config in the configuration file.

• basic:config/(web|web-local|local).php
• advanced:(frontend|backend)/config/main-local.php

Minimum config

 $config['modules']['gii'] = [
    'class' => yii\gii\Module::class,
    'generators' => [
        'fileCrafter' => [
            'class' => andy87\yii2\file_crafter\Crafter::class,
            'options' => [
                'templates' => [
                    'group_name' => [
                        // 'template' => 'path/to/file.php',
                        'common/services/PascalCaseService' => '@app/common/services/items/{PascalCase}Service.php',
                        'template/test/unit/camelCaseService.tpl' => '@backend/test/unit/{{camelCase}}Service.php',
                        'templates/view/index.php' => 'custom/dir/{{snake_case}}/index.php',
                    ]
                ]
            ]
        ]
    ],
];

Full Config with all options

 $config['modules']['gii'] = [
    'class' => yii\gii\Module::class,
    'generators' => [
        'fileCrafter' => [
            'class' => andy87\yii2\file_crafter\Crafter::class,
            'options' => [
                'cache' => [
                    'dir' => '@runtime/yii2-file-crafter/cache',
                    'ext' => '.tpl'
                ],
                'source' => [
                    'dir' => '@runtime/yii2-file-crafter/templates/source',
                    'ext' => '.tpl'
                ],
                'custom_fields' => [
                    'singular' => 'label - one',
                    'plural' => 'label - many',
               ],
                'commands' => [
                    'php yii gii/model --tableName={{snake_case}} --modelClass={{PascalCase}}' //...
                ],
                'eventHandlers' => app\composents\behavior\FileCrafterBehavior::class,
                'autoCompleteStatus' => true,
                'autoCompleteList' => [
                    'autocomplete name 1',
                    'autocomplete name 2',
                ],
                'previewStatus' => true,
                'canDelete' => true,
                'parseDataBase' => ['autocomplete','fakeCache'],
                'templates' => [
                    'common' => [
                        'common/services/PascalCaseService' => 'app/common/services/items/{[PascalCase]}Service.php',
                    ],
                    'backend' => [
                        'backend/test/unit/camelCaseService.tpl' => 'backend/test/unit/{{camelCase}}Service.php',
                    ],
                    'frontend' => [
                        'frontend/view/index.php' => 'app/frontend/view/{{snake_case}}/index.php',
                    ],
                    'all' => [
                        'common/services/PascalCaseService' => 'app/common/services/items/{PascalCase}Service.php',
                        'backend/test/unit/camelCaseService.tpl' => 'backend/test/unit/{{camelCase}}Service.php',
                        'frontend/view/index.php' => 'app/frontend/view/{{snake_case}}/index.php',
                    ]
                ],
            ]
        ]
    ],
];

Using

• Marks
• Cache
• Source
• Custom Fields
• Autocomplete status
• Autocomplete list
• Preview status
• Can delete
• Parse data base
• Commands
• Events
• Templates

Marks

Module use marks for replace variables in templates.

• {{PascalCase}} - PascalCase by schema name
• {{camelCase}} - camelCase by schema name
• {{snake_case}} - snake_case by schema name
• {{kebab-case}} - kebab-case by schema name
• {{UPPERCASE}} - UPPERCASE by schema name
• {{lowercase}} - lowercase by schema name
• {{[key]}} - custom key from property custom_fields on config ( see Custom Fields )

Example

for schema name Product Items replace marks:

• {{PascalCase}} - ProductItems
• {{camelCase}} - productItems
• {{snake_case}} - product_items
• {{kebab-case}} - product-items
• {{UPPERCASE}} - PRODUCT ITEMS
• {{lowercase}} - product items

Cache (optional)

Configuration for the cache folder with schema data.

• dir - path to the cache directory with schema data
• ext - extension of the cache file

Default configuration:

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'cache' => [
                    'dir' => '@runtime/yii2-file-crafter/cache',
                    'ext' => '.json'
                ],
                // ...
            ],
        ],
    ]
];

Source (optional)

Configuration for the source folder with templates files.

• dir - path to the directory with the templates files source for generation
• ext - extension of the templates file

Default configuration:

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'source' => [
                    'dir' => '@runtime/yii2-file-crafter/templates/source',
                    'ext' => '.tpl'
                ],
                // ...
            ],
        ],
    ]
];

Templates (required)

Array with groups of templates for use on generate files.

[
    ['group1'] => [
        'template1' => 'path/from/project/root/to/resultFile.tpl',
        'template2.tpl' => 'path/from/project/root/to/resultFile.php',
        // ...
    ],
    ['group2'] => [
        'template1.php' => '@path/alias/to/resultFile.tpl',
        '@alias/to/template' => 'path/from/project/root/to/resultFile.php',
        // ...
    ],
]

The source path may contain:

• some @ alias ( source['dir'] - default container )
• ext for generate any file type ( .php default )
• some {{variable}} ( see Marks )

File source-template will be searched in the source folder.
Source folder path can be set in the configuration file. ( see Source )

The resultFile path may contain:

• some @ alias ( @app/ - default prefix )
• ext for generate any file type ( .php default )
• some {{variable}} ( see Marks )

Content of the templates file rendered with the View method renderFile
And prepared with the $replaceList array contains all marks. ( see Marks )
And also passed to the render method:

• $schema - schema object
• $generator - self generator object

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'templates' => [
                    'all' => [
                        '@backend/dir/by/alias/camelCaseService.tpl' => '@backend/generate/by/alias/{{camelCase}}Service.php',
                        'dir/on/source/dir/generate_file' => 'custom/dir/on/source/dir/{{snake_case}}/generate_file.tpl',
                    ],
                ],
                // ...
            ],
        ],
    ]
];

Custom Fields (optional)

Array with custom fields for use custom variables in templates.
Using on template key wrapped in square brackets: {{%key%}}
Example: {{key_one}}, {{key_two}}...

Example simple config

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'custom_fields' => [
                    'singular' => 'one',
                    'plural' => 'many',
                ],
                // ...
            ],
        ],
    ]
];

with template:

Value - ONE = {{singular}}
Value - MANY = ({{plural}})

___

Schema 1: Product Items
Field one = !!product!!
Field many = >>> products <<<

...generate...

Result: app/frontend/views/info--product_items.php

Value - ONE = !!product!!
Value - MANY = (>>> products <<<)

___

Schema 2: Category Group
Field label one = --category--
Field label many = +++categories+++

...generate...

Result: app/frontend/views/info--category_group.php

Value - ONE = --category--
Value - MANY = (+++categories+++)

Autocomplete status

Key autoCompleteStatus contain status for autocomplete field Schema name in the form 200 populated values.

Variants: true or false(default)

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'autoCompleteStatus' => true,
                // ...
            ],
        ],
    ],
];

Autocomplete list (optional)

Key autoCompleteList contain list of autocomplete field Schema name in the form self custom list.

Type: array

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'autoCompleteList' => [
                    'Product Items',
                    'Category Group',
                    'User Profile',
                    // ...
                ],
                // ...
            ],
        ],
    ],
];

Preview status (optional)

Key previewStatus contain status for preview file content on hover icon in the form.

Variants: true(default) or false

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'previewStatus' => true,
                // ...
            ],
        ],
    ],
];

Can delete (optional)

Key canDelete contain status for delete schema from the form.

Variants: true(default) or false

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'canDelete' => true,
                // ...
            ],
        ],
    ],
];

Parse data base (optional)

Key parseDataBase contain list of target for extend schema name list from database.

Variants: array with values:

• autocomplete
• fakeCache

Default empty;

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'parseDataBase' => ['autocomplete','fakeCache'],
                // ...
            ],
        ],
    ],
];

Commands (optional)

Key commands contain list cli command for call before generate any file.
command make use of the {{variable}} in the command string ( see Marks )

Example: generate gii model for table name from schema name before generate fileContent

Default empty;

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'commands' => [
                    'php ../../yii gii/model --tableName={{snake_case}} --modelClass={{PascalCase}}' // ... 
                ],
                // ...
            ],
        ],
    ],
];

Events (optional)

Make use of the eventHandlers key to add a behavior to the module.

Example: add behavior FileCrafterBehavior to the module

Default null;

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
        'options' => [
                // ... 
                'eventHandlers' => FileCrafterBehavior::class,
                // ...
            ],
        ],
    ],
];

Before init

CrafterEvent::BEFORE_INIT before init module

After init

CrafterEvent::AFTER_INIT after init module

Come events has special properties...

Before generate

CrafterEventGenerate::BEFORE before generate all files

//class FileCrafterBehavior extends Behavior
public function beforeGenerate(CrafterEventGenerate $crafterEventGenerate): void {
    Yii::info([ 'Generated files', [
        $crafterEventGenerate->files // empty (call before generate)
    ]]); 
}

Before command

CrafterEventCommand::BEFORE before run cli command

//class FileCrafterBehavior extends Behavior
public function beforeCommand(CrafterEventCommand $crafterEventCommand): void {
       Yii::error([ __METHOD__, [
        $crafterEventCommand->cmd->exec,
        $crafterEventCommand->cmd->output, // empty (call before exec command)
        $crafterEventCommand->cmd->replaceList
    ]]);
}

Cmd

\andy87\yii2\file_crafter\components\models\Dto

• string $exec - exec command
• string $output - exec output
• array $replaceList - replace map

After command

CrafterEventCommand::AFTER after run cli command

//class FileCrafterBehavior extends Behavior
public function afterCommand(CrafterEventCommand $crafterEventCommand): void {
    Yii::error([ __METHOD__, [
        $crafterEventCommand->cmd->exec,
        $crafterEventCommand->cmd->output, // output command
        $crafterEventCommand->cmd->replaceList
    ]]);
}

Before render

CrafterEventRender::BEFORE before render file

//class FileCrafterBehavior extends Behavior
public function beforeRender(CrafterEventRender $crafterEventRender): void {
    Yii::error([ __METHOD__, [
        $crafterEventRender->schema,
        $crafterEventRender->sourcePath,
        $crafterEventRender->generatePath,
        $crafterEventRender->replaceList,
        $crafterEventRender->content // empty (call before render file)
    ]]);
}

After render

CrafterEventRender::AFTER after render file

//class FileCrafterBehavior extends Behavior
public function afterRender(CrafterEventRender $crafterEventRender): void {
    Yii::error([ __METHOD__, [
        $crafterEventRender->schema,
        $crafterEventRender->sourcePath,
        $crafterEventRender->generatePath,
        $crafterEventRender->replaceList,
        $crafterEventRender->content // content file
    ]]);
}

After generate

CrafterEventGenerate::AFTER after generate all files

public function afterGenerate(CrafterEventGenerate $crafterEventGenerate): void {
    Yii::info([ 'Generated files', [
        $crafterEventGenerate->files // CodeFile[]
    ]]); 
}

Packagist