Download the PHP package pmjones/auto-shell without Composer

On this page you can find all versions of the php package pmjones/auto-shell. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package auto-shell

AutoShell

PDS Skeleton PDS Composer Script Names

AutoShell automatically maps CLI command names to PHP command classes in a specified namespace, reflecting on a specified main method within that class to determine the argument and option values. The method parameters may be scalar values(int, float, string, bool) or arrays.

AutoShell has no dependencies and is low-maintenance. Merely adding a class to your source code, in the recognized namespace and with the recognized main method name, automatically makes it available as a command.

Think of AutoShell as the "router" for your CLI command classes:

That is:

Front Controller    => Console
Router              => Shell
Route               => Exec
Action/Controller   => Command

Getting Started

Note:

The documentation examples follow the pds/skeleton standard for directory and file names.

Installation

Install AutoShell using Composer:

Console Script

You will need a console script to run your commands. To create a console script, open a file in your project at bin/console.php and add the following code:

You will need to specify the namespace for your command classes, and the directory where those class files are saved. You can also specify help text to be shown at the top of all help output, but doing so is optional.

Now you can issue php bin/console.php and see some output:

This output is to be expected, since there are no commands yet.

Command Class

Open a file at src/Project/Cli/Command/Hello.php and add the following code:

That's all -- the command should now be available via the console script. If you issue the following ...

php bin/console.php hello world

... you should see Hello world as the output.

Note:

This example uses echo to generate output, but you can use any other output mechanism you like.

Adding Options

To enable options on the command, create a class that implements the Options marker interface, using #[Option] attributes on constructor-promoted properties. Then add that Options implementation to the main method parameters to make those options available to the command logic.

First, open a file at src/Project/Cli/Command/HelloOptions.php and add the following code:

Then in the command, add a typehinted main method parameter for the options, along with some logic for the option behavior:

Now if you issue one of the following ...

php bin/console.php hello world -u
php bin/console.php hello world --upper

... you will see Hello WORLD as the output.

Giving Help

To add help for your command, use the #[Help] attribute.

Edit the command to add #[Help] attributes on the class and its main method parameters:

Likewise, edit each #[Option] attribute to add a help parameter:

Now when you issue php bin/console.php or php bin/console.php help, you should see your command listed in the roster of commands:

Similarly, when you issue php bin/console.php help hello, you should see a manual page for your command:

Advanced Topics

Command Naming

Command class files are presumed to be named according to PSR-4 standards; further:

For example, given a base namespace of Project\Cli\Command, the command name create-article maps to the class Project\Cli\Command\CreateArticle.

Likewise, the command name schema:dump maps to the class Project\Cli\Command\Schema\Dump.

The Shell will parse the command name to find the correct class, then reflect on the "main" method in that class (typically __invoke()) to find the available options and arguments, and parse those out as well. (The Shell ignores interfaces, traits, abstract classes, and Options implementations.)

If you want to name your command classes with a suffix, specify that suffix when creating the Console object:

Command Method

By default, AutoShell reflects on __invoke() as the main method on command classes. You can change that main method when creating the Console. For example, to use exec() as the main method on commands:

Finally, your main method signature should indicate an int return for the Console exit code. Retuning 0 indicates success, whereas any other integer value indicates failure or error. See http://www.unix.com/man-page/freebsd/3/sysexits/ for common exit codes.

Command Factory

By default, the Console will just create command classes using new. This is fine for getting started, but you will likely need some form of dependency injection for your command classes. You can achieve this by setting a command factory on the Console.

To set a factory for creating command objects based on their class name, perhaps one based on psr/container, pass a $factory callable to the Console:

The Console will not use the injected factory for its own help classes; it will create those itself.

Argument Types

AutoShell recognizes main method parameter typehints of int, float, string, bool, mixed, and array, and will automatically cast values collected from the command-line invocation to their respective types.

For bool, AutoShell will case-insensitively cast these argument values to true: 1, t, true, y, yes. Similarly, it will case-insensitively cast these argument values to false: 0, f, false, n, no.

For array, AutoShell will use str_getcsv() on the argument value to generate an array. E.g., an array typehint for an argument value of a,b,c will receive ['a', 'b', 'c'].

Finally, trailing variadic parameters are also honored by AutoShell.

Option Definitions

You can define long and short options for your command by adding an #[Option] attribute to a constructor-promoted property in a class that implements the Options marker interface.

The property name can be anything you like, but must be nullable. (AutoShell indicates an option was not passed at the command line by setting it to null).

As a matter of good practice, the property should be defined as readonly, and should not have a default value, but these are not strictly necessary.

The first parameter for each #[Option] is a comma-separated list of short and long names for the option, and is required:

There are several optional named parameters for each #[Option] attribute:

Values will be cast to the property type of the #[Option].

Inside your command, you can address the option via an Options parameter on the main method:

Composing Options

Sometimes you will want to have a common set of Options used across all your commands, along with a set of Options specific to an individual command. To support this, AutoShell allows more than one Options parameter on the main method:

The only caveat to this is that Options specified later in the parameters may not have an option name defined in any earlier Options parameter.

Given the above example, this means you cannot define (e.g.) -f in both the CommonOptions and the FooOptions; you must define it on only one of them. If you define it in more than one, AutoShell will raise an OptionAlreadyDefined exception.

Extended Help

You can add extra, long-form text to the command-level Help as a second parameter. A very light markup of *bold* and _underline_ is supported.

Console Input/Output

By default, the Console writes help output to STDOUT, and writes invocation-time error messages to STDERR (such as when it cannot parse command line input).

To change where the Console writes output, pass a callable for the $stdout and/or $stderr arguments:

Please note that these callables are used only by the Console itself -- and even then, only for help and error output.

Command Input/Output

AutoShell does not require or provide any command I/O mechanisms. This means your command classes can use any I/O system you like; it is completely under your own control.

When getting started, you may wish to just use echo, printf(), and the like. However, that may become troublesome, especially when you want to begin automated testing. You will need to buffer all command output, capture it, and then read it to assert output correctness.

As an alternative, you can pass a psr/log implementation that writes to STDOUT and STDERR resource handles, such as pmjones/stdlog. Then in testing, you can instantiate the implementation with php://memory resource handles, and fread() the command output from memory.

Finally, you may wish to inject a more powerful standalone CLI input/output system. I am told league/climate is nice, but have not used it.


All versions of auto-shell with dependencies

PHP Build Version
Package Version
Requires php Version ^8.1 | ^8.2 | ^8.3
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package pmjones/auto-shell contains the following files

Loading the files please wait ....