Download the PHP package zfcampus/zf-console without Composer

On this page you can find all versions of the php package zfcampus/zf-console. 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 zf-console

ZF\Console: Console Tool Helper

Repository abandoned 2019-12-05

This repository is no longer maintained. Other projects in the ecosystem, such as symfony/console, provide more robust and flexible solutions, and we recommend users target those runtimes instead.

Build Status Coverage Status

Introduction

zf-console provides functionality on top of Zend\Console, specifically a methodology for creating standalone PHP console applications using Zend\Console's DefaultRouteMatcher. It includes built-in "help" and "version" commands, and colorization (via Zend\Console), as well as support for shell autocompletion.

Requirements

Please see the composer.json file.

Installation

Run the following composer command:

Alternately, manually add the following to your composer.json, in the require section:

And then run composer update to ensure the module is installed.

Creating an application

Console applications written with zf-console consist of:

Defining console routes

Routes in zf-console are typically configuration driven. Each route is an associative array consisting of the following members:

Alternately, you can create a ZF\Console\Route instance. The signature is similar:

When defining routes, you will need to provide either an array or Traversable object of route configuration arrays or Route instances (they can be mixed).

We suggest putting your routes in a configuration file:

On Routes

ZF\Console\Route is an extension of Zend\Console\RouteMatcher\DefaultRouteMatcher, and follows its rules for route definitions and matching. In general, a route string will consist of:

  • Literal parameters (literal strings to match; e.g., build)
  • Literal flags (e.g., --help, -h, etc; flags do not have associated values)
  • Positional value parameters (named captures that do not use flags; e.g., <email>)
  • Value flag parameters (aka long options, with associated values; e.g., '--target=')

Most parameters may be made optional by surrounding them with brackets (e.g., [--target=], [<command>]).

For a full overview of how to create route specification strings, please review the ZF2 console routes documentation.

Route definitions

Note that, by default, the route name will be prefixed to the route you pass. In the example above, the build route becomes build <package> [--target=]. If you wish to be explicit, you can include the command name in your route definition yourself, or pass the prepend_command_to_route flag with a boolean false value to disable prepending the command name.

Prepending is done to make explicit the idea the mapping of the command name to the route -- which is particularly prudent when considering usage of the help system (which is command centric).

Mapping routes to callables

In order to execute commands, you will need to map route names to code that will dispatch them. ZF\Console\Dispatcher provides the ability to define such a map, via its map() method:

The $callable argument may be any PHP callable. Additionally, you may provide a string class name, so long as that class can be instantiated without constructor arguments, and so long as it defines an __invoke() method.

All callables should expect up to two arguments:

Additionally, callables should return an integer status to use as the application's exit status; a 0 indicates success, while anything else indicates a failure.

Callables may be defined in route configuration

As noted in the previous section, you can also provide the callable for handling the route via the handler key of your route configuration. The same rules apply to that argument as for the map() method.

Any callables mapped directly to the Dispatcher instance will be preferred over those passed via configuration.

Creating and running the application

Creating the application consists of

For the following example, we'll assume that the classes My\SelfUpdate and My\Build are autoloadable, and each define the method __invoke().

Features

zf-console provides a number of features "out of the box." These include:

Usage reporting may be observed by executing an application with no arguments, or with only the help argument:

Help reporting for individual commands may be observed by executing script help <command name>:

Name routes after the command

We recommend naming routes after the command name. In part, this simplifies finding the matching route definition, but more importantly: if a user specifies the command, but does not specify valid arguments for it, the command will be used to provide a help usage message for that route.

As an example, in the above, if I typed script.php build without any additional arguments, the usage message for the build command will be displayed, since the command and route name match.

Version reporting can be observed by executing script --version or script -v:

You can override the default behavior in several ways.

First, you can override either of the help or version commands by mapping them in your Dispatcher instance prior to creating your Application instance:

Second, you can set both custom banners and footers for the usage and help messages using the setBanner() and/or setFooter() methods of the Application instance. Each accepts either a string message, or a callable that to invoke in order to display the message; if using a callable, it will be passed the Console instance as the sole argument.

Disabling banners

The banner is shown by default. In some cases, you may not want to display it; e.g., when piping output to another process.

