diff --git a/README.md b/README.md index 62d2d47..1bb15b4 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [](https://typist.tech/contact/)
- TODO.
+ Generate PHP version matrix according to `composer.json`.
Built with ♥ by Typist Tech
@@ -24,32 +24,194 @@
## Usage
-TODO
-
-### Inputs
-
-TODO
-
-#### `mode`
-
-Available modes:
-- `minor-only` *(default)*: Report `MAJOR.MINOR` versions only
-- `full`: Report all satisfying versions in `MAJOR.MINOR.PATCH` format
-
-#### `source`
-
-Available sources:
-- `auto` *(default)*: Use `offline` in `minor-only` mode. Otherwise, fetch from [php.net](https://www.php.net/releases/index.php)
-- `php.net`: Fetch releases information from [php.net](https://www.php.net/releases/index.php)
-- `offline`: Use [hardcoded releases](https://github.com/typisttech/php-matrix/blob/main/resources/all-versions.json) information
+See [action.yml](action.yml) and the underlying script [`typisttech/php-matrix`](https://github.com/typisttech/php-matrix/#options).
+
+```yaml
+ - uses: typisttech/php-matrix-action@v1
+ with:
+ # Version format.
+ #
+ # Available modes:
+ # - `minor-only`: Report `MAJOR.MINOR` versions only
+ # - `full`: Report all satisfying versions in `MAJOR.MINOR.PATCH` format
+ #
+ # Default: minor-only
+ mode: ''
+
+ # Source of releases information.
+ #
+ # Available sources:
+ # - `auto`: Use `offline` in `minor-only` mode. Otherwise, fetch from [php.net]
+ # - `php.net`: Fetch releases information from [php.net]
+ # - `offline`: Use [hardcoded releases] information
+ #
+ # [php.net]: https://www.php.net/releases/index.php
+ # [hardcoded releases]: https://github.com/typisttech/php-matrix/blob/main/resources/all-versions.json
+ #
+ # Default: auto
+ source: ''
+```
### Outputs
-TODO
+This action yields a single output `matrix` which is a JSON-encoded string of:
+
+| Key | Description | Example |
+| --- | --- | --- |
+| `constraint` | PHP constraint found in `composer.json` | `^7.3 \|\| ^8.0` |
+| `versions` | Array of all supported PHP versions | In `minor-only` mode, `["7.3", "7.4", "8.0", "8.1", "8.2", "8.3", "8.4"]`
In `full` mode, `["7.4.998", "7.4.999", "8.4.998", "8.4.999"]` |
+| `lowest` | Lowest supported PHP versions | In `minor-only` mode, `7.3`
In `full` mode, `7.3.0` |
+| `highest` | Highest supported PHP versions | In `minor-only` mode, `8.4`
In `full` mode, `8.4.2` |
+
+> [!TIP]
+>
+> Use [`fromJSON()`](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson) and [`toJSON()`](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#tojson) to decode the output.
+>
+> ```yaml
+> jobs:
+> php-matrix:
+> runs-on: ubuntu-latest
+> outputs:
+> matrix: ${{ steps.php-matrix.outputs.matrix }}
+> constraint: ${{ fromJSON(steps.php-matrix.outputs.matrix).constraint }}
+> # Use `fromJSON()` when accessing `versions`!
+> versions: ${{ toJSON(fromJSON(steps.php-matrix.outputs.matrix).versions) }}
+> lowest: ${{ fromJSON(steps.php-matrix.outputs.matrix).lowest }}
+> highest: ${{ fromJSON(steps.php-matrix.outputs.matrix).highest }}
+> steps:
+> - uses: actions/checkout@v4
+> - uses: typisttech/php-matrix-action@main
+> id: php-matrix
+> ```
## Examples
-TODO
+Run tests against all supported PHP minor versions.
+
+```yaml
+name: Test
+
+on:
+ push:
+
+jobs:
+ php-matrix:
+ runs-on: ubuntu-latest
+ outputs:
+ matrix: ${{ steps.php-matrix.outputs.matrix }}
+ steps:
+ - uses: actions/checkout@v4
+ - uses: typisttech/php-matrix-action@v1
+ id: php-matrix
+
+ test:
+ runs-on: ubuntu-latest
+ needs: php-matrix
+ strategy:
+ matrix:
+ php: ${{ fromJSON(needs.php-matrix.outputs.matrix).versions }}
+ steps:
+ - uses: actions/checkout@v4
+ - uses: shivammathur/setup-php@v2
+ with:
+ php-version: ${{ matrix.php }}
+ - run: composer install
+ - run: composer test
+```
+
+Run `$ pint --test` with the lowest supported PHP minor version.
+
+```yaml
+name: Pint
+
+on:
+ push:
+
+jobs:
+ pint:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: typisttech/php-matrix-action@v1
+ id: php-matrix
+
+ - uses: shivammathur/setup-php@v2
+ with:
+ php-version: ${{ fromJSON(steps.php-matrix.outputs.matrix).lowest }}
+ tools: pint
+
+ - run: pint --test
+```
+
+Run tests with coverage.
+
+```yaml
+name: Test
+
+on:
+ push:
+
+jobs:
+ php-matrix:
+ runs-on: ubuntu-latest
+ outputs:
+ versions: ${{ toJSON(fromJSON(steps.php-matrix.outputs.matrix).versions) }}
+ highest: ${{ fromJSON(steps.php-matrix.outputs.matrix).highest }}
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ sparse-checkout: composer.json
+ sparse-checkout-cone-mode: false
+
+ - uses: typisttech/php-matrix-action@v1
+ id: php-matrix
+
+ test:
+ runs-on: ubuntu-latest
+ needs: php-matrix
+ strategy:
+ matrix:
+ php: ${{ fromJSON(needs.php-matrix.outputs.versions }}
+ dependency-versions: [lowest, highest]
+ coverage: [none]
+ exclude:
+ - php: ${{ needs.php-matrix.outputs.highest }}
+ dependency-versions: highest
+ coverage: none
+ include:
+ - php: ${{ needs.php-matrix.outputs.highest }}
+ dependency-versions: highest
+ coverage: xdebug
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: shivammathur/setup-php@v2
+ with:
+ php-version: ${{ matrix.php }}
+ coverage: ${{ matrix.coverage }}
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ - uses: ramsey/composer-install@v3
+ with:
+ dependency-versions: ${{ matrix.dependency-versions }}
+
+ - run: composer test:with-coverage
+ if: ${{ matrix.coverage == 'xdebug' }}
+
+ - run: composer test:without-coverage
+ if: ${{ matrix.coverage != 'xdebug' }}
+```
+
+