Proposal: silverstripe-console

[robbieaverill]

silverleague/silverstripe-console

Repository: https://github.com/silverleague/silverstripe-console
Specification: https://silverleague.github.io/development/silverstripe-console

Introduction

The SilverLeague Console is a Symfony console application which interfaces directly with a SilverStripe application for a better command line experience.

Use case

The SilverStripe framework ships with a built in CLI management tool - "framework/cli-script.php". It also has a bash wrapper called "sake". This tool essentially lets you run controllers from the command line in much the same way as you would from the browser, while providing added benefits such as not having to worry about web server timeouts, being able to run in a cron task, etc.

This tool is limited. The SilverLeague console aims to replace its use with a more powerful, flexible and featured tool for managing SilverStripe applications.

Aims over other community modules

There are some existing CLI modules for SilverStripe among the community already. This module is going to be built with the following focusses:

• SilverLeague concepts first
• PHP 5.6+ minimum (in turn, PHPUnit 5.7)
• SilverStripe 4 minimum (?)
• Don't use "sake" or variations of the same, since they mean nothing to unaware developers
• Don't ship as a module that should be installed into a SilverStripe application - should run standalone

This module would not support SilverStripe 3.x at this stage. Users would be recommended to use an established console like "supersake" for legacy framework/CMS support.

Functionality

• Most importantly the console will automatically detect all BuildTask instances from the SilverStripe application and expose them as console commands
• Database build, manifest flushing: Enhancement: database build and manifest flush silverstripe-console#9
• Database management (import, dump, dev-stripping): Enhancement: database management - import, export, exclude tables silverstripe-console#5
• Asset management (import, dump): Enhancement: asset management - import, export silverstripe-console#6
• Member management (create, change password, change groups)
• Cache management (clear, inspect, clear individual areas): Enhancement: cache management - flush, inspect, remove individually silverstripe-console#4
• Config inspection - search by class name or property name: Enhancement: configuration - show all, search by class name or property silverstripe-console#3
• Module creation - initialise a new module, choose classes to extend and choose new DataObjects to create: Enhancement: module creator silverstripe-console#8
• Extensibility - ability to add custom commands to a user directory, or specific folder in a SilverStripe application to be run by the console: Enhancement: console should be extensible silverstripe-console#7
• SilverStripe Extensions - list by class name: Enhancement: list extensions of a class silverstripe-console#1
• Concrete extensions - list by class name: Enhancement: list a class's children silverstripe-console#2
• Delete DataObjects - ability to remove DataObjects by class name and ID/URL route: Enhancement: Delete DataObject by class name and URL Route/ID silverstripe-console#28
• DataObject debug output (dump) - ability to dump a DataObject by class name and ID/URL route with output formatted cleanly: Enhancement: Debug output for a DataObject silverstripe-console#29
• Discussion: Support both 3.x and 4.x versions without needing a different console version installed Removed

License

To be released under the MIT license.

[Firesphere]

Sorry, I would prefer @axyr his work here. His console module is way more complete and stable and provides a coherent CLI interface.

[dmc-core]

Debugging output and the ability to completely delete pages would be a nice touch!

[robbieaverill]

Thanks @dmc-core - I've adjusted your suggestions to be for DataObjects generally instead of Pages. Great idea.

[dmc-core]

Thinking about the db and assets export/imports could we utilise sspak as a requirement and wrap it in its own namespace? Could then pass in its expected args etc from the single cmd. Ie sspak:load [args]

[robbieaverill]

@dmc-core I like that. It would remove our database and assets command scope, and we add sspak as a command namespace which is literally a wrapper for sspak, which can be included with composer and bootstrapped accordingly

[sminnee]

How does this compare to https://github.com/axyr/silverstripe-console?

[robbieaverill]

The comparison is very similar.

I think what this proposal is trying to achieve that other consoles (cli-script/sake, supersake and sakemore), as well as sspak etc, don't already can be loosely summed up as:

• A modern [tech wise] and combined approach - use one tool that covers functionality from all others you may need
• This is not a SilverStripe module, it's a utility (do not install into the web root or the SilverStripe framework) - you install globally with composer, or we potentially compile a phar at some stage - especially since the global Symfony Console requirement conflicts with that of the upgrader tool (if installed globally as well)
• Extensibility - users can define their own commands, or write and publish their own modules that extend it
• The idea's been mooted that this console should support both SS 3 and 4 within the same utility
• Active support - the other modules appear to either be forgotten about, ignored or on a low priority

The general ideas of SilverLeague in terms of high quality code, exhibiting best practices for development/architecture, high test coverage etc apply too, but aren't necessarily unique to this console versus the others.

---

Those are pretty high level, but on a granular level, one thing this module does that supersake doesn't is the ability to see all native SS tasks and run them.

[sminnee]

This is not a SilverStripe module, it's a utility (do not install into the web root or the SilverStripe framework) - you install globally with composer, or we potentially compile a phar at some stage - especially since the global Symfony Console requirement conflicts with that of the upgrader tool (if installed globally as well)

