Documentation

Exercise Checks#^ TOP

The main task of the workshop framework is to compare the output of the student's solution with the output of the reference solution, it is not however, limited to this. In this article we will introduce the workshop exercise check feature.

What are Checks?#^ TOP

Checks are extra verifications that can be performed during the process of verifying a students solution to an exercise. Each exercise can utilise any amount of additional checks.

Check Types#^ TOP

There are two types of checks: Simple & Listener. What are the differences? Read on!

Simple Checks

Simple checks are basically a block of code that can run before or after verifying the output of the students solution. There can be many checks, which will be run sequentially - each check can return a success or failure and this will be injected into the result set.

Listener Checks

Listener checks are more advanced - when you add a listener type check, it will be passed an event dispatcher (PhpSchool\PhpWorkshop\Event\EventDispatcher) which can be used to listen to various events throughout the life-cycle of verifying. Learn more about Listener Checks and the events which can be listened to in the Listener checks documentation.

How to use a check in your exercise?#^ TOP

1. Tell the dispatcher about your check requirements

In order to specify that your exercise requires additional checks you should implement the method configure in your exercise. It will be passed an instance of ExerciseDispatcher which you can interact with and tell it which checks your exercise requires. The method configure is already implemented in AbstractExercise, but is empty, so you don't need to call parent::configure($dispatcher) inside your method.

class MyExercise extends AbstractExercise implements ExerciseInterface
{
    ...snip

    /**
     * @param ExerciseDispatcher $dispatcher
     */
    public function configure(ExerciseDispatcher $dispatcher)
    {
        $dispatcher->requireCheck(ComposerCheck::class);
    }
}

This basically informs the workshop framework that when verifying the student's solution to this exercise, we should also run the ComposerCheck check. To learn what the ComposerCheck check actually does go to the Bundled Checks page.

2. Implement the required interface and methods

The second and final step is to implement the correct interface in your exercise. If you do not do this the workshop framework will throw an exception when it tries to run the check. Each check has an interface you need to implement when requiring it in your exercise. This interface can be found by visiting the Bundled Checks page or by looking at the getExerciseInterface() method of the check. This method returns a string containing the FQCN (Fully Qualified Class Name) of the interface the check requires your exercise to implement.

Some of the bundled checks only require you to implement PhpSchool\PhpWorkshop\Exercise\ExerciseInterface which you will have to do anyway as part of building your exercise. Some checks require you to implement additional interfaces which introduce new methods to your exercise. These methods provide the checks with the necessary information to execute. For example, the ComposerCheck requires you to implement the PhpSchool\PhpWorkshop\ExerciseCheck\ComposerExerciseCheck interface, which, in turn, requires your exercise to implement the method getRequiredPackages.

So, your exercise, taking advantage of the ComposerExerciseCheck may end up looking something like the following:

class MyExercise extends AbstractExercise implements
        ExerciseInterface,
        ComposerExerciseCheck
{
    ...snip

    /**
     * @param ExerciseDispatcher $dispatcher
     */
    public function configure(ExerciseDispatcher $dispatcher)
    {
        $dispatcher->requireCheck(ComposerCheck::class);
    }

    /**
     * @return array
     */
    public function getRequiredPackages()
    {
        return [
            'nikic/fast-route'
        ];
    }

}