Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 45 additions & 65 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,112 +5,92 @@ Exercism exercises in PHP
Follow these instructions to contribute to the PHP track.
To solve the exercises, head to the [PHP track][exercism-track-home] and check the [documentation][exercism-track-installation].

## Quick Start with Dev Containers
## Quick Start

This repo includes a [dev container](.devcontainer) that provides PHP 8.4, Composer, `jq` and all other dependencies out of the box.
Open the repo in [VS Code][vscode-devcontainers] (or [GitHub Codespaces][github-codespaces]) and select "Reopen in Container" - `composer install` runs automatically once it starts.
### Dev containers

## Install Dependencies
This repo includes a [dev container](.devcontainer) that provides PHP 8.4, `composer`, `jq` and all other dependencies out of the box.
Open the repo in [VS Code][vscode-devcontainers] (or [GitHub Codespaces][github-codespaces]) and select "Reopen in Container".

The following system dependencies are required:
### Local

- `composer`, as recommended in the [PHP track installation docs][exercism-track-installation-composer].
- [`bash` shell][gnu-bash].
- PHP V8.4+ CLI, with the following extensions:
- `ds` (V1.x)
- `intl`
- Default modules: `Core`, `ctype`, `date`, `dom`, `fileinfo`, `filter`, `hash`, `iconv`, `json`, `libxml`, `mbstring`, `pcre`, `random`, `Reflection`, `SimpleXML`, `sodium`, `SPL`, `standard`, `tokenizer`, `xml`, `xmlreader`, `xmlwriter`, `zlib`
- An active Internet connection for installing required tools / composer packages.
- [`jq`][jq], if you change the difficulty or add a practice exercise.
For a non-devcontainer setup, see `.devcontainer/` for exact setup.

The [dev container](.devcontainer) already provides all of the above.

Run the following command to get started with this project:
In particular the required dependencies are: `bash`, `jq`, `php8.4`, `composer`, `ext-gmp`, `ext-ds` (v1.x), `ext-intl`.

Install composer dependencies with:
```shell
composer install # Required dependencies to develop this track
~/> composer install
contribution/> composer install
```

## Running Exercism resources management

`bin/configlet` is the official tool for managing Exercism language track repositories.
See [Building Exercism docs][exercism-configlet].

For convenience, you can use `composer configlet:fmt` to fix formatting issues in the Exercism track files.
This is included in `composer ci` to run the CI checks locally.

## Running Unit Test Suite

The tests are run with PHPUnit. A shell loop injecting `exemplar.php` is provided to ease testing.
## PHP track maintenance

Execute the following command to run the tests:
[`bin/configlet`][exercism-configlet] is the official tool for managing Exercism language track repositories.

```shell
composer test:run
```

This is included in `composer ci` to run the CI checks locally.
### Running Unit Test Suite

### Run a specific test

If you want to run tests for one specific exercise, you can do it with following cli command.
The tests are run with PHPUnit. Execute the following command to run the tests:

```shell
composer test:run -- exercise-name
# e.g
composer test:run -- book-store
~/> composer tests:run # Runs whole test suite
~/> composer tests:run -- <slug> # Runs tests for <slug> (e.g. book-store)
~/> composer tests:run -- "b*" # Runs tests for <slug> starting with `b`
```

If you want to run all starting with let's say 'b' you can run
### Code style

```shell
composer test:run -- "b*"
```
[`bin/configlet fmt`][exercism-configlet-fmt] checks Exercism's ressources files (json).

## Running Style Checker
`composer lint:check` checks PHP files using a slightly [modified][local-file-phpcs-config] version of [PSR-12].

This project uses a slightly [modified][local-file-phpcs-config] version of [PSR-12].
Use the following commands to apply code style:
Autofix (for both Exercism and PHP files) is provided with `composer format:fix`.

```shell
composer lint:check # Checks the files against the code style rules
composer lint:fix # Automatically fix code style issues
```
### Continuous Integration

The `lint:check` is included in `composer ci` to run the CI checks locally.
`composer ci` invokes the above checks: [code style][h-code-style], [tests][h-unit-tests].

## Contributing

