README

Simple PHP tool to map your classes and methods, so you can execute them from the comfort of your command line interface.

Includes:

the core Euclid class that will handle your commands, offering a direct mode and a guided one;
a Parser, mainly to decipher direct commands;
something resembling a CRUD class to configure your commands map: set hooks to filter through methods; operate permanent or per-instance edits; save edits, possibly to another config file; etc -- the list of available commands will updated itself;
a companion class that will handle input, output and formatting, and can be used independently of Euclid;
a sample nano bin script, allowing you to edit CLI arguments before passing them to Euclid, if you do so wish.

Getting Started

Prerequisites

Very basic knowledge of CLI (CLI is awesome – like a lot of things made in the sixties)
PHP 8.0.3 (probably works with earlier versions; but untested)
Composer

Install

$ composer require ssitu/euclid

Set up a bin/euclid file, and a euclid-config.json to suit your needs. Sample files are available in samples/.

Setup

bin/euclid file:

#!/usr/bin/php
<?php
use SSITU\Euclid\EuclidCore;
if (php_sapi_name() !== 'cli') {
exit;
}
require_once  dirname(__DIR__).'/vendor/autoload.php';

$Euclid = new  EuclidCore();
// or
$Euclid = new  EuclidCore($argv);
// or
$configPath = dirname(__DIR__).'/config/euclid.json';
$Euclid = new  EuclidCore($argv, $configPath);
// or even
$EuclidMap = new  EuclidMap();
$EuclidMap->initMap($configPath);
$EuclidMap->rmvFromMap('unsetme');
$EuclidMap->updtMap('demo', 'build*', 'methodHook');
$EuclidMap->saveMap();
$argv[4] = 'something else';
$Euclid = new  EuclidCore($argv, $EuclidMap);

CLI:

$ php bin/euclid

# or to run Euclid and a command in one go (direct mode):
$ php bin/euclid classkey constrArg1 constrArg2 ->method methodArg1 methodArg2

Second case requires that EuclidCore was called with either a valid path to your config file, or an instance of EuclidMap.

CLI

Exit anytime by entering $.

Guided Mode

Easily navigate through classes and methods, and then enter arguments if any. Just follow the prompts!

1 medicis
2 igor
Pick a class > 2

1  compileCreature
Pick a method > 1

[param1] $creatureFace
Enter argument > SomeFace

[param2] $creatureBrain|opt
Enter argument >

Direct Mode

Commands will look like this:

classkey ->method
# if your class constructor has parameters:
classkey constrArg1 constrArg2 ->method
# and if your method has parameters:
classkey constrArg1 constrArg2 ->method methodArg1 methodArg2

Your list of commands is available by entering #; a nano readme by entering ?; and you can switch to guided mode with %.

Result

After passing a command: result will be displayed, and you can pick what to do next.

[class] igor
[method] compileCreature
[return] 'Creature compiled without brain.'

$ exit
* edit map
1 reset | direct mode
2 reset | guided mode
3 re-run same cmd
4 call another method of class "igor"
5 call method "compileCreature" with new arguments

Escaping Arguments

Strings

To escape strings: you can wrap them in double quotes, or if you're automating Euclid jobs you may use urlencode().

Examples:

If you need to pass $ as an argument without Euclid exiting, use quotes: "$".
In direct mode:
```
myclass ->mymethod "some string with spaces"
```
Quotes here will prevent "some string with spaces" to be considered as four different arguments.

Arrays

You can use method parseArrayArgm($array) available in EuclidCompanion, or pass them as follow:

a[]=bob&a[]=0.5&a[b]="some other bob"

It will be parsed into:

[0 =>'bob',1 => 0.5,'b' => 'some other bob']

Config

Concept

For each of your classes you wish to call from Euclid, you will need to set:

the class "key name", that will constitute the first part of your CLI command; Example: for a class named DemoDoer: its key name can be demo (or... whatever)
the class full name, preceded by any applicable namespace; Example: SSITU\Euclid\Demo\DemoDoer
optionally, a "method hook", aka a method name, or a prefix / suffix found in the names of methods you wish to target – because not all methods are meant for CLI.
- If it's a sufix, prepend your hook with an * : *yourHook;
- if it's a prefix: yourHook*.
- Example: aforementioned DemoDoer class has 3 methods: buildDirTree, buildFile, setBobName; method hook can be set to build*; setBobName will therefore not be listed in commands list.

Please note that protected and private function cannot be listed or called from CLI.

JSON File

If you have a set list of classes to call, a dedicated JSON file will be used to store their keys/names/hooks (and their auto-built list of commands).

{
"maps": {
	"demo": {
		"className": "SSITU\\Demo\\DemoDoer",
		"methodHook": "build*"
		}
	}
}

Handling

You can set up your config:

by manually editing the JSON file if you do so wish;
in CLI with Euclid (menu 'edit', key *);
or by using EuclidMap class and its CRUD-like methods.

Purposes

Well, I personally use that lib to automate my "build jobs" : compiling, editing, minifying, moving assets around, and sending me a message if something went wrong.

Contributing

Yes please! You can take a loot at CONTRIBUTING. This repo also features a Discussions tab.

License

This project is under the MIT License; cf. LICENSE for details.

ssitu / euclid

Maintainers

Details