diff --git a/Build-Command.md b/Build-Command.md index e69de29..c98b112 100644 --- a/Build-Command.md +++ b/Build-Command.md @@ -0,0 +1,19 @@ +Spins up a new Docker environment for your project. + +# Command Definition + +```shell +loom spin:up [name] [path] [--options] +``` + +# Usage + +## Arguments + +| Argument | Required | Valid Options | +|----------|-----------|------------------------------------------------------------------------| +| name | ✅ | Valid string (no special characters). Full stops are allowed. | +| path | ✅ | Absolute path to your projects root, or `.` for the current directory. | + + +## Options \ No newline at end of file diff --git a/Configuration.md b/Configuration.md index f9ec2c8..3104067 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,8 +1,8 @@ By default, **Loom Spinner** spins up a pretty powerful environment all by itself, without the need for further configuration. -It is understandable however that you may need different settings for different projects. For example, maybe you're -building a CLI tool, so have no need for a webserver - you can pass the `--disable-server` option to the `spin:up` +It is understandable, however, that you may need different settings for different projects. For example, maybe you're +building a CLI tool, so have no need for a webserver; you can pass the `--disable-server` option to the `spin:up` command and the default server (Nginx) won't be installed alongside your PHP Container. This document explains the different ways to configure your project environments created with Spinner. @@ -13,6 +13,10 @@ The default configuration for Spinner environments can be found at [config/spinn in the Spinner repository. # Custom Configuration + +On the page for the build command (`spin:up`), you will have seen that you can pass options to the command which allow +you to further configure your environment. + ## Argument Priority Environment options and arguments are considered in the following priority order: @@ -27,13 +31,37 @@ the flag you passed in. ## Command Line Arguments +Please consult the table in the [All Configuration Options](#all-configuration-options) section for a list of all +available command line options. + ## Using Custom Configuration +As an alternative to passing lots of options to the `loom spin:up` command, `loom` allows you to create a configuration +file in the root of your project: `spinner.yaml` + +Your `spinner.yaml` file can contain as many or as few custom options as your project requires. For example, if you're +happy with the default settings, but you just don't need xdebug, your `spinner.yaml` file might look like this: + +```yaml +options: + environment: + php: + xdebug: false +``` + +For a full example of available options, please consult the `config/spinner.yaml` file in this repository for whichever +version you are currently using. You can also consult the table below for a list of all current available configuration +options if you are using the latest version. + ## All Configuration Options | Option | Config Key | Accepted Values | |----------------------|---------------------------------------|-------------------------------------------------------| | `--php` | `environment.php.version` | Any PHP version with a valid PHP FPM Docker Image | +| `--disable-xdebug` | `environment.php.xdebug: false` | - None in CLI
- `true`/`false` in `spinner.yaml` | +| `--database` | - | Currently only accepts: `sqlite`/`sqlite3` | | `--disable-database` | `environment.database.enabled: false` | - None in CLI
- `true`/`false` in `spinner.yaml` | +| `--disable-server` | `environment.server.enabled: false` | - None in CLI
- `true`/`false` in `spinner.yaml` | +| `--node` | `environment.node.version` | Any valid version of Node i.e. `20` | diff --git a/Debugging.md b/Debugging.md new file mode 100644 index 0000000..4a3c652 --- /dev/null +++ b/Debugging.md @@ -0,0 +1,36 @@ +# XDebug + +By default, your PHP container includes XDebug. This can be disabled for new environments by passing the +`--disable-xdebug` option to the `spin:up` command, or by setting `options.environment.php.xdebug: false` in your +projects `spinner.yaml` file. + +# Server Settings + +The following instructions are for PHPStorm, I have not tested this with other IDE's, however the settings table should +be fairly universal. + +## Server Configuration + +- `File` -> `Settings` +- `PHP` -> `Servers` -> `+` +- Give your server a name and use the values shown below. + +| Setting | Value | +|-------------------------|----------------------------------------------------------------------------------------------------------------| +| Host | 127.0.0.1 | +| Port | **Local** port **PHP** container is running on. i.e. if your docker container shows 52033:9003, use **52033**. | +| Debugger | Xdebug | +| Use path mappings? | ✅ | +| File/Directory | Select **your project root** | +| Absolute path on server | /var/www/html | + +## Remote Debugger + +- `Run` -> `Edit Configurations` +- `+` -> `PHP Remote Debug` +- Give it a name +- Use the server you created before +- Use **SPINNER** as IDE key + +Make sure you start listening when you want to debug by clicking the little bug icon in the top right (by default) in +PHPStorm. \ No newline at end of file diff --git a/Home.md b/Home.md index 33c8f7b..812034d 100644 --- a/Home.md +++ b/Home.md @@ -1,7 +1,7 @@ > Please note, this package is currently unreleased, this Wiki is a work in progress for a package that is currently > under active development. -Welcome to the official documentation for **Loom Spinner**, the PHP development environment tool. +Welcome to the official documentation for **Loom Spinner CLI**, the PHP development environment tool. Spinner is a tool that helps you spin up and manage Docker containers for PHP development on a project-by-project basis. It is designed to be **highly configurable** whilst requiring _minimal configuration_. @@ -24,5 +24,5 @@ The default environment contains the following set of tools: # Documentation Navigation -This Wiki is designed to be navigated by following the top level sidebar links in order, however feel free to read in +This Wiki is designed to be navigated by following the top level sidebar links in order, however, feel free to read in any order you would prefer. \ No newline at end of file diff --git a/Installation.md b/Installation.md index eb75071..278f514 100644 --- a/Installation.md +++ b/Installation.md @@ -1,6 +1,6 @@ # Pre-Requisites -Imperfectly, **Loom Spinner** requires the following tools installed on your system: +Imperfectly, **Loom Spinner CLI** requires the following tools installed on your system: - PHP 8.3+ - [Composer](https://getcomposer.org/download/) @@ -10,11 +10,11 @@ Imperfectly, **Loom Spinner** requires the following tools installed on your sys > Please note, this will not yet work as this package is currently unreleased. -To install **Loom Spinner**, use the following Composer command: +To install **Loom Spinner CLI**, use the following Composer command: ```shell -composer global require loomlabs/spinner +composer global require loomlabs/loom-spinner-cli ``` -This will download the package and add the binary to your `$PATH` so you can call `spinner` commands on -your machine. \ No newline at end of file +This will download the package and add the command to your global Composer `bin` directory, so you can call `loom` +commands on your machine. \ No newline at end of file diff --git a/Quick-Start-Guide.md b/Quick-Start-Guide.md index 752645f..3874cb1 100644 --- a/Quick-Start-Guide.md +++ b/Quick-Start-Guide.md @@ -1,3 +1,3 @@ After [installation](Installation), you'll need to ensure that your **Docker Engine** is installed and running before running any -`spinner` commands. If you attempt to run any `spinner` commands while your Docker Engine is turned off, you'll see an +`loom` commands. If you attempt to run any `loom` commands while your Docker Engine is turned off, you'll see an error message. \ No newline at end of file diff --git a/_Sidebar.md b/_Sidebar.md index 958a1c1..76e1745 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -5,4 +5,5 @@ - [Commands](Commands) - [Build Environment](Build-Command) - [Destroy Environment](Destroy-Command) - - [List Environments](List-Command) \ No newline at end of file + - [List Environments](List-Command) +- [Debugging](Debugging) \ No newline at end of file