- Read the documentation at [Exercism][exercism-docs].
- Follow the [PSR-12] coding style (Exercisms PHP track uses a slightly [modified][local-file-phpcs-config] version of [PSR-12]).
- Follow the [PSR-12] coding style (Exercism's PHP track uses a slightly [modified][local-file-phpcs-config] version of [PSR-12]).
- Run `composer ci` to run CI checks locally before pushing.
- CI is run on all pull requests, it must pass the required checks for merge.
- CI is running all tests on PHP 8.1 to PHP 8.4 for Linux, Windows and MacOS.
- CI runs on all pull requests, it must pass the required checks for merge.
- CI runs all tests on PHP 8.2 to PHP 8.4 for Linux, Windows and MacOS.
- [Contribution tools](./contribution/README.md) are available.

### Generating new practice exercises

Adding a new exercise involves multiple steps

## Generating new practice exercises
#### 1. Initialize exercism resources

Use `bin/configlet create --practice-exercise <slug>` to create the exercism resources required.
This provides you with the directories and files in `exercises/practice/<slug>`.
Look into `tests.toml` for which test cases **not** to implement / generate and mark them with `include = false`.

Test generator MVP used like this:
#### 2. Write tests

```shell
composer -d contribution/generator install
contribution/generator/bin/console app:create-tests '<slug>'
composer lint:fix
```
Once the directory structure is created either:
1. Use `php contribution/main.php exercism:test:bootstrap <slug>` to init a test file with tests bodies to implement.
2. Create a `<ExerciseSlug>Test.php.twig` file and run `php contribution/main.php exercism:test:generate <slug>` to render the corresponding `<ExerciseSlug>Test.php` file.

A `.meta/example.php` file is also necessary in order to validate that the implementation is correct / achievable.

#### 3. Miscellaneous

Run `bin/order-exercises.sh` when you set the exercise difficulty to a sensible value to order the exercises on the website accordingly.

Ensures that the [test suite runs][h-unit-tests] and that the files are properly [formatted][h-code-style].

[exercism-configlet]: https://exercism.org/docs/building/configlet
[exercism-configlet-fmt]: https://exercism.org/docs/building/configlet/format
[exercism-docs]: https://exercism.org/docs
[exercism-track-home]: https://exercism.org/docs/tracks/php
[exercism-track-installation]: https://exercism.org/docs/tracks/php/installation
[exercism-track-installation-composer]: https://exercism.org/docs/tracks/php/installation#h-install-composer
[github-codespaces]: https://docs.github.com/en/codespaces/overview
[gnu-bash]: https://www.gnu.org/software/bash/
[jq]: https://jqlang.org/
[local-file-phpcs-config]: phpcs.xml
[psr-12]: https://www.php-fig.org/psr/psr-12
[vscode-devcontainers]: https://code.visualstudio.com/docs/devcontainers/containers
[h-code-style]: #code-style
[h-unit-tests]: #running-unit-test-suite
2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@
],
"format:fix": [
"@lint:fix",
"@configlet:fmt"
"@configlet:fmt --update --yes"
],
"lint:check": "phpcs",
"lint:fix": "phpcbf",
Expand Down
29 changes: 8 additions & 21 deletions contribution/README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,19 @@
Commands to automate some contribution part of `exercism/php`.

They are all invokable with `php main.php <command>`.
They are all invokable with `php main.php <command> <arguments>`.

## `exercism:deprecated`

checks upstream deprecated exercises
Lists upstream-deprecated exercises that are not track-deprecated yet.

## `exercism:create-tests`
Those exercises should be flagged with `"status": "deprecated"` in the PHP track.

This is a small poc on how we could auto generate tests for the PHP track based on the https://github.com/exercism/problem-specifications/.
## `exercism:test:bootstrap`

How to test it:
Bootstrap an `<ExerciseSlug>Test.php` file for argument `<exercise-slug>`.

```
git clone https://github.com/tomasnorre/exercism-tests-generation.git
cd exercism-tests-generation
composer install
php main.php exercism:create-tests nucleotide-count
vendor/bin/phpunit src/Command/NucleotideCountTest.php
```
Tests functions have to be implemented manually afterward.

If you now make a `git status` you will see that the `src/Command/NucleotideCountTest.php` and you can now inspect the auto generated tests.
## `exercism:test:generate`

It's all based on the `nikic/php-parser` and the https://github.com/exercism/problem-specifications/ repository, I have made a local copy of that on file
for now to spare the http-requests.

Let me know what you think.

## `exercism:generate-tests`

Generate tests from a twig template file
Generate `<ExerciseSlug>Test.php` files from `<ExerciseSlug>Test.php.twig` files for argument `<exercise-slug>`.
19 changes: 9 additions & 10 deletions contribution/main.php
Original file line number Diff line number Diff line change
Expand Up @@ -5,25 +5,24 @@

require_once __DIR__ . '/vendor/autoload.php';

use App\Command\CreateTestsCommand;
use App\Command\Deprecated;
use App\Command\GenerateTests;
use App\Configlet;
use App\Command\TestGenerate;
use App\Command\TestBootstrap;
use App\Service\Configlet;
use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
use Symfony\Component\Console\Application;
use Symfony\Component\HttpClient\HttpClient;

$application = new Application();
$repositoryRoot = __DIR__ . '/../';
$configlet = new Configlet($repositoryRoot . '/bin/configlet', $repositoryRoot);
$exercises = new Filesystem(new LocalFilesystemAdapter($repositoryRoot . '/exercises'));

$exercises = new LocalFilesystemAdapter(__DIR__ . '/../exercises');
$application->addCommand(
new Deprecated(
new Filesystem($exercises),
HttpClient::createForBaseUri('https://github.com/exercism/problem-specifications'),
),
new Deprecated($exercises, HttpClient::createForBaseUri('https://github.com/exercism/problem-specifications')),
);
$application->addCommand(new CreateTestsCommand(__DIR__ . '/..'));
$application->addCommand(new GenerateTests(new Configlet(__DIR__ . '/../bin/configlet'), new Filesystem($exercises)));
$application->addCommand(new TestBootstrap($configlet, $exercises));
$application->addCommand(new TestGenerate($configlet, $exercises));

$application->run();
62 changes: 0 additions & 62 deletions contribution/src/Command/CreateTestsCommand.php

This file was deleted.

2 changes: 1 addition & 1 deletion contribution/src/Command/Deprecated.php
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@

use const JSON_THROW_ON_ERROR;

#[AsCommand('exercism:deprecated', 'This command allows you to check for deprecated exercises...')]
#[AsCommand('exercism:deprecated', 'Lists upstream-deprecated exercises that are not track-deprecated yet.')]
readonly class Deprecated
{
public function __construct(
Expand Down
Loading
Loading