152 lines
4.2 KiB
Markdown
152 lines
4.2 KiB
Markdown
# Spark: Ignite your development workflow
|
|
|
|
Spark is a utility to help with everything from various mundane tasks to complex
|
|
database migrations and project deployment.
|
|
|
|
## Installation
|
|
|
|
System Requirements:
|
|
|
|
* PHP 8.0 or later (php-cli)
|
|
* Linux or other POSIX compatible OS. Probably. May work on MacOS!
|
|
|
|
### From dist package
|
|
|
|
Download the latest dist release from [dev.noccylabs.info](https://dev.noccylabs.info/noccy/php-spark/releases)
|
|
and extract it into a directory somewhere, such as `/tmp`:
|
|
|
|
```
|
|
$ mkdir /tmp/spark; cd /tmp/spark; unzip ~/Downloads/spark-0.1.0-dist.zip`
|
|
```
|
|
|
|
Make sure spark.phar is executable, and run the installer. Then just follow the
|
|
instructions:
|
|
|
|
```
|
|
$ chmod +x spark.phar
|
|
$ ./spark.phar install
|
|
```
|
|
|
|
Afterward you will be able to call directly on `spark`, as well as optionally
|
|
the `sparkplug`, `sparker`, `sparkres` and `sparksh` aliases. You can then
|
|
install any new plugins into `~/opt/spark/plugins` and enable them in your
|
|
projects with `sparkplug --enable the.plugin.name`.
|
|
|
|
### From installer
|
|
|
|
Download the latest installer release (the one that ends in `.run`)
|
|
from [dev.noccylabs.info](https://dev.noccylabs.info/noccy/php-spark/releases)
|
|
and make it executable:
|
|
|
|
```
|
|
$ chmod +x spark-0.1.0-dist.run
|
|
$ ./spark-0.1.0-dist.run
|
|
```
|
|
|
|
Follow the instructions, select Yes when prompted to proceed with the installation.
|
|
|
|
### From source
|
|
|
|
Download the latest source release from [dev.noccylabs.info](https://dev.noccylabs.info/noccy/php-spark/releases)
|
|
and extract it into a directory somewhere, such as `~/src/spark`. You can then build spark, using spark:
|
|
|
|
```
|
|
$ unzip -d ~/src/spark spark-0.1.0-src.zip
|
|
$ cd ~/src/spark
|
|
$ bin/spark run build
|
|
```
|
|
|
|
You can now install `spark.phar` where desired, and place the `plugins` directory in
|
|
a good place. You want to add the following to your `.bashrc` or similar:
|
|
|
|
```
|
|
export SPARK_PLUGINS="<path-to-plugins-dir>"
|
|
# If you don't want to rename the .phar for some reason. Skip otherwise!
|
|
alias spark=spark.phar
|
|
# Useful aliases
|
|
alias sparksh=spark repl
|
|
alias sparkplug=spark plugins
|
|
alias sparkpipe=spark pipe
|
|
```
|
|
|
|
## Using Spark
|
|
|
|
### The easy way
|
|
|
|
To get started use the `init` command. You still need to edit the `/.spark/docker.json`
|
|
and other related files as required, but his is the *easy* way.
|
|
|
|
```
|
|
$ spark init
|
|
$ sparkplug --enable com.noccy.git
|
|
```
|
|
|
|
### The useful details
|
|
|
|
Spark expects a configuration file to either be found at `./.spark.json` or
|
|
`./.spark/spark.json` relative to the project root. The `./.spark` directory
|
|
will always be used for auxillary configuration, so the placement is fully up
|
|
to you.
|
|
|
|
On its own it doesn't do much except provide a command interface to its inside.
|
|
The magic can be found in preloading:
|
|
|
|
*spark.json*
|
|
```
|
|
{
|
|
"preload": [ "./.spark/plugins/*", "./.spark/autoload.php" ]
|
|
}
|
|
```
|
|
|
|
The preloader will go over each of the defined rules and attempt to load them
|
|
in one of two ways, if applicable:
|
|
|
|
1. Files with a `.php`-extension will be loaded directly.
|
|
2. Directories having a `sparkplug.php` file will be loaded as plugins.
|
|
|
|
The advantages of writing your extensions as flat files:
|
|
|
|
- Simple interface
|
|
- Quickly register resources for other parts of Spark
|
|
- All code evaluated on load (can be a caveat!)
|
|
|
|
The advantage of writing your extensions as plugins:
|
|
|
|
- Object-oriented interface
|
|
- Delayed evaluation of code, ensuring dependencies are loaded
|
|
- Free autoloader! The namespace and path of the plugin class will be used to
|
|
set up a Psr-4 autoloader for your code.
|
|
|
|
### Scripts
|
|
|
|
Using scripts is the simplest way to leverage Spark:
|
|
|
|
*spark.json*
|
|
```json
|
|
{
|
|
...
|
|
"scripts": {
|
|
"hello": "./.spark/hello.php",
|
|
"world": "echo 'World'",
|
|
"greet": [
|
|
"@hello",
|
|
"@world"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
- Call on other scripts by prepending `@` to the script name.
|
|
- `.php`-files are executed in-process, and as such have access to any registered
|
|
resources, resource types and plugins.
|
|
- `.phar` files are still executed out-of-process, as are any commands that don't
|
|
match a PHP callable or any other specific rule.
|
|
- Substitute shell variables using `${varname}`.
|
|
|
|
### Resources
|
|
|
|
Resources are wrappers around database connections and such, providing a cleaner
|
|
interface to its innards.
|
|
|
|
Resources are generally registered by plugins or local scripts.
|