exercise runner docs

Author: AydinHassan

src/ExerciseRunner/CgiRunner.php

@@ -17,11 +17,14 @@
 use PhpSchool\PhpWorkshop\Result\Success;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
+use RuntimeException;
 use Symfony\Component\Process\Process;
 use Zend\Diactoros\Response\Serializer as ResponseSerializer;
 
 /**
- * Class CgiRunner
+ * The `CGI` runner. This runner executes solutions as if they were behind a web-server. They populate the `$_SERVER`,
+ * `$_GET` & `$_POST` super globals with information based of the request objects returned from the exercise.
+ *
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class CgiRunner implements ExerciseRunnerInterface
@@ -38,8 +41,13 @@ class CgiRunner implements ExerciseRunnerInterface
     private $eventDispatcher;
 
     /**
-     * @param CgiExercise $exercise
-     * @param EventDispatcher $eventDispatcher
+     * Requires the exercise instance and an event dispatcher. This runner requires the `php-cgi` binary to
+     * be available. It will check for it's existence in the system's $PATH variable or the same
+     * folder that the CLI php binary lives in.
+     *
+     * @param CgiExercise $exercise The exercise to be invoked.
+     * @param EventDispatcher $eventDispatcher The event dispatcher.
+     * @throws RuntimeException If the `php-cgi` binary cannot be found.
      */
     public function __construct(CgiExercise $exercise, EventDispatcher $eventDispatcher)
     {
@@ -52,15 +60,15 @@ public function __construct(CgiExercise $exercise, EventDispatcher $eventDispatc
                 // Try one more time, relying on being in the php binary's directory (where it should be on Windows)
                 system(sprintf('%s --version %s', $newPath, $silence), $stillFailedToRun);
                 if ($stillFailedToRun) {
-                    throw new \RuntimeException(
+                    throw new RuntimeException(
                         'Could not load php-cgi binary. Please install php-cgi using your package manager.'
                     );
                 }
             }
         } else {
             @system('php-cgi --version > /dev/null 2>&1', $failedToRun);
             if ($failedToRun) {
-                throw new \RuntimeException(
+                throw new RuntimeException(
                     'Could not load php-cgi binary. Please install php-cgi using your package manager.'
                 );
             }
@@ -192,8 +200,21 @@ private function getProcess($fileName, RequestInterface $request)
     }
 
     /**
-     * @param string $fileName
-     * @return ResultInterface
+     * Verifies a solution by invoking PHP via the `php-cgi` binary, populating all the super globals with
+     * the information from the request objects returned from the exercise. The exercise can return multiple
+     * requests so the solution will be invoked for however many requests there are.
+     *
+     * Events dispatched (for each request):
+     *
+     * * cgi.verify.reference-execute.pre
+     * * cgi.verify.reference.executing
+     * * cgi.verify.reference-execute.fail (if the reference solution fails to execute)
+     * * cgi.verify.student-execute.pre
+     * * cgi.verify.student.executing
+     * * cgi.verify.student-execute.fail (if the student's solution fails to execute)
+     *
+     * @param string $fileName The absolute path to the student's solution.
+     * @return ResultInterface The result of the check.
      */
     public function verify($fileName)
     {
@@ -209,9 +230,21 @@ function (RequestInterface $request) use ($fileName) {
     }
 
     /**
-     * @param string $fileName
-     * @param OutputInterface $output
-     * @return bool
+     * Runs a student's solution by invoking PHP via the `php-cgi` binary, populating all the super globals with
+     * the information from the request objects returned from the exercise. The exercise can return multiple
+     * requests so the solution will be invoked for however many requests there are.
+     *
+     * Running only runs the student's solution, the reference solution is not run and no verification is performed,
+     * the output of the student's solution is written directly to the output.
+     *
+     * Events dispatched (for each request):
+     *
+     * * cgi.run.student-execute.pre
+     * * cgi.run.student.executing
+     *
+     * @param string $fileName The absolute path to the student's solution.
+     * @param OutputInterface $output A wrapper around STDOUT.
+     * @return bool If the solution was successfully executed, eg. exit code was 0.
      */
     public function run($fileName, OutputInterface $output)
     {

src/ExerciseRunner/CliRunner.php

@@ -21,7 +21,13 @@
 use Symfony\Component\Process\Process;
 
 /**
- * Class CliRunner
+ * The `CLI` runner. This runner executes solutions as PHP CLI scripts, passing the arguments
+ * from the exercise as command line arguments to the solution. The solution will be invoked like:
+ *
+ * ```bash
+ * php my-solution.php arg1 arg2 arg3
+ * ```
+ *
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 class CliRunner implements ExerciseRunnerInterface
@@ -37,8 +43,10 @@ class CliRunner implements ExerciseRunnerInterface
     private $eventDispatcher;
 
     /**
-     * @param CliExercise $exercise
-     * @param EventDispatcher $eventDispatcher
+     * Requires the exercise instance and an event dispatcher.
+     *
+     * @param CliExercise $exercise The exercise to be invoked.
+     * @param EventDispatcher $eventDispatcher The event dispatcher.
      */
     public function __construct(CliExercise $exercise, EventDispatcher $eventDispatcher)
     {
@@ -76,7 +84,7 @@ private function executePhpFile($fileName, ArrayObject $args, $type)
     }
 
     /**
-     * @param string      $fileName
+     * @param string $fileName
      * @param ArrayObject $args
      *
      * @return Process
@@ -88,8 +96,20 @@ private function getPhpProcess($fileName, ArrayObject $args)
     }
 
     /**
-     * @param string $fileName
-     * @return ResultInterface
+     * Verifies a solution by invoking PHP from the CLI passing the arguments gathered from the exercise
+     * as command line arguments to PHP.
+     *
+     * Events dispatched:
+     *
+     * * cli.verify.reference-execute.pre
+     * * cli.verify.reference.executing
+     * * cli.verify.reference-execute.fail (if the reference solution fails to execute)
+     * * cli.verify.student-execute.pre
+     * * cli.verify.student.executing
+     * * cli.verify.student-execute.fail (if the student's solution fails to execute)
+     *
+     * @param string $fileName The absolute path to the student's solution.
+     * @return ResultInterface The result of the check.
      */
     public function verify($fileName)
     {
@@ -123,9 +143,20 @@ public function verify($fileName)
     }
 
     /**
-     * @param string $fileName
-     * @param OutputInterface $output
-     * @return bool
+     * Runs a student's solution by invoking PHP from the CLI passing the arguments gathered from the exercise
+     * as command line arguments to PHP.
+     *
+     * Running only runs the student's solution, the reference solution is not run and no verification is performed,
+     * the output of the student's solution is written directly to the output.
+     *
+     * Events dispatched:
+     *
+     *  * cli.run.student-execute.pre
+     *  * cli.run.student.executing
+     *
+     * @param string $fileName The absolute path to the student's solution.
+     * @param OutputInterface $output A wrapper around STDOUT.
+     * @return bool If the solution was successfully executed, eg. exit code was 0.
      */
     public function run($fileName, OutputInterface $output)
     {

src/ExerciseRunner/ExerciseRunnerInterface.php

@@ -7,27 +7,44 @@
 use PhpSchool\PhpWorkshop\Result\ResultInterface;
 
 /**
- * Interface ExerciseRunnerInterface
+ * This interface describes how an exercise runner should work. Each exercise type
+ * maps to an exercise runner.
+ *
  * @package PhpSchool\PhpWorkshop\ExerciseRunner
  * @author Aydin Hassan <aydin@hotmail.co.uk>
  */
 interface ExerciseRunnerInterface
 {
     /**
+     * Get the name of the exercise runner.
+     *
      * @return string
      */
     public function getName();
 
     /**
-     * @param string $fileName
-     * @return ResultInterface
+     * Verify a solution to an exercise. Verification involves executing the reference solution
+     * and the student's solution and comparing their output. If the output is the same
+     * an instance of `PhpSchool\PhpWorkshop\Result\SuccessInterface` should be returned, if the output
+     * is not the same, or something else went wrong then an instance of
+     * `\PhpSchool\PhpWorkshop\Result\FailureInterface` should be returned.
+     *
+     * Other things that could go wrong include the student's solution returning a non-zero
+     * exit code, or an notice/warning being exhibited.
+     *
+     * @param string $fileName The absolute path to the student's solution.
+     * @return ResultInterface The result of the check.
      */
     public function verify($fileName);
 
     /**
-     * @param string $fileName
-     * @param OutputInterface $output
-     * @return bool
+     * Run a solution to an exercise. This simply run's the student's solution with the correct input from the exercise
+     * (such as the CLI arguments) and prints the output directly. This allows the student to have the environment
+     * setup for them including getting a different set of arguments each time (if the exercise supports that).
+     *
+     * @param string $fileName The absolute path to the student's solution.
+     * @param OutputInterface $output A wrapper around STDOUT.
+     * @return bool If the solution was successfully executed, eg. exit code was 0.
      */
     public function run($fileName, OutputInterface $output);
 }