Starting with version 1.3.0, you can disable banner output using:

Additionally, starting with 1.3.0, you can explicitly nullify both the banner and footer:

Autocompletion

Autocompletion is a useful feature of many login shells. zf-console provides autocompletion support for bash, zsh, and any shell that understands autocompletion rules in a similar fashion. Rules are generated per-script, using the autocomplete command:

Running this will output a shell script that you can save and add to your toolchain; the script itself contains information on how to save it and add it to your shell. In most cases, this will look something like:

where {script} is the name of the command, and {your_shell_rc} is the location of your shell's runtime configutation file (e.g., .bashrc, .zshrc).

Dispatcher callables

The Dispatcher will invoke the callable associated with a given route by calling it with two arguments:

In most cases, you will use the Route instance to gather arguments passed to the application, and the Console instance to provide any feedback or to prompt for any additional information.

The Route instance contains several methods of interest:

Custom dispatchers

  • Since 1.3.0

You may create a custom dispatcher by implementing ZF\Console\DispatcherInterface, which defines the following methods:

When you do, instantiate your custom dispatcher and pass it to the Application instance when initializing it:

Pulling commands from a container

  • Since 1.3.0

Instead of specifying a callable or a class name for a command handler, you may store your handlers within a dependency injection container compatible with the PSR-11 specification; when you do so, you can specify the service name of the handler instead.

To do this, you will need to create a Dispatcher instance, passing it the container you are using at instantiation:

From there, you can configure routes using the service name (which is often a class name):

Finally, do not forget to pass your dispatcher to your application when you initialize it:

In the above examples, when the hello route is matched, the Dispatcher will attempt to pull the HelloCommand service from the container prior to dispatching it.

Exception Handling

zf-console provides exception handling by default, via ZF\Console\ExceptionHandler. When your console application raises an exception, this handler will provide a "pretty" view of the error, instead of the full stack trace (unless you want to include the stack trace in your view!).

The default message looks like the following:

where :className will be filled with the exception's class name, and message will contain the exception message, if any.

You may provide your own template if desired:

The following template variables are defined:

If you want to provide your own exception handler, you may do so by providing any PHP callable to the setExceptionHandler() method:

Debug mode

If you want normal PHP stack traces and error reporting, you can put the application into debug mode:

Using zf-console in Zend Framework 2 Applications

While Zend Framework 2 integrates console functionality into the MVC, you may want to write scripts that do not use the MVC. For instance, it may be easier to write an application-specific script without going through the hoops of creating a controller, adding console configuration, etc. However, you will likely still want access to services provided within modules, and also want the ability to honor service and configuration overrides.

To do this, you will need to bootstrap your application first. We'll assume you're putting your script in your application's bin/ directory for this example.

Essentially, you're calling Zend\Mvc\Application::init(), but not it's run() method. This ensures all modules are bootstrapped, which means all configuration is loaded and merged, all services are wired, and all listeners are attached. You then pull relevant services from the ServiceManager and pass them to your console callbacks.

Best Practices

We recommend the following practices when creating applications using zf-console.

Use Zend\Console to create output

Use Zend\Console to create any output you send. This ensures that the output works cross-platform (including Unix-like systems and Windows). As examples:

Install your script via Composer

You can tell Composer to install your script in the vendor/bin/ directory, making it trivial for end-users to locate and execute your script within their own applications.

If you do this, be sure to name your script uniquely.

Use filters or validators

Zend\Console's RouteMatcher sub-component allows you to specify filters and/or validators for each matched argument of a route. These let you provide normalization (filters) and more robust validation logic when desired.

As an example, consider a common scenario of using comma-separated values for an argument; you could split those into an array as follows:

Using filters and validators well, you can ensure that when your dispatch callbacks receive data, it is already sanitized and ready to use.

Filters provided by zf-console

zf-console provides several filters for your convenience:

Classes

This library defines the following classes:


All versions of zf-console with dependencies

PHP Build Version
Package Version
Requires php Version ^5.6 || ^7.0
psr/container Version ^1.0
zendframework/zend-console Version ^2.6
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 zfcampus/zf-console contains the following files

Loading the files please wait ....