Download the PHP package dovetaily/compio without Composer

Compio

• La version française

Descrption

Compio is an advanced component generator. It works temporarily only on Laravel with Artisan (CLI) by generating Blade components, but you can customize it to generate components from other template engines like Twig or VueJs or others.

How to install

After creating your laravel project you have "Two methods" to install Compio The two methods are:

• First method : Add a code in the `./composer.json` file.
• Second method : Add a code in the `./app/Console/Kernel.php` file.

First method

In your file ./composer.jsonyou need to paste this :

Copy it and paste it into your file ./composer.json in the key(or property) scripts.post-autoload-dump. You need to paste it like this:

Finally, run the following command in your project :

If the script Compio\\ComposerScripts::postAutoloadDump was successful, you will see in your file ./app/Console/Kernel.php a line of code that looks like this :

If you don't have this line of code in your file ./app/Console/Kernel.php, make sure the method commands exists and there is this line of code require base_path('routes/console.php'); and then re-run the command composer dump-autoload in the console.

If all in all your file still hasn't added this require_once getcwd() . '\vendor\dovetaily\compio\src\Environments\Laravel\...';, then try the second method.

If all goes well, a configuration file Compio with the minimum possible configuration will be created. Here is the content of this configuration file :

Everything concerning the customization of component generations will be done in this configuration file and will be explained later. Finish for the First method !

Second method

In this second method, you will paste the code corresponding to your Laravel version into your file ./app/Console/Kernel.php in the commands.

Your ./app/Console/Kernel.php file will look like this :

Finish for the Second Method !

Finishing the installation

If you are trying one or both methods, run the command php artisan list as follows to confirm that Compio is working:

If you have tried both methods and you do not have this result, then please check your version Laravel if it conforms to the versions supported by Compio.

How to use

Compio is very easy to use. When Compio generates a component it creates by default 4 file templates including :

• A file for the php class in the folder ./app/View/Components/
• A file for rendering (Blade by default) in the folder ./resources/views/components/
• A js file in the folder ./public/js/components/
• A css file in the folder ./public/css/components/

However, you can customize the folder paths or select the generated template or more, create your own generated templates.

There are two ways to use Compio.

• 1 - Direct use with the console.
• 2 - Use with a configuration file.

1 - Direct use with the console

Let's see the Compio command in depth.

The command usage looks like this :