Yeah, it's difficult (but not impossible) to make a single package that combines both use-cases. I would probably note that the approach of other tools such as phpunit has been do go the other way, and notably in SS4 you can't use the globally installed version. We've chosen this approach for a number of reasons:

• We need different versions of PHPUnit for different projects
• Developers will automatically get the packages we need by running composer update
• We can use the location of the referenced vendor/ folder to determine the BASE_PATH of the project. This has been used to good effect in letting you run silverstripe/serve and phpunit directly from the framework folder, rather than needing to "build a project structure" to develop on the framework. More generally, it helps allow for flexibility in the project structure.

To that effect, in SS4 I was keen to see both silverstripe/serve get a bit more love as a recommended dev tool, and for sake to be replaced with something provided by a separate project-specific dependency, that puts a binary into vendor/bin.

[robbieaverill]

Yeah - this module will run as a project dependency (as the others do too) and that would mean less magic for adapting multiple major SS versions in one app and instead just installing the appropriate tag for your SS version. I personally prefer tools like this to be separate from the codebase, but can see the benefits of having it bundled in with it too

[sminnee]

Presumably you might have extensions to the CLI tool that only apply to a given project. In these cases it would make sense to have the extension loaded into the project rather than globally.

You might set up an architecture where if the global tool detects that the in-project tool is installed, it defers all the commands to it. That could potentially leave the global tool quite lean, and make a cross-major-version tool more feasible without a bunch of if blocks.

[robbieaverill]

True. You could also have a global utility that looks for local modules

[axyr]

That would over complicate things...

What about commands I want to use on production?

[robbieaverill]

I guess if you have production ssh access then you would also have access to install a utility into the path. As I say though, this can currently be installed as a silverstripe dependency as well, it's just that I'd encourage against it :-)

[robbieaverill]

For reference, the Magento equilavent (which I'm trying to model this on) n98-magerun doesn't appear to encourage installation inside a Magento project, nor augment any functionality within the app (like admin interfaces). I'm not sure whether than means you couldn't install it as a composer dependency at all though

[axyr]

Checkout Laravel. There are tons of use cases you want have console commands on production.

I have several website spiders that are solely ran from scheduled commands.

Or scheduled mailers, maintenance scripts etc. Putting a site in 503.

So if I have 1 site that needs console commands, I need to install a tool global that could otherwise just als easy added as a composer dependency with the correct tag that I require for that project?

[robbieaverill]

You completely can install into your project if it suits your use case

[sminnee]

It might be helpful to elaborate on what you see as the biggest benefits of installing the tool globally. Is it about easy execution, smaller project size, ability to run commands such as "create project" that don't naturally fit into a single project, or something else?

[robbieaverill]

Here's what I see as the pros and cons of both ways:

Global install

Pros

• One installation per server/development environment (assuming the utility is cross-version supported)
• No need to include it as a project dependency (faster installs, less clutter)
• Ability to perform project agnostic tasks (for example, what sspak does and what Martijn's CLI installer does)

Cons

• If installed with composer (as opposed to a bundled application) there is the potential for version conflicts in the global composer dependencies which could prevent you from installing it (valid example - this module and silverstripe-upgrader require different major versions of Symfony console)
• If installed with composer then the composer's bin folder needs to be available in the user's PATH. This adds an extra installation step if it's not configured this way already from other installs.

In-project

Pros

• Lock each project to a specific version of the utility
• Don't worry about it being available - wherever your project goes, it will likely follow
• No need to remember to install it in a new environment as it will come with the project's composer install

Cons

• Same as the global install - potential for local composer package conflicts (in fact, it's much more likely in this instance)
• Many instances of the module on one machine if there are many projects (however, again, it's locked to the project version)

---

Both install options would be able to support local extensions to the application (within the project, or user's home folder in the environment, or both).

I think that the "preferred installation option" would probably guide a decision like "should we support multiple SilverStripe framework versions in a single app, or have different versions for each" - since you don't need the added complexity of the former if you're deploying natively into a project, and you probably do if you deploy globally.

Otherwise, I think it's largely going to come down to the preference of the developer using it - the tool supports both options already. It'd be good to choose a little more definitely which way to go, which will naturally guide the decision mentioned above re: version support.

I'm already pretty indifferent - if people want to install it into a project, that's cool, if they want to install it globally, that's fine too.

[Firesphere]

Can you get a comparison between @axyr his work and yours? This still feels to me as a "I did this, so take mine" over "This is the best solution".

[robbieaverill]

"I did this, so take mine" over "This is the best solution".

It's not like that - there wasn't a suitable module for what I wanted to do (outlined previously), and the existing consoles (there are many, not just one) aren't on offer here.

I'm mostly dubious of reinventing wheels, which is why I've tried to propose a substantial set of improvements over what any of the others offer.

[robbieaverill]

1.0.0 tagged, not all of the initial features made it in but it's got some useful ones.