Download the PHP package tarsana/command without Composer
On this page you can find all versions of the php package tarsana/command. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download tarsana/command
More information about tarsana/command
Files in tarsana/command
Package command
Short Description A framework to build command line applications and share them with the world
License MIT
Informations about the package command
Tarsana Command
A library to build command line applications using PHP. This is part of the Tarsana Project.
Table of Contents
-
Installation
-
Your First Command
-
Initializing The Command
-
Showing The Help And Version Of A Command
-
Reading & Writing to The Console
-
Defining Arguments and Options
- Reading Arguments and Options Interactively Since version 1.1.0
-
Handeling The Filesystem
-
Loading Configuration New on version 1.2.0
-
Rendering Templates
-
Adding SubCommands
-
Testing Commands
-
What's Next
- Development Notes
Installation
Install it using Composer
Your First Command
Let's write a "Hello World" command. Create a file hello.php
with the following content:
Then run it from the terminal:
Congratulations, you have just written your first command :D
As you see, Tarsana\Command\Command
is a class providing the basic features of a command. Every command should extend it and implement the execute()
method.
Initializing The Command
In addition, Command
gives the init()
method which is used the initialize the command general attributes. Let's rewrite our HelloWorld
command:
Here we are overriding the init()
method to define the command name, version and description.
Note that the setter of an attribute foo
is named foo()
instead of setFoo()
. I know that this is not a common convention but it makes sense for me. :P
Showing the Help and Version of a Command
To show the version of a command, we use the --version
flag (we will learn after that this is actually a sub command). We also have the --help
to show the help message:
Reading & Writing to the Console
The attribute console
is used to handle the reading and writing operations to the console.
Let's update our command to read the user name:
- The
readLine()
method reads a line from the stdin and returns it as string. - The
out()
method writes some text tostdout
(without a line break). - The
line()
method writes some text tostdout
and adds a line break. - The
error()
method writes some text tostderr
and adds a line break.
The Console
class provides some tags
to control the output:
The <background:$number>
and <color:$number>
tags allows to set the background and foreground colors of the text to be written; the <reset>
tag resets the default values. The colors are given as numbers from the 256-color mode.
List of supported tags
<color:$n>
: Sets the foreground text to the color$n
in 256-color mode.<background:$n>
: Sets the foreground text to the color$n
in 256-color mode.<reset>
: Resets the formatting default values.<bold>
: Makes the text bold.<underline>
: Underlines the text.
Console
allows you also to define styles using aliases:
Predefined aliases are:
Note: tags and aliases can be used in all strings printed to the console, including the command and arguments descriptions.
Defining Arguments and Options
The command syntax is defined using the Syntax library. Let's start with a command that repeats a word a number of times:
We are using the method syntax()
to define the syntax of arguments. The string given to this method follows the rules described here
The describe()
method is used to describe an argument.
When you define the syntax of the command; arguments are parsed automatically and available in the execute()
method via the args
attribute.
The help
subcommand shows full description of the arguments and options:
And the result is:
In the second example, the count
argument takes automatically its default value.
Warning: Giving wrong arguments generates an error
Reading Arguments and Options Interactively
Some commands can have long and complicated list of arguments. Defining the syntax of such command is easy thanks to Syntax but typing the arguments in the command line becomes challenging.
Let's take the following command for example:
if you run the command using the -i
flag, it will let you enter the arguments interactively:
After reading all args, the command will show the command line version of the entered args:
which means that running
would produce the same result.
Handling The Filesystem
The fs
attribute is an instance of Tarsana\IO\Filesystem
that you can use to handle files and directories. Read the documentation for the full API.
By default, the Filesystem
instance points to the directory from which the command is run. You can also initialize it to any directory you want:
Loading Configuration
In addition to the command line arguments, the user can provide data to your command via configuration files. This is useful because it lets you define a default configuration file and lets the user change some values with a custom configuration file.
Let's write an example command which have a global configuration file at /home/user/.config.json
. It lets the user customize value via the file config.json
in the current directory:
-
The method
configPaths
take a list of paths, loads them and merges them into one configuration (it usearray_replace_recursive
internally). - The method
config
is used to retreive configuration values.
Note that:
-
Only
json
files are supported as configuration files for the moment. Please open an issue or make a Pull Request to add other formats. -
configPaths
will silently ignore paths which does not exist in the filesystem. - A subcommand will always have the same configuration data as its parent command, unless
configPaths
is used to override it.
Rendering Templates
The Command
class gives also possibility to render templates. The default template engine is Twig but you can use your favorite one by implementing the interfaces TemplateLoaderInterface
and TemplateInterface
.
Let's make a command which renders a simple template. For this we will create two files:
hello.twig
This is a simple template that print a hello message.
render-hello.php
Result
Adding SubCommands
You can add subcommands while initializing your command.
Now when you run
The FooCommand
will be run with other arguments here
as arguments.
Note: subcommands will always have the attributes console
, fs
and templatesLoader
pointing to the same objects as their parent, as long as you don't change them explicitly in the subcommand's code.
Testing Commands
The class Tarsana\Tester\CommandTestCase
extends PHPUnit\Framework\TestCase
and adds useful methods to test Tarsana Commands.
Testing the Input and Output
Let's write a test for our HelloWorld
command above which reads the user name than shows the hello message.
Sets the content of the standard input of the command.
Runs the command $c
with the standard input and $args
then stores its outputs for further assertions.
-
printsExactly
asserts that the standard output of the command equals$text
. Note that tags are not applied to allow testing them easily. -
prints
asserts that the standard output of the command contains$text
. printsError
asserts that error output of the command contains$text
.
Testing the Arguments and Options
Let's now test the RepeatCommand
above.
Assert that the parsed arguments and options of the command are equal to the given values.
Testing the Filesystem
Let's take the following command:
The test can be written as follows:
The CommandTestCase
run the command with a virtual filesystem. The methods havingFile
and havingDir
can be used to create files and directories on that filesystem before running the command.
What's Next
Please take a look at the examples in the examples
directory, and try using the library to build some awesome commands. Any feedback is welcome!
Development Notes
-
Version 2.0.0 Tarsana Command now uses PHPUnit 9 and thus requires PHP 7.3 or PHP 7.4.
-
Version 1.2.1 The
CommandTestCase
is now an abstract class to avoid PHPUnit warnings. -
Version 1.2.0 Commands can now load configuration from multiple JSON files.
-
Version 1.1.1 Fixed a bug with subcommands not having the default
--help
,--version
and-i
subcommands. -
Version 1.1.0 The flag
-i
added to commands to enable interactive reading of arguments and options. -
Version 1.0.1 Fixed a bug of subcommands having different instances of
fs
andtemplatesLoader
from their parent. - Version 1.0.0 The first version is finally out; have fun!
All versions of command with dependencies
tarsana/io Version ^2.0
tarsana/syntax Version ^2.0
twig/twig Version ^2.4