Improve scaffolding commands

[RomainMazB]

Requests:

• Add composer.json file to create:plugin command
• Add a create:tests command
• Translation keys into stubs (Scaffolding Improvements #486)
• Generate the lang folder from command-line (Scaffolding Improvements #486)
• Add a --settings option to create:model command (Add create:settings command storm#37)
• Add a run:tests command (Add winter:test command #202)

Background

All of us would agree that the scaffolding command is a great things in WinterCMS as it is into Laravel.

I've build many plugins this last weeks and used them widely, so I wanted to give my feedback on what could and should be improved from a "plugin-creator" point of view.

Also I'd like to get some other "plugin-creators" feedback here on how the features should be implemented

---

Translation keys into stubs

The first thing that should be improved is the translation keys into controllers. Most of them are already included into the core and translated in many language. I've modified the stubs here: wintercms/storm#35

All of us need this:

• many creator will create plugin for their personal use in their native-language so they are always forced to open and modify the generated controllers' views files which are only generated in english.
• all the plugin-creators who aim to share their plugin on the marketplace want to make it usable by all the community without a regard to their language. Many plugins will be shared into english + the creator native language. I hope that the fact that the controllers actions will now be translated into the end-user native language directly from the core, it will ease its usage and invites the user to make a PR to the plugin to add his native-language translation.

[EDIT] @mjauvin pointed me out that a related feature has not been merged in the past due to the fact that it would be hard for beginners to read and modify the view file.
This should live as an option of the create:controller command:

php artisan create:controller AuthorName.PluginName ControllerName --use-translations

Add composer.json file to create:plugin command

Because the marketplace will widely rely on composer-installation (stop me if I'm wrong), the create:plugin file should create the composer.json file.

Most of us has never published a package, easing the first step is a nice-to-have and will encourage us to do so.

The composer.json file can't contain any comment. To guide the users into publishing his package on packagist, the command-line should display into the terminal a link to this page which include a "how-to" section.

---

Generate the lang folder from command-line - PR open here: wintercms/storm#36

A thing which is missing into the scaffolding commands is definitely the lang folder, I keep creating it plugin after plugin.

Because many of us will use create:plugin command to create site-specific plugin which will never be translated or may not even need user-readable text (Eg: a tiny Plugin.php file just to register to some event and process some logic), this should probably live into an option of the create:plugin command:

artisan create:plugin AuthorName.PluginName --with-lang-files

maybe this option could be filled with some extra locales that he want to translate himself:

artisan create:plugin AuthorName.PluginName --with-lang-files=en,fr,de,it

the default would be the en and [current_installation_locale] files.

Using this option, it would generates the lang folder and locale files but also include keys into the Plugin.php file:

public function pluginDetails()
{
    return [
        'name'        => 'authorname.pluginname::lang.plugin.name',
        'description' => 'authorname.pluginname::lang.plugin.description'
        //...
    ];
}

The presence of the lang folder should also be detected intocreate:model, create:component and create:reportwidget commands to generate the stub files including translation keys.

This would ease and so increase the number of translated plugins at a long term.

---

Add a --settings option to create:model command - PR open here: wintercms/storm#37

A thing that annoyed me is to create a basic model that I should almost modify totally to make it as a settings model.
The create:model command should accept a --settings option that would generate a basic settings model and not create a create_model_table.php file.

<?php namespace AuthorName\PluginName\Models;

use Winter\Storm\Database\Model;

class Settings extends Model
{
    use \Winter\Storm\Database\Traits\Validation;

    public $implement = ['System.Behaviors.SettingsModel'];

    public $settingsCode = 'authorname_pluginname_settings';

    public $settingsFields = 'fields.yaml';
}

if possible, passing this option would make the model class name optional and would default to Settings so this command would be valid:

php artisan create:model AuthorName.PluginName --settings

---

Add a create:tests command

It won't be the most used for sure but easing the creation of plugin-test will improve the community-plugins code quality at a long term and we'll all benefits from this.

This command line should generate the basic files including a passing test:

• phpunit.xml
• tests/unit/[PluginName]PluginTest.php

<?php namespace AuthorName\PluginNameTests\Unit

use PluginTestCase;

class PluginNamePluginTest extends PluginTestCase
{
    /**
     * A basic test example.
     *
     * @return void
     */
    public function testBasicTest()
    {
        $this->assertTrue(true);
    }
}

A shortcut to this could be included into create:plugin command, imagine ❤️ :

php artisan create:plugin AuthorName.PluginName --with-lang-files --with-tests

---

Add a run:tests command - PR Open here: #202

Additionally to the previous one, it was a bit annoying to go into each plugin folder to run the plugin's tests.
When I worked on some plugins that should work together, I had to make many:

• go there
• run tests from a ugly ../../../vendor/bin/phpunit
• go back there
• run tests from a ugly ../../../vendor/bin/phpunit
• and so on many times...

This command should be possible to be ran from the root:

php artisan test:plugin AuthorName.PluginName

---

End-note

I could work on all these features as soon as most of us agree on the need of these and how they should be implemented. So please plugin-creators: Give us your feedback!

Do you think about anything that you would see implemented that I'm missing or should the commands I described be implemented in another way / syntax?

[bennothommo]

@RomainMazB very good suggestions here. I'll comment on each individually:

Translation keys into stubs

As long as @LukeTowers' suggestions from the original issue on October are integrated with the PR, I'm happy with that. Anything that makes it easy to translate will be good.

Generate the lang folder from command-line

Your idea is on the right track.

I would love, if it is indeed possible, for a command which scans available language strings in a plugin's files and creates placeholder translate files that can then be easily populated with the translations. If this is too flaky/difficult, even just a command that copies a main language file (say the en/lang.php) to another language (ie. fr/lang.php) would suffice.

Add a --settings option to create:model command

Love it - this is definitely a good idea.

Add a create:tests command

Again, great idea. There's a bit of boilerplate code with the plugin tests that could definitely be made easier with a scaffold.

Add a run:tests command

OMG YES. This shits me to tears - I'm half-tempted to write this myself. I had a handy helper command with the Dusk plugin which did this already for the Dusk tests, so I would imagine it would be easily portable for the normal plugin tests.

[RomainMazB]

For the lang files, I guess a mix of our two worlds would be perfect:

• a --with-translations option that generate the lang/[current locale]/lang.php file and plugin stubs including translation keys
• a copy:lang command which should take two mandatory parameters to get the locale from and the locales to.

php artisan copy:lang PluginName.AuthorName fr en,it,de

To be perfect, this command should create the file including the keys but could also detect if the file exist and create only the missing keys.
Not sure if the corresponding values should be prefilled or blank?

Also we discussed with @mjauvin few weeks ago that it would be great if a similar command would exist for the modules translation.

Maybe this could live as a unique command and instead of author and plugin name accepts the module name:

php artisan copy:lang system en fr

For the run:tests command I'll take a look into the dusk plugin, if it's that easy I'll do the PR immediately or so.

[RomainMazB]

I've just sent a PR for the plugin:test command.
I finally renamed it to be on the good "namespace" for console command:

I did not copy anything from the dusk plugin finally: I felt it would have been too far for just a single line command:

cd plugins/author/plugin && ../../../vendor/bin/phpunit

Reviews are welcome :)

[helmutkaufmann]

This is great and it will sure help people getting started. Along with comments. Two more thing that would have been nice

• Code fragment in Plugin.php to for the inclusion of new Twig commands.
• Code fragment in Plugin.php that also creates a Snippet for inclusion in Static Pages - as many people probably use Static Pages as opposed to CMS only.

[RomainMazB]

Hi, I'm not sure this should be the default because they are not that much needed imo: I never registered a twig command with my 15 plugins.
The registerSettings is the missing one for me but even I'm not sure we should add it into the default stub.

Maybe we could add an option to the create:plugin command to add those if needed:

php artisan create:plugin AuthorName.PluginName --register=settings,twig,scheduler,commands

This would add the corresponding register command with a full example for each.

[luciandex]

Super cool suggetions/ideas.
It would be nice that generated "Settings" class will be named "PluginNameSettings".
If we have more than one Settings class include into a file, we need to made aliases... no so cool if we make refactoring in the future.
(that problem is with generated "Plugin" class too - for readibility)

[RomainMazB]

Not sure to understand the problem you want to avoid by aliasing the Settings model. Can you describe it?

To me there isn't a problem: only one Settings model is needed by plugin to access the plugin's settings. Then if you need more complex stuff that should be stored as rows/cols: you create a basic model with controller and only create a link into the settings page to access this controller.

And if you've got 5 plugins with settings into each, the namespace is clear enough to me:

use Luciandex\AwesomePlugin\Models\Settings as LuciandexSettings;
use SunLab\TrickyPlugin\Models\Settings as SunLabSettings;

[luciandex]

This is an approach (a good one), but not friendly on refactoring.
Another point of view is if we have settings into more than one plugins from same Author.

use Author\PluginOne\Models\Settings;
use Author\PluginTwo\Models\Settings;

// we can write:
use Author\PluginOne\Models\PluginOneSettings;
use Author\PluginTwo\Models\PluginTwoSettings;

We can aliasing as you suggest or as we code for the moment , but I want to avoid aliasing completely. :) (also we write less code)

Just an opinion :).

[RomainMazB]

Ok. This is true, good example 👍

But does this isn't already doable with this?

php artisan create:model AuthorName.PluginOne PluginOneSettings

The --settings option won't change anything on that.

I agree that making this as the default behavior for settings model would make this syntax more used for the future and improve readability. But this adds a complexity to the command. This is totally valid:

php artisan create:model authorname.pluginone Model

With this lowercased syntax, it's impossible to detect the good model class name.

Also I made some tests with this command improvement, and we can't make a command parameter (the model class name) required or not depending on the presence of a parameter, so the model class name will be needed. Except if we create a totally separated command like:

php artisan create:settings AuthorName.PluginName

For the Plugin.php file: even if I agree a bit on the readability, I never had to load, detect or extend a Plugin.php file. The PluginManager is easy and clear enough to work with for those kind of stuff using the plugin's code.

[tospe]

Awesome ideas.
It would be cool if the create:tests command also had the option to create dynamic tests using the https://github.com/wintercms/wn-dusk-plugin.

[RomainMazB]

We started a "debate" into a PR mentioned in this discussion. Any feedback on how localized plugins development could be improved are welcome.

Read the discussion here.