2.0.0releasedShell

Provides access to the Symphony core from the command line.

Clone URLhttps://github.com/pointybeard/shell.git

Add as a submodulegit submodule add https://github.com/pointybeard/shell.git extensions/shell --recursive

Compatibility

2.x.x2.1.x2.2.x2.3.x2.4.x2.5.x2.6.x2.7.0
NoNoNoNo1.0No2.0.0No. Soon?

Readme

Shell Extension for Symphony CMS

The Symphony Shell extension provides access to the Symphony core from the command line.

Developers can include commands in their extensions, allowing for operations not suited to web servers. The command API gives easy access to the Symphony core framework, including database, config, authentication and logs.

Installation

This is an extension for Symphony CMS. Add it to the /extensions folder of your Symphony CMS installation, then enable it though the interface.

Requirements

This extension requires the Shell Arguments (symfony/http-foundation) library to be installed via Composer. Either require it in your main composer.json file, or run composer install on the extension/shell directory.

json "require": { "php": ">=5.6.6", "pointybeard/shell-args": "~1.0" }

Optional Setup

To simply accessing Symphony commands on the command line, we recommend you do the follow:

  1. Make the bin/symphony script executable with chmod +x extensions/shell/bin/symphony
  2. Add extensions/shell/bin/symphony to your PATH or create a symbolic link in a location that resides in the PATH e.g. /usr/local/sbin. This will allow you to call the Symphony command from anywhere.

Usage

From the shell, you can run the following command

php -f /path/to/extensions/shell/bin/symphony -- [args]

For usage information, use --usage. E.G.

php -f /path/to/extensions/shell/bin/symphony -- --usage

or, if you followed the "Optional Setup" above, just

symphony --usage

This remainder of this document assumes you have set up the extension using the "Optional Setup" steps above.

Getting Started

The Shell extension looks for commands in the bin/ folder of extensions you have installed, and also in workspace/bin/. You can see a list of commands by running symphony without any arguments. A list like this will be displayed:

Below is a list of all available commands. (use --usage for details on
executing individual commands):

   shell/hello
   shell/token

At any time you can use --usage, --help or -h to get help. If you have also specified a command (see below), you will get help for that particular command instead.

Use the -c or --command argument to run a particular command. The value provided is always [extension]/[command] or [workspace]/[command]. This extension comes with two commands out of the box: hello and token.

To run the hello command use the following:

symphony -c shell/hello

You should see output like this:

Hello! Here are the arguments you passed me.
0: 'c' => 'shell/hello'

Authentication

Some commands may require you are authenticated before you use them. To do this, either provide the name of the user you want to authenticate as with -u <username> or the auth token of that user with -t <token>. When using -u, you will be prompted to enter your password.

Writing a custom command

To write a command, create a class that implements SymphonyShellLibInterfacesCommand and place it into workspace/bin/. Alternatively, put it into the bin/ folder of any Extension. You commands will be prefixed with either workspace (if it has been placed in workspace/bin/), or by the name of the extension.

Any command you write must have a namespace starting with SymphonyShellCommand followed by the name of your extension (e.g. namespace SymphonyShellCommandMyExtension) or workspace (i.e. namespace SymphonyShellCommandWorkspace).

When implementing SymphonyShellLibInterfacesCommand, you must include a usage and run method.

Here is an example of a very basic Command called test placed in workspace/bin/:

```php <?php namespace SymphonyShellCommandWorkspace;

use SymphonyShellLib;

class Test implements LibInterfacesCommand {

public function usage()
{
    return "    usage for 'workspace/test'

Add usage information for this command." . PHP_EOL;
}

public function run()
{
    LibShell::message("Greetings. This is the test command!");
}

} ```

From within the run() method, you have full access to the Symphony core framework. For example, to get the database object, use Symphony::Database(). Anything you would normally do in an extension, you can do here (e.g. triggering delegates, accessing sections or fields).

Requiring Authentication

You can secure your commands so that anyone using it must provide Symphony user credentials. To do this, instead of implementing SymphonyShellLibInterfacesCommand, extend SymphonyShellLibAuthenticatedCommand. When you command is run, Shell will notice and force the user to provide a authentication with -u or -t.

When extending AuthenticatedCommand, you must provide an authenticate() method in your command. The simplest way is to use the hasRequiresAuthenticationTrait trait. It includes a boilerplate authenticate() method and generally is more than adequate. It will check if the user is logged in, request username and password if they are not, and throw an AuthenticationRequiredException if login ultimately fails.

Here is the same 'test' command from above, but this time it requires authentication:

