Yii2 File Crafter

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 `bash composer update `

- - - - -

Config

Config in the configuration file.

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

Minimum config `php $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 `php $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}} --ns="common\models" --interactive=0' //... 
            ],
            'eventHandler' => 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
<small style="color: #009; font-size:9px">(optional)</small>

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: `php $config['modules']['gii'] = [

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

]; `

Source
<small style="color: #009; font-size:9px">(optional)</small>

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: `php $config['modules']['gii'] = [

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

]; `

Templates
<small style="color: #900; font-size:9px">(required)</small>

Array with groups of templates for use on generate files.
`php [

['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
<small style="color: #009; font-size:9px">(optional)</small>

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
`php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'custom_fields' => [
                'singular' => 'one',
                'plural' => 'many',
            ],
            // ...
        ],
    ],
]

]; with template:php 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 `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 `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)
`php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'autoCompleteStatus' => true,
            // ...
        ],
    ],
],

]; `

Autocomplete list
<small style="color: #009; font-size:9px">(optional)</small>

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

Type: array
`php $config['modules']['gii'] = [

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

]; `

<h2 align="center">Preview status
<small style="color: #009; font-size:9px">(optional)</small> 

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

Variants: true(default) or false
`php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'previewStatus' => true,
            // ...
        ],
    ],
],

]; `

<h2 align="center">Can delete
<small style="color: #009; font-size:9px">(optional)</small> 

Key canDelete contain status for delete schema from the form.

Variants: true(default) or false `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'canDelete' => true,
            // ...
        ],
    ],
],

]; `

Parse data base
<small style="color: #009; font-size:9px">(optional)</small>

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

Variants: array with values:

• autocomplete
• fakeCache

Default empty; `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'parseDataBase' => ['autocomplete','fakeCache'],
            // ...
        ],
    ],
],

]; `

Commands
<small style="color: #009; font-size:9px">(optional)</small>

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; `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'commands' => [
                'php yii gii/model --tableName={{snake_case}} --modelClass={{PascalCase}} --ns="common\models"  --interactive=0 --overwrite=1' // ... 
            ],
            // ...
        ],
    ],
],

]; `

Events
<small style="color: #009; font-size:9px">(optional)</small>

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

Example: add behavior FileCrafterBehavior to the module

Default null; `php $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