MinimaPHP is a PHP console micro-framework for quickly creating fast general purpose command-line scripts, usually to automate boring tasks, using the PHP tools you're already familiar with. Minima provides easy helpers to interact with the CLI I/O, making it a breeze to build powerful and dynamic scripts.
<?php
require_once 'minima.php';
Command::main(function () {
$this->info('Welcome to MinimaPHP!');
});The main benefit of using MinimaPHP is that it has zero dependencies. You thus don't need to bother with Composer or autoloading. Just include the single compact minima.php file, and you're ready to go. That's right, you don't even need a Phar, because Minima is tiny (< 10Kb).
Since Minima is designed for scripting, the philosophy is that your Minima projects don't need to be pretty, they just need to do the thing you want them to do. If all you're doing is formatting some files, or compiling a file to a standalone executable, who cares if the code looks ugly, as long as it works! Just bodge something together, then call it a day.
Copy the minima.php file to your project, include it from your main script. You're done.
If you want, you can install the global Minima binary. It's a script written in MinimaPHP, and allows you to quickly scaffold new projects.
curl https://raw.githubusercontent.com/caendesilva/MinimaPHP/main/bin/minima -o minima
chmod +x minima
mv minima /usr/local/bin/minimaYou can then call the command from anywhere, like this:
minima new my-projectWrite your logic in a closure through the Command::main() method or the main() function. You will then be able to access all the helpers through the $this variable.
<?php
require_once 'minima.php';
Command::main(function (): void {
$this->info('Welcome to MinimaPHP!');
});If you prefer functional code, we've got it covered. Here's a simple one-line procedural script to get the current time:
exit(main(fn () => $this->info('The time is: ' . date('c'))));If your closure function returns an exit code, the main method/function will return that as well. You can then use this to set the exit code for your script:
exit(Command::main(function (): int {
return 1;
}));Minima is designed to abstract away the lower level I/O calls, and using these helpers is what makes the framework helpful, compared to having to deal with these yourself.
$this->write('This is written "inline" to the output');
$this->line('This writes the string to the output, then adds a newline.');These helpers will write a line using predefined colours.
$this->info('info');
$this->warning('warning');
$this->error('error');You can also use Symfony-XML-style colours when using the formatted helper:
$this->formatted('<info>Welcome to MinimaPHP!</info> <comment>Star us on GitHub?</comment>');<info><warning><error><comment><reset>
You can also use </> to close any tag.
You can fluently access ANSI colour codes using the bundled ANSI interface:
interface ANSI {
const BLACK = "\033[30m";
const RED = "\033[31m";
const GREEN = "\033[32m";
const YELLOW = "\033[33m";
const BLUE = "\033[34m";
const MAGENTA = "\033[35m";
const CYAN = "\033[36m";
const WHITE = "\033[37m";
const GRAY = "\033[90m";
const RESET = "\033[0m";
}
$this->line(ANSI::GREEN . $message . ANSI::RESET);Use the ask helper to write the prompt to the console, and return the collected input.
$this->line('Hello ' . $this->ask('Name'));You can also specify a default value by setting the second parameter of the ask helper.
Minima also makes it easy to access arguments and options passed to the command.
Options are defined as any argument starting with - or -- like any of the following:
php my-script.php -v --help --foo=barThese types of arguments are generally optional, hence the name, and when not supplied with any extra data like the foo=bar example, are usually used as boolean flags.
Arguments are generally required, and can either be positional, or keyed.
php my-script.php example bar=bazIf your argument contains spaces, you must quote them, otherwise the parser considers them to be separate arguments.
Options can be accessed using the options array, and arguments using the arguments array. You can also access them through the options() and arguments() methods.
Command::main(function () {
$this->info('Here is the data you passed to the command:');
$this->line('Options: ' . implode(', ', $this->options));
$this->line('Arguments: ' . implode(', ', $this->arguments));
});Options will be returned as a list like this, where the option name is used as the array key, with the value as the value. If your option is a boolean flag, the value will be set to true.
// --help -v --foo=bar
['help' => true, 'v' => true, 'foo' => 'bar']Likewise, arguments accessed through the method are also in an associative array, but here, if the argument has no assigned value (using the equals sign), it's array key will be set to it's position in the array. If the argument is associative, the array key will be the left-hand part of the argument. In both cases, the value will be the argument value.
// example foo=bar baz
[0 => 'example', 'foo' => 'bar', 2 => 'baz']Use hasArgument and hasOption to determine if the argument or option was passed to the command.
$this->hasArgument('foo'): bool;
$this->hasOption('foo'): bool;You can use the getArgument and getOption helpers to get a value from the passed input.
$this->getArgument('foo'): ?mixed);
$this->getOption('foo'): ?mixed);You can also specify a default value by setting the second parameter:
$this->line('Your name is ' . $this->getArgument('name', 'Guest'));To make your life easier, Minima comes with a few code APIs you can use to write scripts faster than ever!
The task function creates a self-contained task that does something and reports the execution time.
The benefit of using a task like this is that if you set the environment variable SKIP_TASKS to true, the command will bypass all tasks. This is useful for skipping long-running tasks when testing your script during coding.
This function takes two parameters:
$name(string) - A string that represents the name of the task.$task(callable) - A callable function that represents the task to be executed.
Command::main(function () {
task('Example Task', function () {
$this->line('Hello world!');
});
});This will print the following: (any output will be buffered and printed indented when the command is done)
Running task Example Task... Done! (took 0.01ms)
Hello world!
The tasks are made useful by being skippable. You can either do this by setting the environment variable before defining the task:
putenv('SKIP_TASKS=true');You can also pass --skip-tasks to the called command to automatically set the environment variable.
php my-script --skip-tasks