• <name> : The name of your component, according to the regular expression /^[a-z_]+[a-z0-9\/_]+$|^[a-z_]$/i(or again /^\#([a-z]+)\|([^|]+)$/i but this expression will be seen in the use with a configuration file).
• <arguments> : The arguments of your class and this entry is not mandatory, you can leave it out.

Let's illustrate this with the example above :

The command php artisan compio:component Path/MyComponent string:my_string_type_argument="Default value" array:null:my_array_or_null_type_argument_2= my_argument_require_3 receives all component information on a single line, but you can also run it as follows :

Let's see the generated files

File my_project\app\View\Components\Path\MyComponent.php

On the following line :

Let's analyze the generated arguments :

• string:my_string_type_argument="Default value" : Typed argument with a default value.
• array:null:my_array_or_null_type_argument_2= : Typed argument with default value null.
  If you enter your arguments in the input Put your arguments :, you must enter the value null(like this array:null:my_array_or_null_type_argument_2=null)
• my_argument_require_3 : Mandatory untyped argument.

File my_project\resources\views\components\Path\MyComponent.blade.php

File my_project\public\css\components\Path\MyComponent.css

File my_project\public\js\components\Path\MyComponent.js

2 - Use with a configuration file

In this section, we will use data from a configuration file. During the installation of Compio when all goes well, it generates a configuration file ./my_project/config/compio.php if it is not created please create it, and to configure what affects the generations of the components, add the key component and inside you add the key there config and for a minimum rendering of the configuration, it will give this :

A. Utiliser simplement le fichier de configuration pour générer plusieurs composants

So we have component.config, and before seeing the possible compio configurations in point 'B' , we will first see how to generate several components at the same time. Please add the key where the list of your generated components will be stored, it can be named as you wish but cannot contain the symbol |. So for an example we will add the key datas and the structure will become component.datas. And we're going to put our components there.

Now that the configuration file has components to generate, we'll run the following command php artisan compio:component "#config|[config_keys]". The entry [config_keys] will be the configuration path to the components key like when we use config([config_keys]) Laravel's helper function :

Namely, we will see the parameters (arguments) of the __construct component method Cards/Post/User to understand the default values of the arguments : File C:\Path\...\my_project\app\View\Components\Cards\Post\User.php

B. Possible compio configurations

Here are the main keys of compio for a good personal management of the library :

As you may have noticed, when you generate a component, there are four files that are created and these files correspond to the number of templates that there are in component.config.template(class, render, css and js). Before seeing how to Add, Stop or Modify Templates , we will first see the keys component.config.require_template and component.config.replace_component_exist

The key component.config.require_template

When you run a command to generate a component, it does not ask you which generated template, it automatically generates 4 template files predefined by Compio.

The key component.config.require_template only accepts values of type : bool

• If the key component.config.require_template is false (default key value) : you have no way to choose which generated template.
• If the key component.config.require_template is true : you can choose which generated template.

We will see an example when the key component.config.require_template is true.

And in the console :

And that's when for the key 'require_template' => true. When it is false, the generation process will be done as in the examples above.

The key component.config.replace_component_exist

This key gives us a way to Replace, Ignore or Choose, a component that already exists.

The key component.config.replace_component_exist only accepts values of type : bool|null

• If the key component.config.replace_component_exist is null (default key value) : during the process it will ask you to Choose if you want to regenerate the component (it will only ask you if it finds the template of class) and you will have to choose which template to regenerate.
• If the key component.config.replace_component_exist is true: whenever a component already exists, it will automatically Replace.
• If the key component.config.replace_component_exist is false: If a component already exists, it will automatically Ignore(this component will not be regenerated).

Example if component.config.replace_component_exist is null

Example if component.config.replace_component_exist is true

Example if component.config.replace_component_exist is false

You can also configure it directly on the command line with the option --replace.

The key to templates (component.config.template)

This key has default templates including :

• `class`
• `render`
• `css`
• `js`

The template class

The Compio configuration values for this template are :

• The key path (type string|array) : this is the folder where the generated files will be stored.
• The key template_file (type string) : this is the template file to generate components (it can be a .txt, .php,... or other file). And the function dirname(__DIR__) is in the Compio class.
• The key generate (type bool) : if it is false, the template will not be generated and if it is true it will be the opposite.
• The key convert_case (type string|callable) : convert the short path name of your component name(default value lower).
• The key keywords (type array): these are the keywords found in the template file (you will see their usefulness in the template file).

Here's how the default template file(template_file) looks like :

We now clearly observe the keywords @command, @namespace, @class_name, @locate_css, @locate_js, @locate_render, @args_init, @args_params, @args_construct and @args_render

• The keyword @command : the command to generate the same component.
• The keyword @namespace : the namesapce.
• The keyword @class_name : the class name.
• The keyword @locate_css : the path of the css file.
• The keyword @locate_js : the path of the js file.
• The keyword @locate_render : the path to the render file.
• The keyword @args_init : the argument initialization zone as a property of the class.
• The keyword @args_params : structuring the arguments in the method __construct.
• The keyword @args_construct : assignment of arguments in class properties.
• The keyword @args_render : data to pass to rendering.

You can customize the keywords to return what you need. Example :

Anything you put as text in a keyword will be replaced in the same keyword in the template file, but the keyword can contain a callback function, like this :

Namely, here is the argument structure of the callback function :

Le modèle render

The Compio configuration values for this template are :

• The key path (type string|array) : refer to the template class.
• The key file_extension (type string) : define the extension of your file (it can also be defined in the template class).
• The key short_path (type string) : it serves as a shortcut path for the keyword @locate_render in the template class (not used in the template class).
• The key template_file (type string) : refer to the template class.
• The key generate (type bool) : refer to the template class.
• The key keywords (type array): refer to the template class.

Here's how the default template file(template_file) looks like:

In this template file, there are two new keywords including @component_name and @class_html.

• The keyword @component_name : the name of the component merged with its path.
• The keyword @class_html : a random HTML class merged with the component name.

Let's see what these keywords contain :

Le modèle css

The Compio configuration values for this template are :

• The key path (type string|array) : refer to the template class.
• The key file_extension (type string) : refer to the template render.
• The key short_path (type string) : it serves as a shortcut path for the keyword @locate_css in the template class.
• The key template_file (type string) : refer to the template class.
• The key generate (type bool) : refer to the template class.
• The key keywords (type array): refer to the template class.

Here's how the default template file(template_file) looks like :

Le modèle js

The Compio configuration values for this template are:

• The key path (type string|array) : refer to the template class.
• The key file_extension (type string) : refer to the template render.
• The key short_path (type string) : it serves as a shortcut path for the keyword @locate_js in the template class.
• The key template_file (type string) : refer to the template class.
• The key generate (type bool) : refer to the template class.
• The key keywords (type array): refer to the template class.

Here's how the default template file(template_file) looks like :

Create your own templates

The creation of the templates is very simple, let's start by making a new configuration. To add your own template, you must place it in the key component.config.template.my_template

By following this structure you have the possibility to create your own templates. If you create a template from the name of the templates that already exist (eg class, render, css and js), you will have the default values for this template. The templates class, render, css and js are automatically generated by Compio, to prevent this you will need to set their key generate to the value false, like this:

The keywords in depth

You should know that you can also create your own keywords component.config.template.my_template.keywords.my_own_keyword Default keywords already has values including :

And when you create your keyword, it will be merged with the default value of keywords.

You can also get your arguments as a keyword, as follows @args[argument key][string template] In the template text you can write whatever you want and combine it with the argument information :

Now let's see how to create a keyword. The instructions are simple to have a keyword you must respect : 1 - The regular expression /^@([a-z_]+.*|[a-z_]+|[a-z_])$/i 2 - The value of your default value must be of type string|closure. The closure must return a value of type string|null. Example :

Apply different configurations in multiple components

By using the configuration file to generate several components, you will be able to apply different configurations for each of them.