├── .env.slic ├── .github └── workflows │ ├── publish-slic-docker-image.yml │ └── publish-wordpress-docker-image.yml ├── .gitignore ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── changelog.md ├── containers ├── scripts │ ├── before-npm.sh │ └── host-ip.sh ├── slic │ ├── .bashrc │ ├── Dockerfile │ ├── bashrc_scripts.sh │ ├── docker-php-ext-uopz.ini │ ├── fixuid.yml │ ├── php.ini │ ├── slic-entrypoint.sh │ ├── xdebug-off.sh │ └── xdebug-on.sh └── wordpress │ ├── Dockerfile │ ├── php.ini │ ├── xdebug-off.sh │ └── xdebug-on.sh ├── docs ├── M1-Mac.md ├── images │ ├── activation-deactivation-debug-phpstorm-config.png │ ├── slic-Xdebug-PhpStorm.png │ ├── slic-composer-cache.gif │ ├── slic-here-wp.gif │ ├── slic-here.gif │ ├── slic-init.gif │ ├── slic-target-example.png │ └── slic-use.gif ├── slicjson.md └── xdebug.md ├── includes ├── Spyc │ ├── LICENSE.txt │ └── Spyc.php └── polyfills.php ├── slic ├── slic-stack.site.yml ├── slic-stack.yml ├── slic.bat ├── slic.md ├── slic.php ├── src ├── cache.php ├── classes │ └── Cache.php ├── colors.php ├── commands.php ├── commands │ ├── airplane-mode.php │ ├── build-prompt.php │ ├── build-stack.php │ ├── build-subdir.php │ ├── cache.php │ ├── cc.php │ ├── cli.php │ ├── composer-cache.php │ ├── composer.php │ ├── config.php │ ├── dc.php │ ├── debug.php │ ├── down.php │ ├── exec.php │ ├── here.php │ ├── host-ip.php │ ├── info.php │ ├── init.php │ ├── interactive.php │ ├── logs.php │ ├── mysql.php │ ├── npm.php │ ├── php-version.php │ ├── phpcbf.php │ ├── phpcs.php │ ├── playwright.php │ ├── ps.php │ ├── reset.php │ ├── restart.php │ ├── run.php │ ├── shell.php │ ├── site-cli.php │ ├── ssh.php │ ├── start.php │ ├── stop.php │ ├── target.php │ ├── up.php │ ├── update-dump.php │ ├── update.php │ ├── upgrade.php │ ├── use.php │ ├── using.php │ └── xdebug.php ├── database.php ├── docker.php ├── env.php ├── notify.php ├── plugins.php ├── process.php ├── project.php ├── scaffold.php ├── scripts.php ├── services.php ├── shell.php ├── slic.php ├── themes.php ├── utils.php └── wordpress.php ├── tric └── tric.bat /.env.slic: -------------------------------------------------------------------------------- 1 | # The distribution version of the slic-stack.yml configuration file. 2 | # DO NOT MODIFY THIS FILE! 3 | # If you need to override the contents of this file create a .env.slic.local file and customize it. 4 | 5 | 6 | # slic cli configuration parameters. 7 | # ================================== 8 | # The containers will each be assigned an IP address in the `slic` network. 9 | # If you have other similar setups, this setting might conflict with existing settings, change this in the override file 10 | # if required. 11 | SLIC_TEST_SUBNET=28 12 | # Set to `1` to have more debug information. 13 | CLI_VERBOSITY=0 14 | # These two are better set at run time, but it might come in handy to fix them. 15 | # DOCKER_RUN_UID=0 16 | # DOCKER_RUN_GID=0 17 | # This will force the cli tool to use a specific project to run the tests. 18 | # You should use the `use` command usually. 19 | # SLIC_CURRENT_PROJECT=the-events-calendar 20 | # When you `here` at the site level, all selected targets via `use` will have a relative path set. 21 | # SLIC_CURRENT_PROJECT_RELATIVE_PATH= 22 | # When you `use` on a supported subdirectory of a plugin, this stores the subdirectory name. 23 | #SLIC_CURRENT_PROJECT_SUBDIR= 24 | # The git domain from which to clone plugins. 25 | SLIC_GIT_DOMAIN=github.com 26 | # The git handle from which to clone plugins. 27 | SLIC_GIT_HANDLE=stellarwp 28 | 29 | # The path where `slic here` was executed. 30 | # SLIC_HERE_DIR= 31 | # The path from which to read plugins from. 32 | SLIC_PLUGINS_DIR=./_plugins 33 | # The path from which to read themes from. 34 | SLIC_THEMES_DIR=./_wordpress/wp-content/themes 35 | # The path from which to read WordPress core code from. 36 | SLIC_WP_DIR=./_wordpress 37 | # The path where mounted scripts will live 38 | SLIC_SCRIPTS=./containers/scripts 39 | 40 | # The build-prompt mode of slic. Set to `0` to avoid prompting/defaulting prompts for composer/npm builds during CLI operations. 41 | SLIC_BUILD_PROMPT=1 42 | 43 | # The build-subdir mode of slic. Set to `0` to avoid slic from prompting, and running, composer/npm commands during CLI operations. 44 | SLIC_BUILD_SUBDIR=1 45 | 46 | # The interactive mode of slic. Set to `0` to avoid prompts during CLI operations. 47 | SLIC_INTERACTIVE=1 48 | 49 | # The PHP version to run in the slic container. Only use single dot notation, e.g. 7.4, not 7.4.35 50 | SLIC_PHP_VERSION=7.4 51 | 52 | # XDebug configuration parameters, will apply to the `cli`, `wordpress` and `codeception` services. 53 | # =============================== 54 | # The IDE key used to identify connection requests coming from the services. 55 | XDK=slic 56 | # Whether to enable XDebug in the containers or not. 57 | XDE=0 58 | # The remote host XDebug should connect to. 59 | # This default value should work out of the box on Docker for Mac and Windows. 60 | # On Linux, this is automatically set in src/slic.php to make the Docker gateway IP map to this host. 61 | # Override this value in the .env.slic.local file, if required. 62 | # E.g. to get the current host IP on Debian derivatives: ip route | grep docker0 | awk '{print $9}' 63 | XDH=host.docker.internal 64 | # The remote host port XDebug will connect to. Avoids the default 9000 as your host machine might have php-fpm already 65 | # listening on that. 66 | XDP=9001 67 | 68 | # `db` service configuration parameters. 69 | # ====================================== 70 | MYSQL_ROOT_PASSWORD=password 71 | SLIC_DB_LOCALHOST_PORT=9906 72 | 73 | # `wordpress` service configuration parameters. 74 | # ============================================= 75 | # The localhost port the WordPress website will be served at. 76 | WORDPRESS_HTTP_PORT=8888 77 | 78 | # Directory the host machine's cache directory will be mapped to. 79 | COMPOSER_CACHE_DIR=./.cache 80 | 81 | # This value will be assigned to the WP_HTTP_BLOCK_EXTERNAL constant defined in the wp-config.php file. 82 | # Set to `true` to block all external HTTP requests from WordPress, set to `false` to allow all requests. 83 | SLIC_WP_HTTP_BLOCK_EXTERNAL=true 84 | 85 | # This value will be assigned to the DISABLE_WP_CRON constant defined in the wp-config.php file. 86 | # Set to `true` to disable the WordPress cron system, set to `false` to enable it. 87 | SLIC_DISABLE_WP_CRON=true 88 | 89 | # This value will be assigned to the WP_AUTO_UPDATE_CORE constant defined in the wp-config.php file. 90 | # Set to `true` to allow automatic core updates to take place. 91 | SLIC_WP_AUTO_UPDATE_CORE=false 92 | 93 | # This value will be assigned to the AUTOMATIC_UPDATER_DISABLED constant defined in the wp-config.php file. 94 | # Set to `false` to allow all types of automatic updates. 95 | SLIC_AUTOMATIC_UPDATER_DISABLED=true 96 | -------------------------------------------------------------------------------- /.github/workflows/publish-slic-docker-image.yml: -------------------------------------------------------------------------------- 1 | name: Publish slic-php docker image 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | - '[0-9]+.[0-9]+.[0-9]+' 8 | release: 9 | types: [published] 10 | 11 | jobs: 12 | publish-slic-image: 13 | runs-on: ubuntu-latest 14 | permissions: 15 | contents: read 16 | packages: write 17 | strategy: 18 | matrix: 19 | # The php_version is the docker tag from https://hub.docker.com/_/php/tags 20 | php_version: [ '7.3', '7.4', '8.0', '8.1', '8.2', '8.3' ] 21 | 22 | steps: 23 | - name: Checkout repository 24 | uses: actions/checkout@v4 25 | 26 | - name: Log in to Docker Hub 27 | uses: docker/login-action@v3 28 | with: 29 | username: ${{ secrets.DOCKER_USERNAME }} 30 | password: ${{ secrets.DOCKER_TOKEN }} 31 | 32 | - name: Log in to the Container registry 33 | uses: docker/login-action@v3 34 | with: 35 | registry: ghcr.io 36 | username: ${{ github.actor }} 37 | password: ${{ secrets.GITHUB_TOKEN }} 38 | 39 | - name: Extract metadata for image 40 | id: meta 41 | uses: docker/metadata-action@v5 42 | with: 43 | images: ghcr.io/${{ github.repository }}-php${{ matrix.php_version }} 44 | tags: | 45 | type=edge,branch=main 46 | type=ref,event=branch 47 | type=ref,event=tag 48 | type=semver,pattern={{raw}} 49 | 50 | - uses: docker/setup-buildx-action@v2 51 | 52 | - name: Build and push Docker image 53 | uses: docker/build-push-action@v3 54 | with: 55 | context: containers/slic 56 | file: containers/slic/Dockerfile 57 | push: true 58 | tags: | 59 | ${{ steps.meta.outputs.tags }} 60 | labels: ${{ steps.meta.outputs.labels }} 61 | cache-from: type=gha,scope=${{ matrix.php_version }} 62 | cache-to: type=gha,mode=max,scope=${{ matrix.php_version }} 63 | build-args: | 64 | PHP_VERSION=${{ matrix.php_version }} 65 | NODE_VERSION=18.13.0 66 | NVM_VERSION=v0.39.7 67 | platforms: linux/amd64,linux/arm64 68 | -------------------------------------------------------------------------------- /.github/workflows/publish-wordpress-docker-image.yml: -------------------------------------------------------------------------------- 1 | name: Publish slic-wordpress-php Docker image 2 | 3 | on: 4 | push: 5 | branches: 6 | - main 7 | - '[0-9]+.[0-9]+.[0-9]+' 8 | release: 9 | types: [published] 10 | 11 | jobs: 12 | publish-wordpress-image: 13 | runs-on: ubuntu-latest 14 | permissions: 15 | contents: read 16 | packages: write 17 | strategy: 18 | matrix: 19 | wp_version: [ '6.2' ] 20 | php_version: [ '8.0', '8.1', '8.2' ] 21 | include: 22 | # No WordPress image for version 6.2+ and PHP 7.3: use the latest 5.9 version. 23 | # This version is NOT updated in the containers/wordpress/Dockerfile for back-compatibility. 24 | - wp_version: '5.9' 25 | php_version: '7.3' 26 | # No WordPress image for version 6.2+ and PHP 7.4: use the latest 6.1.1 version. 27 | # See containers/wordpress/Dockerfile for the wp-cli update to version 6.2. 28 | - wp_version: '6.1.1' 29 | php_version: '7.4' 30 | # Use the latest 6.5 WordPress version for PHP 8.3. 31 | - wp_version: '6.5' 32 | php_version: '8.3' 33 | 34 | steps: 35 | - name: Checkout repository 36 | uses: actions/checkout@v4 37 | 38 | - name: Log in to Docker Hub 39 | uses: docker/login-action@v3 40 | with: 41 | username: ${{ secrets.DOCKER_USERNAME }} 42 | password: ${{ secrets.DOCKER_TOKEN }} 43 | 44 | - name: Log in to the Container registry 45 | uses: docker/login-action@v3 46 | with: 47 | registry: ghcr.io 48 | username: ${{ github.actor }} 49 | password: ${{ secrets.GITHUB_TOKEN }} 50 | 51 | - name: Extract metadata (tags, labels) for Docker 52 | id: meta 53 | uses: docker/metadata-action@v5 54 | with: 55 | images: ghcr.io/${{ github.repository }}-wordpress-php${{ matrix.php_version }} 56 | tags: | 57 | type=edge,branch=main 58 | type=ref,event=branch 59 | type=ref,event=tag 60 | type=semver,pattern={{raw}} 61 | 62 | - uses: docker/setup-buildx-action@v3 63 | 64 | - name: Build and push Docker image 65 | uses: docker/build-push-action@v5 66 | continue-on-error: true 67 | with: 68 | context: containers/wordpress 69 | file: containers/wordpress/Dockerfile 70 | push: true 71 | pull: true 72 | tags: | 73 | ${{ steps.meta.outputs.tags }} 74 | labels: ${{ steps.meta.outputs.labels }} 75 | cache-from: type=gha,scope=${{ matrix.wp_version }}-${{ matrix.php_version }} 76 | cache-to: type=gha,mode=max,scope=${{ matrix.wp_version }}-${{ matrix.php_version }} 77 | build-args: | 78 | PHP_VERSION=${{ matrix.php_version }} 79 | WP_VERSION=${{ matrix.wp_version }} 80 | platforms: linux/amd64,linux/arm64 81 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | wp-lib 3 | wp 4 | vendor 5 | .data 6 | .idea 7 | *.log 8 | local-config.php 9 | 10 | # Any dot prefixed scripts are dynamically generated and should be ignored. 11 | containers/scripts/.* 12 | 13 | wp-content/uploads 14 | wp-content/plugins 15 | wp-content/themes 16 | 17 | # The directory where we're downloading the plugins in different versions. 18 | test/_plugin_store 19 | 20 | # Local file used to test the script locally. 21 | .env.licenses 22 | 23 | # Ignore the local version of WordPress and the plugins files used in local development and testing. 24 | _wordpress 25 | _plugins 26 | # Any .using file created by the slic cli tool. 27 | .using 28 | # Any .env.slic.* file created to override the slic cli tool configuration or to configure the runs. 29 | .env.slic.local 30 | .env.slic.run 31 | 32 | # Any .build-version file created by the slic cli tool. 33 | .build-version 34 | # Any .remote-version file created by the slic cli tool. 35 | .remote-version 36 | # Any architecture detection flag file. 37 | .architecture_arm64 38 | .architecture_x86 39 | 40 | # slic own cache directory 41 | .cache 42 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # How to contribute 2 | 3 | We happily review/accept third-party Pull Requests. To help get your patches adopted into our plugins, there's a few bits of info that are worth knowing. 4 | 5 | ## Prerequisites 6 | 7 | * Docker 8 | * PHP 7.4+ at the system level 9 | 10 | ## Build steps 11 | 12 | Wooo! There aren't any! We do suggest adding `slic` to your `$PATH`, though. To do that, place the following in your `.bashrc` or `.zshrc` (or whatever) file: 13 | 14 | ```bash 15 | export PATH=$PATH:path/to/slic 16 | ``` 17 | 18 | ## Releases 19 | 20 | When we prep a release, we follow these steps: 21 | 22 | 1. Create a branch with the version number of the release, e.g. `1.0.0` 23 | 2. Merge changes into that branch. This will trigger the Docker images to build. 24 | 3. Ensure that the `CLI_VERSION` has been updated in `slic.php` to reflect the version number of the release. 25 | 4. Ensure that the `changelog.md` file has been updated. 26 | 5. Merge the release branch into `main`. 27 | 6. Delete the release branch. 28 | 7. Tag the release with the changelog.md contents for that release. This will trigger the final Docker images to build. -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 StellarWP 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # slic 2 | 3 | The slic (**S**tellarWP **L**ocal **I**nteractive **C**ontainers) CLI command provides a containerized and consistent environment for running automated tests. 4 | 5 | ## Table of Contents 6 | 7 | * [Getting started](#getting-started) 8 | * [Why use `slic`?](#why-use-slic) 9 | * [Why use Codeception?](#why-use-codeception) 10 | * [Requirements](#requirements) 11 | * [Installation](#installation) 12 | * [The most important command to know](#the-most-important-command-to-know) 13 | * [Using `slic`](#using-slic) 14 | * [Tell `slic` how to find your project](#tell-slic-how-to-find-your-project) 15 | * [Preparing your project](#preparing-your-project) 16 | * [Adding tests](#adding-tests) 17 | * [Running tests](#running-tests) 18 | * [Advanced topics](#advanced-topics) 19 | * [Defaults for your project with `slic.json`](/docs/slicjson.md) 20 | * [Making composer installs faster](#making-composer-installs-faster) 21 | * [Changing your composer version](#changing-your-composer-version) 22 | * [Customizing `slic`'s `.env` file](#customizing-slics-env-file) 23 | * [Xdebug and `slic`](#xdebug-and-slic) 24 | * [Configuring IDEs for Xdebug](/docs/xdebug.md) 25 | * [Releasing a new version of `slic`](/CONTRIBUTING.md) 26 | 27 | 28 | ## Gettings started 29 | 30 | ### Why use `slic`? 31 | 32 | One of the biggest stumbling blocks that engineers face when getting automated testing going for their projects is the complexity of setting up a testing environment. And as your team size grows, the struggles with consistent test running increase. 33 | 34 | **`slic` automatically configures a Codeception testing environment so you don't have to.** 35 | 36 | Plus, it provides a lot of handy development tools and utilities that you can use while developing your project _or_ during Continuous Integration builds! 37 | 38 | ### Why use Codeception? 39 | 40 | [Codeception](https://codeception.com/) is a PHP testing framework that uses [PHPUnit](https://phpunit.de/) under the hood, adding all sorts of extra features to make testing PHP much easier. By using Codeception, you then get the ability to use [wp-browser](https://wpbrowser.wptestkit.dev/), a module that _greatly_ simplifies testing WordPress plugins, themes, and whole WP sites at all levels of testing. 41 | 42 | » Learn more about [wp-browser here](https://wpbrowser.wptestkit.dev/) and get it set up on your project. 43 | 44 | > You can see examples of what to toss in your `composer.json` in our [stellarwp/schema](https://github.com/stellarwp/schema/blob/main/composer.json) repository. 45 | 46 | ### Requirements 47 | 48 | Docker. 49 | 50 | That's the only prerequisite. Get that installed and running on your machine and you'll be good to go! 51 | 52 | ### Installation 53 | 54 | #### 1. Clone the repo 55 | 56 | > These instructions are assuming that you are cloning the `slic` repository in `~/projects`. If you want it in a different location, feel free to tweak the example commands below. 57 | 58 | ```bash 59 | cd ~/projects 60 | git clone git@github.com:stellarwp/slic.git 61 | ``` 62 | 63 | #### 2. Add `slic` to your `$PATH` 64 | 65 | _Assuming you are cloning the `slic` repository in `~/projects`:_ 66 | 67 | ```bash 68 | echo "export PATH=$HOME/projects/slic:$PATH" >> ~/.bashrc 69 | source ~/.bashrc 70 | ``` 71 | 72 | > If you are using zsh, change `~/.bashrc` to `~/.zshrc`. 73 | 74 | ### The most important command to know 75 | 76 | `slic` is well documented within the CLI utility itself. To see all of the available commands, run: 77 | 78 | ```bash 79 | slic help 80 | ``` 81 | 82 | You can see details and usage on each command by running: 83 | 84 | ```bash 85 | slic help 86 | ``` 87 | 88 | ## Using `slic` 89 | 90 | The `slic` command has many subcommands. You can discover what those are by typing `slic` or `slic help`. If you want 91 | more details on any of the subcommands, simply type: `slic [subcommand] help`. 92 | 93 | ### Tell `slic` how to find your project 94 | 95 | The `slic` command needs a place to look for plugins, themes, and WordPress. By default, `slic` creates a `_plugins` and 96 | `_wordpress` directory within the local checkout of `slic`. In most cases, however, developers like to run automated tests 97 | against the paths where they are actively working on code – which likely lives elsewhere. 98 | 99 | Good news! You can use the `slic here` sub-command to re-point `slic`'s paths so it looks in the places you wish. There 100 | are two locations you can tell `slic` to look. 101 | 102 | #### 1. Plugins Directory 103 | 104 | If you want to defer all of the WP site configuration to a dynamically pulled codebase and _just_ worry about testing 105 | plugins, you can run the `slic here` command right from the parent directory of your project. Doing so will restrict `slic` to running tests on subdirectories of where you ran the command. 106 | 107 | Example: 108 | 109 | ```bash 110 | # Change to your plugin containing dir (likely some path to wp-content/plugins) 111 | cd /path/to/your/wp-content/plugins 112 | 113 | slic here 114 | ``` 115 | 116 | ![slic here](docs/images/slic-here.gif) 117 | 118 | #### 2. WordPress Directory 119 | 120 | The second option is to navigate to the root of your site (likely where `wp-config.php` lives) and run the `slic here` 121 | command. 122 | 123 | > Note: This is an opinionated option and there are some assumptions that are made: 124 | > 125 | > 1. That the WordPress directory _is_ the path you are indicating or in a sub-directory called `wp/`. 126 | > 2. That the `wp-content/` (or `content/`) directory is a sub-directory of the location in which you are typing `slic here`. 127 | 128 | 129 | ```bash 130 | # Change to your root directory of your site (where your wp-config.php file lives) 131 | cd /path/to/your/site 132 | 133 | slic here 134 | ``` 135 | 136 | By running `slic here` at the site level, this allows you to set plugins, themes, or the site itself as the location 137 | from which to run tests. This also has the benefit of running tests within the WP version that your site uses. 138 | 139 | ![slic here](docs/images/slic-here-wp.gif) 140 | 141 | ### Preparing your project 142 | 143 | ### Point `slic` at your project 144 | 145 | Before you can do anything productive with `slic`, you need to tell it which 146 | project you wish to use and then you can initialize the project, run tests, and 147 | execute other commands to your heart's content! 148 | 149 | Assuming you have a plugin called `the-events-calendar` in the plugins directory 150 | where you ran `slic here`, you can tell `slic` you want to take actions on that 151 | plugin using the following command: 152 | 153 | ```bash 154 | slic use the-events-calendar 155 | ``` 156 | 157 | > For more information on this command, run `slic help use`. 158 | 159 | ![slic use](docs/images/slic-use.gif) 160 | 161 | ### Initialize your project 162 | 163 | With your desired plugin containing directory set, you will need to initialize plugins so that they are prepped and ready 164 | for `slic`-based automated test running. You do that using `slic init [plugin]`. 165 | 166 | Example: 167 | 168 | ```bash 169 | slic init event-tickets 170 | ``` 171 | 172 | ![slic init](docs/images/slic-init.gif) 173 | 174 | What this command does: 175 | 176 | 1. Generates a `.env.testing.slic` env file in the plugin. 177 | 2. Generates a `test-config.slic.php` file in the plugin. 178 | 3. Generates a `codeception.slic.yml` file in the plugin. 179 | 4. Prompts for confirmation on running `composer` and `npm` installs on the plugin. 180 | 181 | ### Adding tests 182 | 183 | As mentioned above, you'll need to use Codeception for your automated testing and it is _highly_ recommended that you make use of [wp-browser](https://wpbrowser.wptestkit.dev/) - which adds a _lot_ of WordPress helper functions and utilities. 184 | 185 | ### Running tests 186 | 187 | Ok. You have `slic` set up. It is pointing at your project. Your project has tests. Now you want to run one of your test suites. Let's pretend that your test suite is called `wpunit`. 188 | 189 | You can run the full suite like so: 190 | 191 | ```bash 192 | slic run wpunit 193 | ``` 194 | 195 | Or, if you want an even more efficient way to do it, you can do: 196 | 197 | ```bash 198 | slic shell 199 | 200 | # You'll get a prompt once you are thrown into the shell 201 | 202 | > cr wpunit 203 | ``` 204 | 205 | ## Advanced topics 206 | 207 | ### Making composer installs faster 208 | 209 | By default, `slic` caches composer dependencies within the container 210 | and, when the containers are destroyed, so is the cache. The good news 211 | is that `slic` allows you to map your machine's composer cache directory into 212 | the `slic` containers so that repeated `slic composer` commands can benefit from 213 | the cache as well! 214 | 215 | ```bash 216 | # Feel free to change the path to whatever is appropriate for your machine. 217 | slic composer-cache set $HOME/.cache/composer 218 | ``` 219 | 220 | For more information on this topic, type `slic help composer-cache`. 221 | 222 | ![slic composer-cache](docs/images/slic-composer-cache.gif) 223 | 224 | ### Changing your composer version 225 | 226 | By default, `slic` uses composer v1 but you may also choose to use v2 by running the following command: 227 | 228 | `slic composer set-version 2` 229 | 230 | If you need to go back, just set the version back to 1: 231 | 232 | `slic composer set-version 1` 233 | 234 | If you want to know which version `slic` is pointed at, you can always call: 235 | 236 | `slic composer get-version` 237 | 238 | ### Installing private packages with composer 239 | 240 | If you need to install a private composer package, configure the [COMPOSER_AUTH](https://getcomposer.org/doc/03-cli.md#composer-auth) environment variable. For example, to install a package from a private GitHub repository: 241 | 242 | > Note: You may need to create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). 243 | 244 | ```shell 245 | export COMPOSER_AUTH='{"github-oauth": {"github.com": "YOUR_TOKEN_HERE"}}' 246 | ``` 247 | 248 | Then, restart slic and try again: 249 | 250 | ```shell 251 | slic restart; slic composer update 252 | ``` 253 | 254 | Or, in a GitHub Action, for example: 255 | 256 | ```yaml 257 | jobs: 258 | test: 259 | runs-on: ubuntu-latest 260 | 261 | env: 262 | COMPOSER_AUTH: '{"github-oauth": {"github.com": "${{ secrets.GH_BOT_TOKEN }}"}}' 263 | ``` 264 | 265 | ### Customizing `slic`'s `.env` file 266 | 267 | The `slic` CLI command leverages `.env.*` files to dictate its inner workings. It loads `.env.*` files in the following order, the later files overriding the earlier ones: 268 | 269 | 1. [`.env.slic`](/.env.slic) - this is the default `.env` file and **should not be edited**. 270 | 2. `.env.slic.local` in the main _slic_ directory - this file doesn't exist by default. Make overrides to all your projects (e.g. `SLIC_GIT_HANDLE`) by creating it and adding lines to your heart's content. 271 | 3. `.env.slic.local` in your _target's_ directory - this file doesn't exist by default. Make overrides to a single project (e.g. `SLIC_PHP_VERSION`). 272 | 4. `.env.slic.run` - this file is generated by `slic` and includes settings that are set by specific `slic` commands. 273 | 274 | ### Xdebug and `slic` 275 | 276 | #### Available Commands 277 | 278 | ##### `slic xdebug help` 279 | 280 | List the available Xdebug commands. 281 | 282 | ##### `slic xdebug status` 283 | 284 | See if Xdebug is enabled or disabled, the host information, and the path mapping to add to your IDE. 285 | 286 | Note that this command cannot be ran within `slic shell` because you've SSH'd into the Codeception container which has no knowledge of *slic*. 287 | 288 | See also: [Configuring Xdebug](/docs/xdebug.md) 289 | 290 | 291 | #### Enable/Disable Xdebug 292 | 293 | 1. `slic xdebug on` 294 | 1. `slic xdebug off` 295 | 1. Within `slic shell`: 296 | 1. `slic xon` 297 | 1. `slic xoff` 298 | 299 | 300 | 301 | ## Acknowledgements 302 | 303 | Props to [@lucatume](https://github.com/lucatume), [@borkweb](https://github.com/borkweb), and [The Events Calendar](https://theeventscalendar.com) team for creating this tool and it's predecessor, `tric`. 304 | -------------------------------------------------------------------------------- /containers/scripts/before-npm.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | . $NVM_DIR/nvm.sh 4 | 5 | NVMRC=.nvmrc 6 | 7 | if [[ -f "$NVMRC" ]]; then 8 | VERSION=$(cat $NVMRC) 9 | HAS_VERSION=$(nvm ls --no-colors "$VERSION" | tail -1 | tr -d '\->*' | tr -d '[:space:]' ) 10 | echo $HAS_VERSION 11 | if [[ "$HAS_VERSION" == "N/A" ]]; then 12 | nvm install $VERSION 13 | fi 14 | nvm use 15 | fi -------------------------------------------------------------------------------- /containers/scripts/host-ip.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | ip route | awk "/default/ { print $3 }" | cut -d " " -f3 -------------------------------------------------------------------------------- /containers/slic/.bashrc: -------------------------------------------------------------------------------- 1 | #! /usr/bin/env bash 2 | 3 | export PS1="[\\u@slic] \\w\\n > " 4 | 5 | [[ -s $NVM_DIR/nvm.sh ]] && . $NVM_DIR/nvm.sh 6 | 7 | source /home/slic/bashrc_scripts.sh -------------------------------------------------------------------------------- /containers/slic/Dockerfile: -------------------------------------------------------------------------------- 1 | ARG PHP_VERSION=7.4 2 | 3 | # Source Composer 1 and 2 from the respective images, multi-layer builds. 4 | FROM composer:1 AS composer1 5 | FROM composer:2 AS composer2 6 | 7 | FROM php:${PHP_VERSION} 8 | 9 | ARG NODE_VERSION=18.17.0 10 | ARG NVM_VERSION=v0.40.1 11 | # Disable AVIF for GD https://github.com/mlocati/docker-php-extension-installer#configuration 12 | ARG IPE_GD_WITHOUTAVIF=true 13 | 14 | SHELL ["/bin/bash", "-eou", "pipefail", "-c"] 15 | 16 | # Install and make wp-cli binary available and executable by all users. 17 | ADD https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar /usr/local/bin/wp 18 | RUN chmod a+rx /usr/local/bin/wp 19 | 20 | # The mlocati/docker-php-extension-installer will install PHP extensions setting up requirements correctly and cleaning up after. 21 | ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/ 22 | RUN chmod a+x /usr/local/bin/install-php-extensions && \ 23 | install-php-extensions xdebug pdo pdo_mysql mysqli zip uopz pcntl sockets intl exif 24 | 25 | RUN if [ ${IPE_GD_WITHOUTAVIF} = true ]; then \ 26 | IPE_GD_WITHOUTAVIF=1 install-php-extensions gd; \ 27 | else \ 28 | install-php-extensions gd; \ 29 | fi 30 | 31 | # Install some more packages required by wp-cli, Composer and Playwright. 32 | RUN apt-get update && apt-get upgrade -yqq && apt-get install -yqq --no-install-recommends --show-progress \ 33 | default-mysql-client curl git zip unzip iproute2 \ 34 | libnss3 libnspr4 libdbus-1-3 libatk1.0-0 libatk-bridge2.0-0 \ 35 | libcups2 libdrm2 libxkbcommon0 libatspi2.0-0 libxcomposite1 \ 36 | libxdamage1 libxext6 libxfixes3 libxrandr2 libgbm1 \ 37 | libpango-1.0-0 libcairo2 libasound2 less \ 38 | && apt-get clean && rm -rf /var/lib/apt/lists/* 39 | 40 | # Configure the uopz extension. 41 | COPY ./docker-php-ext-uopz.ini /usr/local/etc/php/conf.d/docker-php-ext-uopz.ini 42 | 43 | # Add the XDebug control scripts. 44 | COPY ./xdebug-on.sh /usr/local/bin/xdebug-on 45 | COPY ./xdebug-off.sh /usr/local/bin/xdebug-off 46 | RUN chmod a+x /usr/local/bin/xdebug-on && \ 47 | chmod a+x /usr/local/bin/xdebug-off 48 | 49 | # Make the PHP configuration directory recursively readable and writable to allow all users to activate and deactivate XDebug. 50 | RUN chmod -R a+rwx /usr/local/etc/php/conf.d 51 | RUN xdebug-off 52 | 53 | # Install nvm. 54 | ENV NODE_VERSION=${NODE_VERSION} 55 | ENV NVM_VERSION=${NVM_VERSION} 56 | ENV NVM_DIR=/usr/local/bin/.nvm 57 | RUN mkdir /usr/local/bin/.nvm && mkdir /usr/local/bin/.nvm/cache 58 | RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/${NVM_VERSION}/install.sh | bash 59 | RUN bash -c '. $NVM_DIR/nvm.sh && nvm install $NODE_VERSION' 60 | RUN bash -c '. $NVM_DIR/nvm.sh && nvm alias default $NODE_VERSION' 61 | RUN bash -c '. $NVM_DIR/nvm.sh && nvm use default' 62 | 63 | ENV PATH $NVM_DIR/versions/node/v$NODE_VERSION/bin:$NVM_DIR:$PATH 64 | RUN chmod a+x $NVM_DIR/nvm.sh && chmod a+rwx $NVM_DIR/cache 65 | 66 | # Install Composer 1 and 2 from the respective images and make them world-executable. 67 | COPY --from=composer1 /usr/bin/composer /usr/local/bin/composer1 68 | COPY --from=composer2 /usr/bin/composer /usr/local/bin/composer 69 | RUN chmod a+x /usr/local/bin/composer1 && chmod a+x /usr/local/bin/composer 70 | 71 | # Create a `slic` user and group fixuid will use. 72 | RUN [ $(getent group 1000) ] || addgroup --gid 1000 slic && \ 73 | [ $(id -u 1000) ] || adduser --uid 1000 --gid 1000 --home /home/slic --shell /bin/bash --disabled-password --gecos "" slic && \ 74 | mkdir -p /home/slic && \ 75 | curl -SsL https://github.com/boxboat/fixuid/releases/download/v0.5.1/fixuid-0.5.1-linux-amd64.tar.gz | tar -C /usr/local/bin -xzf - && \ 76 | chown root:root /usr/local/bin/fixuid && \ 77 | chmod 4755 /usr/local/bin/fixuid && \ 78 | mkdir -p /etc/fixuid 79 | COPY ./fixuid.yml /etc/fixuid/config.yml 80 | COPY ./.bashrc /home/slic/.bashrc 81 | COPY ./.bashrc /root/.bashrc 82 | COPY ./bashrc_scripts.sh /home/slic/bashrc_scripts.sh 83 | 84 | RUN chown -R slic:slic $NVM_DIR 85 | 86 | # Create a /cache directory any user will be able to read, write and execute from. 87 | RUN mkdir /cache && chmod a+rwx /cache 88 | RUN mkdir /composer-cache && chmod a+rwx /composer-cache 89 | 90 | COPY ./slic-entrypoint.sh /usr/local/bin/slic-entrypoint.sh 91 | RUN chmod a+x /usr/local/bin/slic-entrypoint.sh 92 | ENTRYPOINT ["/usr/local/bin/slic-entrypoint.sh"] 93 | 94 | USER slic:slic 95 | -------------------------------------------------------------------------------- /containers/slic/bashrc_scripts.sh: -------------------------------------------------------------------------------- 1 | # Some aliases to save some typing. 2 | alias c="vendor/bin/codecept -c $(if [ -f 'codeception.slic.yml' ]; then echo 'codeception.slic.yml'; else echo 'codeception.tric.yml'; fi)" 3 | alias cr="vendor/bin/codecept -c $(if [ -f 'codeception.slic.yml' ]; then echo 'codeception.slic.yml'; else echo 'codeception.tric.yml'; fi) run" 4 | alias p="node_modules/.bin/playwright" 5 | 6 | # Returns the path to the PHP version configuration file. 7 | function xdebug_config_file(){ 8 | echo "$(php --ini | grep xdebug | cut -d, -f1)" 9 | } 10 | 11 | # Activates the XDebug extension. 12 | function xon(){ 13 | xdebug-on 14 | echo "#!/bin/bash" > ~/xdebug-setting.sh 15 | echo "xdebug-on" >> ~/xdebug-setting.sh 16 | chmod +x ~/xdebug-setting.sh 17 | } 18 | 19 | # Deactivates the XDebug extension completely. 20 | function xoff(){ 21 | xdebug-off 22 | echo "#!/bin/bash" > ~/xdebug-setting.sh 23 | echo "xdebug-off" >> ~/xdebug-setting.sh 24 | chmod +x ~/xdebug-setting.sh 25 | } 26 | 27 | XDEBUG_FILE=~/xdebug-setting.sh 28 | if [ -f "$XDEBUG_FILE" ]; then 29 | . ~/xdebug-setting.sh 30 | else 31 | xoff 32 | fi 33 | 34 | echo " c = codecept" 35 | echo " cr = codecept run" 36 | echo " p = playwright" 37 | echo " xon = turn xdebug on" 38 | echo " xoff = turn xdebug off" 39 | echo "" 40 | -------------------------------------------------------------------------------- /containers/slic/docker-php-ext-uopz.ini: -------------------------------------------------------------------------------- 1 | ;Enable the uopz extension to mock built-in functions and static methods. 2 | extension=uopz.so 3 | uopz.disable=0 4 | 5 | ;By default, the uopz extension will ignore exit and die, let's make sure it does not. 6 | uopz.exit=1 7 | 8 | ;For dynamic mocking to affect the code execution, Opcache should run at lowest optimization level. 9 | opcache.optimization_level=0 10 | -------------------------------------------------------------------------------- /containers/slic/fixuid.yml: -------------------------------------------------------------------------------- 1 | user: slic 2 | group: slic 3 | paths: 4 | - /home/slic 5 | - /tmp 6 | - /var/www/html 7 | -------------------------------------------------------------------------------- /containers/slic/php.ini: -------------------------------------------------------------------------------- 1 | ;Explicitly set a timezone to avoid PHP complaining about using the default one. 2 | date.timezone="America/New_York" 3 | 4 | ;Avoid populating the $HTTP_RAW_POST_DATA and getting a deprecated warning about it. 5 | always_populate_raw_post_data=-1 6 | 7 | ;Set a fairly high memory limit to cope with Composer 1 needs. 8 | memory_limit=512M 9 | 10 | ;Allow fairly large uploads. 11 | file_uploads=On 12 | upload_max_filesize=128M 13 | post_max_size=128M 14 | 15 | ;Allow long request. 16 | max_execution_time=300 17 | 18 | ;If XDebug is active, it should always start. 19 | xdebug.start_with_request=yes 20 | xdebug.mode=develop,debug,coverage 21 | xdebug.discover_client_host=1 22 | xdebug.log_level=0 23 | 24 | ; Opcache 25 | opcache.revalidate_freq=0 26 | opcache.validate_timestamps=1 27 | opcache.max_accelerated_files=25000 28 | opcache.memory_consumption=128 29 | opcache.interned_strings_buffer=16 30 | 31 | -------------------------------------------------------------------------------- /containers/slic/slic-entrypoint.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | eval $(fixuid) 3 | tail -f /dev/null 4 | -------------------------------------------------------------------------------- /containers/slic/xdebug-off.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | xdebug_config_file=$(php --ini | grep xdebug | cut -d, -f1) 4 | sed -i '/^zend_extension/ s/zend_extension/;zend_extension/g' "$xdebug_config_file" 5 | php -v 6 | -------------------------------------------------------------------------------- /containers/slic/xdebug-on.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | xdebug_config_file=$(php --ini | grep xdebug | cut -d, -f1) 3 | sed -i '/^;zend_extension/ s/;zend_extension/zend_extension/g' "$xdebug_config_file" 4 | php -v 5 | -------------------------------------------------------------------------------- /containers/wordpress/Dockerfile: -------------------------------------------------------------------------------- 1 | ARG WORDPRESS_IMAGE_VERSION=wordpress/apache 2 | ARG PHP_VERSION=7.4 3 | ARG WP_VERSION=6.1 4 | 5 | FROM wordpress:${WP_VERSION}-php${PHP_VERSION}-apache 6 | ADD https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/ 7 | RUN chmod a+x /usr/local/bin/install-php-extensions && install-php-extensions xdebug 8 | COPY xdebug-on.sh /usr/local/bin/xdebug-on 9 | COPY xdebug-off.sh /usr/local/bin/xdebug-off 10 | RUN chmod a+x /usr/local/bin/xdebug-on && \ 11 | chmod a+x /usr/local/bin/xdebug-off && \ 12 | xdebug-off 13 | RUN chmod -R a+rwx /usr/local/etc/php/conf.d 14 | 15 | # Install and make wp-cli binary available and executable by all users. 16 | ADD https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar /usr/local/bin/wp 17 | RUN chmod a+rx /usr/local/bin/wp 18 | 19 | # No image for WordPress 6.2+ is available for PHP 7.4. 20 | # If PHP_VERSION is 7.4, update WordPress to 6.2 using wp-cli. 21 | # Weird syntax? POSIX compliant sh. 22 | RUN if echo "${PHP_VERSION}" | grep -q '^7.4'; then \ 23 | wp --allow-root --path=/usr/src/wordpress core download --version=6.2 --force; \ 24 | fi 25 | -------------------------------------------------------------------------------- /containers/wordpress/php.ini: -------------------------------------------------------------------------------- 1 | ;Explicitly set a timezone to avoid PHP complaining about using the default one. 2 | date.timezone="America/New_York" 3 | 4 | ;Avoid populating the $HTTP_RAW_POST_DATA and getting a deprecated warning about it. 5 | always_populate_raw_post_data=-1 6 | 7 | ;Set a fairly high memory limit to cope with Composer 1 needs. 8 | memory_limit=512M 9 | 10 | ;Allow fairly large uploads. 11 | file_uploads=On 12 | upload_max_filesize=128M 13 | post_max_size=128M 14 | 15 | ;Allow long request. 16 | max_execution_time=300 17 | 18 | ;If XDebug is active, it should always start. 19 | xdebug.start_with_request=yes 20 | xdebug.mode=develop,debug,coverage 21 | xdebug.discover_client_host=1 22 | xdebug.log_level=0 23 | 24 | ; Opcache 25 | opcache.revalidate_freq=0 26 | opcache.validate_timestamps=1 27 | opcache.max_accelerated_files=25000 28 | opcache.memory_consumption=128 29 | opcache.interned_strings_buffer=16 30 | -------------------------------------------------------------------------------- /containers/wordpress/xdebug-off.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | xdebug_config_file=$(php --ini | grep xdebug | cut -d, -f1) 4 | sed -i '/^zend_extension/ s/zend_extension/;zend_extension/g' "$xdebug_config_file" 5 | php -v 6 | # Kill the oldest php-fpm process, the manager. 7 | pkill -o -USR2 php-fpm 8 | # Restart the php-fpm server and php-fpm when used as a module, ignore errors if not running. 9 | /etc/init.d/apache2 reload > /dev/null 2>&1 10 | exit 0 11 | -------------------------------------------------------------------------------- /containers/wordpress/xdebug-on.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | xdebug_config_file=$(php --ini | grep xdebug | cut -d, -f1) 3 | sed -i '/^;zend_extension/ s/;zend_extension/zend_extension/g' "$xdebug_config_file" 4 | php -v 5 | # Kill the oldest php-fpm process, the manager. 6 | pkill -o -USR2 php-fpm 7 | # Restart the php-fpm server and php-fpm when used as a module, ignore errors if not running. 8 | /etc/init.d/apache2 reload > /dev/null 2>&1 9 | exit 0 10 | -------------------------------------------------------------------------------- /docs/M1-Mac.md: -------------------------------------------------------------------------------- 1 | # M1 Mac `tric` Setup 2 | 3 | ## Prerequisites 4 | 5 | 1. Docker Desktop For Mac should be installed and running. 6 | 7 | 2. Docker Experimental Features should be disabled [See Screenshot](https://drive.google.com/file/d/1ccghYtRqw2mqKUHNHKbC5Y7XjPBQoXz1/view?usp=sharing) 8 | 9 | ## The Issue 10 | 11 | The experimental features on Docker for Mac create some permission-related bugs that will hit the tric container. 12 | 13 | ## Workaround 14 | 15 | Download wp core WordPress in the tric/_wordpress directory manually using WP-CLI to have the file modes set up correctly then run tric to confirm the updates work as expected. -------------------------------------------------------------------------------- /docs/images/activation-deactivation-debug-phpstorm-config.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/stellarwp/slic/d32570fde4af46702e65204827804d7d8c5bab91/docs/images/activation-deactivation-debug-phpstorm-config.png -------------------------------------------------------------------------------- /docs/images/slic-Xdebug-PhpStorm.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/stellarwp/slic/d32570fde4af46702e65204827804d7d8c5bab91/docs/images/slic-Xdebug-PhpStorm.png -------------------------------------------------------------------------------- /docs/images/slic-composer-cache.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/stellarwp/slic/d32570fde4af46702e65204827804d7d8c5bab91/docs/images/slic-composer-cache.gif -------------------------------------------------------------------------------- /docs/images/slic-here-wp.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/stellarwp/slic/d32570fde4af46702e65204827804d7d8c5bab91/docs/images/slic-here-wp.gif -------------------------------------------------------------------------------- /docs/images/slic-here.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/stellarwp/slic/d32570fde4af46702e65204827804d7d8c5bab91/docs/images/slic-here.gif -------------------------------------------------------------------------------- /docs/images/slic-init.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/stellarwp/slic/d32570fde4af46702e65204827804d7d8c5bab91/docs/images/slic-init.gif -------------------------------------------------------------------------------- /docs/images/slic-target-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/stellarwp/slic/d32570fde4af46702e65204827804d7d8c5bab91/docs/images/slic-target-example.png -------------------------------------------------------------------------------- /docs/images/slic-use.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/stellarwp/slic/d32570fde4af46702e65204827804d7d8c5bab91/docs/images/slic-use.gif -------------------------------------------------------------------------------- /docs/slicjson.md: -------------------------------------------------------------------------------- 1 | # Using a `slic.json` file 2 | 3 | You can add a `slic.json` file to your project root to ensure that slic is setup correctly when you `slic use` your project. 4 | 5 | Here's an example `slic.json` file: 6 | 7 | ```json 8 | { 9 | "phpVersion": "8.2" 10 | } 11 | ``` 12 | 13 | ## `phpVersion` 14 | 15 | When you specify a `phpVersion` in your `slic.json` file, slic will automatically switch to that PHP version when you run `slic use` in your project if that isn't the current PHP version in slic. 16 | -------------------------------------------------------------------------------- /docs/xdebug.md: -------------------------------------------------------------------------------- 1 | # Configuring Xdebug 2 | 3 | Use `slic xdebug status` to find the configuration details for the project that you have run `slic use` on. This command will give you the path mappings and the port number that you need. 4 | 5 | * [PHPStorm](#phpstorm) 6 | * [VSCode](#vscode) 7 | 8 | ## PHPStorm 9 | 10 | [Video walk-through](https://drive.google.com/file/d/1sD8djXgmYWCUDCm_1XZNRx_GBbotmmiB/view?usp=sharing) 11 | 12 | 13 | ### Set appropriate debug ports 14 | 15 | In PHPStorm settings: 16 | 17 | 1. Search for `debug` 18 | 2. Select `PHP` > `Debug` 19 | 3. Ensure that the Debug port is set to whatever `slic xdebug status` returns. (typically `9001`) 20 | 21 | ### Set up server configuration 22 | 23 | In PHPStorm settings: 24 | 25 | 1. Search for `server` 26 | 2. Select `PHP` > `Servers` 27 | 3. Click the `+` button to add a new server 28 | 4. Set the `Name` to `slic` 29 | 5. Set the `Host` to whatever `slic xdebug status` returns. (typically `http://localhost:8888` ... yes, put the whole thing in the `Host` field) 30 | 6. Set the `Port` to `80` 31 | 7. Check the `Use path mappings` checkbox 32 | 8. Find the `wp-content/plugins` directory and set the `Absolute path on the server` to `/var/www/html/wp-content/plugins` 33 | 9. If you've added the `slic` directory to your workspace, find the `slic/_wordpress` directory and set the `Absolute path on the server` to `/var/www/html` 34 | 35 | Screenshot from PhpStorm's video: 36 | 37 | ![PhpStorm XDebug settings](/docs/images/slic-Xdebug-PhpStorm.png "PhpStorm XDebug settings") 38 | 39 | ## VSCode 40 | 41 | [Video walk-through](https://drive.google.com/file/d/1519M2SRVgWVgTm0Px6UKfBjoQgxCR7Cp/view?usp=sharing) 42 | 43 | Here's a standard configuration for Xdebug in VSCode or VSCode-like editors. _(Note: Be sure to use `slic xdebug status` to get the correct paths and port number.)_ 44 | 45 | ```json 46 | { 47 | "version": "0.2.0", 48 | "configurations": [ 49 | { 50 | "name": "Slic: Listen for Xdebug", 51 | "type": "php", 52 | "request": "launch", 53 | "port": 9001, 54 | "pathMappings": { 55 | "/var/www/html/wp-content/plugins": "${workspaceFolder}//plugins", 56 | "/var/www/html": "${workspaceFolder}/slic/_wordpress" 57 | }, 58 | "ignore": [ 59 | "**/vendor/**/*.php" 60 | ], 61 | "stopOnEntry": false 62 | } 63 | ] 64 | } 65 | ``` 66 | 67 | In this `launch.json` file, there are two `pathMappings` entries: 68 | 69 | 1. The first one maps the `slic` plugins directory (left side) to your local WP's plugins directory (right side). 70 | 2. The second one is technically optional, but it assumes you've added the `slic` directory to your VSCode workspace and maps the `slic` WP root (left side) to your local `slic` directory's WP root (right side). -------------------------------------------------------------------------------- /includes/Spyc/LICENSE.txt: -------------------------------------------------------------------------------- 1 | The MIT License 2 | 3 | Copyright (c) 2011 Vladimir Andersen 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in 13 | all copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 21 | THE SOFTWARE. -------------------------------------------------------------------------------- /includes/polyfills.php: -------------------------------------------------------------------------------- 1 | Note: activating and deactivating the debug mode will tear down, stop and remove, the stack containers and, with them, any modification you've made to the stack. If you have valuable information (you should not) inthe stack, then save it first. 121 | 122 | The next time you spin up the stack to run tests or to have the WordPress installation locally served, you will be able to debug the code line-by-line using the following settings in your IDE: 123 | 124 | * Listen for XDebug connections on port 9001 125 | * Set up path mappings: 126 | * `_wordpress` -> `/var/www/html` 127 | * `_plugins` -> `/plugins` 128 | * If your IDE allows it, then set the server name and host to `slic`, this is the IDE configuration key XDebug will use when communicating with your host machine. 129 | 130 | Please refer to your IDE of choice to know how to set up these values. 131 | 132 | > Note if you cannot set the above values in your "IDE", then your "IDE" is not an "IDE": it's a powerful and cute text editor. 133 | 134 | When you are done with debuggin and want to deactivate it, just run this command: 135 | 136 | ```bash 137 | slic xdebug off 138 | ``` 139 | 140 | You can get more information about the available XDebug options using the `slic xdebug help` command. 141 | 142 | ## Using the stack as a local development environment 143 | 144 | This is not the stack main purpose, but it can be done as long as you're willing to work on a site served on `http://localhost`. 145 | 146 | You can start the stack, and have it configured for you, running the following command: 147 | 148 | ```bash 149 | slic serve 8888 150 | ``` 151 | 152 | The above command will start the stack, install a fresh copy of WordPress, set it up to look for plugins in the `_plugins` directory, and be served at `http://localhost:8888`. 153 | The stack will also create and scaffold the WordPress installation ins the `_wordpress` directory if it does not exist already. 154 | 155 | You can stop the stack by running the following command: 156 | 157 | ```bash 158 | slic down 159 | ``` 160 | 161 | ### Using wp-cli in the stack 162 | 163 | If you are using the stack as a local development environment, then you might need to interact with it using wp-cli. 164 | In that case you can use the `slic cli` sub-command to run any command on the stack: 165 | 166 | ```bash 167 | slic cli plugin list --status=active 168 | slic cli plugin activate the-events-calendar event-tickets 169 | ``` 170 | 171 | If you need to run any command that would modify a plugin filesystem, remember that, in the container, the plugins are located in the `/plugins` directory. 172 | As an example, if I wanted to dump the current database contents to the `tests/_data/dump.sql` file of `the-events-calendar` plugin, I would run this command: 173 | 174 | ```bash 175 | slic cli db export /plugins/the-events/calendar/tests/_data/dump.sql 176 | ``` 177 | 178 | ## How the stack works, an overview 179 | 180 | The stack services are defined by the `slic-stack.yml` file. 181 | This is a YAML format docker compose configuration file the `slic` binary will use to run the `docker compose` command. 182 | The main services defined there are: 183 | 184 | * `wordpress` - this uses the `wordpress:latest` image, the official Docker image for WordPress. When running the container will fill the `_wordpress` directory with the contents of the WordPress installation that is currently serving the container. Furthermore the WordPress container is configured to look for plugins in the `/plugins` directory, that directory is a shared volume that you can find in the `dev/test/plugins` directory. 185 | * `db` - this is an image that is providing the database for the installation. For performance and isolation reasons the database is **not** persisted across test runs and any data stored in the database will be lost when the container is stopped and removed. 186 | * `cli` - this uses the `wordpress:cli` image to provide wp-cli commands for the stack. 187 | * `codeception` - this service contains the Codeception runner and support code, the image is a custom one adapted to WordPress usage. 188 | * `chrome` - this image provides the Chrome instance that will run the acceptance tests requiring JavaScript support. 189 | 190 | The `slic` command, and the interactive shell, will mostly interact and run commands into the `codeception` image. 191 | -------------------------------------------------------------------------------- /slic.php: -------------------------------------------------------------------------------- 1 | slic at https://github.com/stellarwp/slic 62 | 63 | Available commands: 64 | ------------------- 65 | Popular: 66 | composer Runs a Composer command in the stack. 67 | help Displays this help message. 68 | here Sets the current plugins directory to be the one used by slic. 69 | info Displays information about the slic tool. 70 | logs Displays the current stack logs. 71 | npm Runs an npm command in the stack using the version of node specified by .nvmrc. 72 | phpcbf Runs PHP Code Beautifier and Fixer within the current use target. 73 | phpcs Runs PHP_CodeSniffer within the current use target. 74 | restart Restarts containers in the stack. 75 | run Runs a Codeception test in the stack, the equivalent to 'codecept run ...'. 76 | shell Opens a shell in the `slic` container. 77 | start Starts containers in the stack. 78 | stop Stops containers in the stack. 79 | use Sets the plugin to use in the tests. 80 | using Returns the current use target. 81 | wp Runs a wp-cli command or opens a `wp-cli shell` in the stack. 82 | xdebug Activates and deactivates XDebug in the stack, returns the current XDebug status or sets its values. 83 | playwright Runs Playwright commands in the stack. 84 | 85 | Type {$cli_name} help for info about each command. 86 | HELP; 87 | 88 | $help_advanced_message_template = <<< HELP 89 | Advanced: 90 | airplane-mode Activates or deactivates the airplane-mode plugin. 91 | build-prompt Activates or deactivates whether or not composer/npm build prompts should be provided. 92 | build-stack Builds the stack containers that require it, or builds a specific service image. 93 | build-subdir Activates or deactivates whether or not composer/npm build should apply to sub-directories. 94 | cache Activates and deactivates object cache support, returns the current object cache status. 95 | cc Runs a Codeception command in the stack, the equivalent of 'codecept ...'. 96 | cli Runs a wp-cli command or opens a `wp-cli shell` in the stack; alias of `wp`. 97 | composer-cache Sets or shows the composer cache directory. 98 | config Prints the stack configuration as interpolated from the environment. 99 | debug Activates or deactivates {$cli_name} debug output or returns the current debug status. 100 | down Tears down the stack; alias of `stop`. 101 | dc Runs a docker compose command in the stack. 102 | exec Runs a bash command in the stack. 103 | group Create or remove group of targets for the current plugins directory. 104 | host-ip Returns the IP Address of the host machine from the container perspective. 105 | init Initializes a plugin for use in slic. 106 | interactive Activates or deactivates interactivity of {$cli_name} commands. 107 | mysql Opens a mysql shell in the database service. 108 | ps Lists the containers part of {$cli_name} stack. 109 | php-version Sets or shows the PHP version of the stack. 110 | reset Resets {$cli_name} to the initial state as configured by the env files. 111 | site-cli Waits for WordPress to be correctly set up to run a wp-cli command in the stack. 112 | ssh Opens a shell in the `slic` container; alias of `shell`. 113 | target Runs a set of commands on a set of targets. 114 | up Starts containers in the stack; alias of `start`. 115 | update Updates the tool and the images used in its services. 116 | upgrade Upgrades the {$cli_name} repo. 117 | update-dump Updates a SQL dump file. Optionally, installs a specific WordPress version.. 118 | HELP; 119 | 120 | $help_message = colorize( $help_message_template ); 121 | $help_advanced_message = colorize( $help_advanced_message_template ); 122 | 123 | $is_help = args( [ 'help' ], $args( '...' ), 0 )( 'help', false ) === 'help'; 124 | 125 | 126 | $original_subcommand = $args( 'subcommand' ); 127 | $subcommand = $args( 'subcommand', 'help' ); 128 | 129 | // Both these variables will be used by commands. 130 | $run_settings_file = root( '/.env.slic.run' ); 131 | $cli_name = basename( $argv[0] ); 132 | 133 | if ( 'help' !== $subcommand ) { 134 | maybe_prompt_for_repo_update(); 135 | } else { 136 | $help_subcommand = $args( '...' ); 137 | 138 | if ( $help_subcommand ) { 139 | $subcommand = $help_subcommand[0]; 140 | $is_help = true; 141 | } 142 | } 143 | 144 | if ( ! in_array( $subcommand, [ 'help', 'update' ] ) ) { 145 | maybe_prompt_for_stack_update(); 146 | } 147 | 148 | if ( empty( $subcommand ) || $subcommand === 'help' ) { 149 | echo $help_message . PHP_EOL; 150 | if ( $original_subcommand ) { 151 | echo PHP_EOL . $help_advanced_message; 152 | } else { 153 | echo colorize( PHP_EOL . "There are a lot more commands. Use slic help to see them all!" . PHP_EOL ); 154 | } 155 | maybe_prompt_for_repo_update(); 156 | maybe_prompt_for_stack_update(); 157 | echo PHP_EOL; 158 | exit( 0 ); 159 | } 160 | 161 | /* 162 | * Resolve command aliases. 163 | * A map from the user-facing alias to the command that will be actually called. 164 | */ 165 | $aliases = [ 166 | 'wp' => 'cli', 167 | ]; 168 | if ( isset( $aliases[ $subcommand ] ) ) { 169 | $subcommand = $aliases[ $subcommand ]; 170 | } 171 | 172 | $subcommand_file = __DIR__ . '/src/commands/' . $subcommand . '.php'; 173 | if ( file_exists( $subcommand_file ) ) { 174 | include_once $subcommand_file; 175 | } else { 176 | echo colorize( "Unknown command: {$subcommand}" . PHP_EOL . PHP_EOL ); 177 | echo $help_message . PHP_EOL; 178 | maybe_prompt_for_repo_update(); 179 | maybe_prompt_for_stack_update(); 180 | echo PHP_EOL; 181 | exit( 1 ); 182 | } 183 | 184 | // Add a break line at the end of each command to avoid dirty terminal issues. 185 | echo PHP_EOL; 186 | -------------------------------------------------------------------------------- /src/cache.php: -------------------------------------------------------------------------------- 1 | get( $key, $found ); 20 | 21 | if ( $found ) { 22 | return $value; 23 | } 24 | 25 | return $default; 26 | } 27 | 28 | /** 29 | * Sets a value in the cache. 30 | * 31 | * @param string $key 32 | * @param $value 33 | * 34 | * @return void 35 | */ 36 | function slic_cache_set( string $key, $value ) { 37 | global $slic_cache; 38 | 39 | $slic_cache->set( $key, $value ); 40 | } 41 | 42 | /** 43 | * Flushes the cache. 44 | * 45 | * @return void 46 | */ 47 | function slic_cache_flush(): void { 48 | global $slic_cache; 49 | $slic_cache->flush(); 50 | } 51 | -------------------------------------------------------------------------------- /src/classes/Cache.php: -------------------------------------------------------------------------------- 1 | 20 | */ 21 | private array $cache = []; 22 | 23 | /** 24 | * Gets a value from the cache. 25 | * 26 | * @param string $key 27 | * @param bool $found 28 | * 29 | * @return mixed|null 30 | */ 31 | public function get( string $key, ?bool &$found ) { 32 | if ( isset( $this->cache[ $key ] ) ) { 33 | $found = true; 34 | 35 | return $this->cache[ $key ]; 36 | } 37 | 38 | $found = false; 39 | 40 | return null; 41 | } 42 | 43 | /** 44 | * Sets a value in the cache. 45 | * 46 | * @param string $key 47 | * @param $value 48 | * 49 | * @return void 50 | */ 51 | public function set( string $key, $value ): void { 52 | $this->cache[ $key ] = $value; 53 | } 54 | 55 | /** 56 | * Flushes the cache. 57 | * 58 | * @return void 59 | */ 60 | public function flush() { 61 | $this->cache = []; 62 | } 63 | } 64 | -------------------------------------------------------------------------------- /src/colors.php: -------------------------------------------------------------------------------- 1 | ...` format. 81 | * Nested styles will not work. 82 | * 83 | * @param string $string The string to style and colorize. 84 | * 85 | * @return string The styled and colorized string. 86 | */ 87 | function colorize( $string ) { 88 | $result = preg_replace_callback( 89 | '/<(?