Yii2 File Crafter
Yii2 File Crafter - library for generating a many templates with minimal differences
Content ¶
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}}' //...
],
'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 propertycustom_fields
onconfig
( 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 dataext
- 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 generationext
- 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}}' // ...
],
// ...
],
],
],
];
`
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[]
]]);
}
If you have any questions, please ask in the forum instead.
Signup or Login in order to comment.