```php <?php namespace SymphonyShellCommandWorkspace;

use SymphonyShellLib;

class Test extend LibAuthenticatedCommand { use LibTraitshasRequiresAuthenticationTrait;

public function usage()
{
    return "    usage for 'workspace/test'

Add usage information for this command." . PHP_EOL;
}

public function run()
{
    LibShell::message("Greetings. This is the test command!");
}

} ```

Multiple Symphony installations on the same Host

Note that if you follow the "Optional Steps" above, running symphony will always be in the context of that one particular installation.

If you run multiple sites across multiple installations of Symphony, remember that the Shell extension will work with only the installation of Symphony it itself was installed and enabled on.

A workaround to this is to use the symlink method and namespace each install.

For example, you have two sites "Banana" and "Apple". Both are separate installations of Symphony with their own databases. Symlink them using ln -s /path/to/banana/extension/shell/bin/symphony /usr/local/sbin/symphony-banana and ln -s /path/to/banana/extension/shell/bin/symphony /usr/local/sbin/symphony-apple. Now you can use this shell extension for both and know you are always in the correct context (> symphony-banana and > symphony-apple).

In the future there might be better support for running a single shell instance across all Symphony installations on a host.

Support

If you believe you have found a bug, please report it using the GitHub issue tracker, or better yet, fork the library and submit a pull request.

Contributing

We encourage you to contribute to this project. Please check out the Contributing documentation for guidelines about how to get involved.

License

"Shell Extension for Symphony CMS" is released under the MIT License.

Version history

Requires Symphony 2.6

        - Added more background colours to Message class
	        - Added 'token' command. Allows enabling, disabling and retrieval of author tokens
	        - Added `Shell::error()` and `Shell::warning()` convenience methods
	        - Added `fetch()` method to the command autoloader. Simplifies getting a list of all available commands in the system.
	        - Removed need for 'extension' or 'e' flag.
	        - Calling commands authenticate method if it extends `AuthenticatedCommand`.
	        - Using Message class to display errors.
	        - Removed `listCommands()` method
	        - Added additional call to `restore_error_handler`. In version of Symphony prior to 2.7, the Exception and Error handlers are set twice.
	        - Added exception handling around constructor to avoid problems with sessions already being started (not relevant to shell)
	        - Added `AuthenticatedCommand` class and 'hasRequiresAuthenticationTrait.php' trait to simplify the process of requiring authentication for a command.
	        - added new exception `AuthenticationRequiredException` which supports these new classes.
	        - Renamed 'test' command to 'hello'. No longer requires authentication
	        - Using `Shell::error()` when trapping a ShellException
	        - `Message::background()` and `Message::foreground()` now support `NULL`.
	        - Updated example command to use `AuthenticatedCommand` and `hasRequiresAuthenticationTrait`
	        - Move `ShellException` into `Exceptions/` folder.
	        - Moved `Lib/` into `src/`.
	        - Updated autoloader to look in `workspace/bin/` folder (#3)
	        - Using PSR4 autoloader instead of classmap
	

Requires Symphony 2.6

        - Fixed namespace for Command interface
	

Requires Symphony 2.6

        - Fixed path to the Autoloader. Removed extra : character from password prompt
	        - Refactoring of Utils::promptForInput(). Supports a default value and a Closure for validating input. Will throw exception if silent flag is true but bash is not available.
	        - Shell::message() using new Message class
	        - Added Message class which support coloured output
	

Requires Symphony 2.6

        - Refactoring of the Autoloader
	        - Updated to work with 1.0.3 of ShellArgs
	

Requires Symphony 2.6

        - Added composer autoloader
	        - Added shell-args package
	        - Added Utils::promptForInput() which supports silent input capturing. Password will no longer echo to the display when using -u
	

Symphony 2.4 only

        - Checked compatiblity with Symphony 2.4+
	        - Using namespaces.
	        - Updated command API.
	        - Using SPL autoloader for all extension classes and loading commands from other extensions
	        - Updated argument structure. Requires -c and -e before the command and extension values
	

Symphony 2.0.6 only

        - Fixed bug that ignored the '--usage' flag
	        - Added username ('-u') option, which can be used instead of '-t'
	

Symphony 2.3.1beta2 to 2.4

        - Added support for Symphony 2.3.x
	

Symphony 2.0.6 only

        - adding '--usage' after a command will trigger that commands 'usage()' function
	        - added 'Shell::listCommands([$extension])' function for listing commands in the system
	        - omitting a command will list all the commands available for that extension
	        - omitting both extension and command will list all commands in the system
	        - added "deny from all" '.htaccess' directive to the 'bin/' folder
	        - 'test' command implements 'ShellCommand::usage()'