2.0.2releasedShell

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.02.7.12.7.22.7.32.7.42.7.52.7.62.7.7
NoNoNoNo1.0No2.0.02.0.22.0.22.0.22.0.22.0.22.0.22.0.22.0.2

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 solution is to place the Shell extension folder outside of the Symphony CMS install, symlink the it into each extensions/ folder per install of Symphony, and provide the path to Symphony at run-time with $SYMPHONY_DOCROOT.

E.g.

One install of Symphony is called banana and another called apple. The same shell extension folder, which is in ~/source is symlink'd accordingly into the extensions folder. ``` ## ln -s ~/source/shell /var/www/symphony-banana/extensions/ SYMPHONY_DOCROOT=/var/www/symphony-banana symphony

## ln -s ~/source/shell /var/www/symphony-apple/extensions/
SYMPHONY_DOCROOT=/var/www/symphony-apple symphony

```

Using SYMPHONY_DOCROOT like this gives the Shell extension context and will load up the correct install of Symphony at run-time.

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.7

        - Added check to ensure Shell extension is enabled before proceeding. Throws ShellException if it isn't enabled (Fixes #4).
	        - Added __toString() method and moved some code from display().
	        - Removed the login() method since original limitation introduced by Symphony::login() is gone.
	        - Simplified authentication prompt message.
	        - Ran php-cs-fixer over code base to ensure PSR2 compliant formatting.
	

Requires Symphony 2.7

        - Allowing the user to overload DOCROOT at run-time with SYMPHONY_DOCROOT environment variable (Closes #6).
	        - Added checks to make sure composer autoloader exists and display nice message it it cannot be located (Closes #5)
	        - Updated Utils::promptForInput() to allow setting of the prompt character. Default is still colon (:)
	

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()'