DOCSEARCHbyAlgolia
Submit Docs

PhpSchool Documentation

website·Indexed 33 days ago

https://www.phpschool.io/docs

Documentation for the PhpSchool workshop framework, including guides on creating workshops, developing exercises, and implementing custom result renderers and listener checks. Provides technical reference for exercise types, events, and the container system.

Tokens
17.5K
Snippets
63
Records
99
Agent score
60%

What's inside PhpSchool

  1. Overview of the Workshop Tutorial

    The Workshop Tutorial provides a guided path for developers and educators to build a hands-on teaching environment. The tutorial is divided into three primary phases: creating and setting up a new workshop, customizing the visual theme to match a brand or subject, and developing the first exercise. A reference implementation of a simple workshop is available on GitHub for comparison and troubleshooting.
    # Reference implementation for a simple workshop
https://github.com/php-school/simple-math

  2. Overview of bundled exercise checks

    The workshop framework includes several built-in checks to validate student submissions. Most bundled checks support CLI and CGI exercise types. Some checks are automatic and do not need to be manually registered.

  3. Overview of Exercise Checks in php-school.io

    Exercise Checks are additional verifications performed during the process of verifying a student's solution. While the framework primarily compares student output against a reference solution, checks allow for extra validation logic. Each exercise can utilize multiple checks.

  4. Implement a reference solution for exercises

    Every CGI and CLI type exercise requires a reference solution. This solution is used to verify student submissions by comparing outputs and to provide a proposed optimal solution to the student upon completion. Solutions must implement the PhpSchool\PhpWorkshop\Solution\SolutionInterface.

  5. Understand the Result and Rendering system

    In the PhpSchool workshop framework, after a student's solution is verified, the result set is rendered to the console. The result set is an instance of PhpSchool\PhpWorkshop\ResultAggregator and consists of multiple individual results. Verification is considered a failure if any single result in the set is a failure. Each result is associated with a renderer that converts the result's information into a console output string.

  6. Create a PHP workshop exercise

    To create a new exercise in a PHP workshop, follow these four steps:

    1. Decide on a topic: Define the specific concept or problem the student needs to solve.
    2. Create a reference solution: Write a working PHP program that solves the problem. This is used to compare the student's output against the expected result.
    3. Create a problem file: Write a markdown file containing instructions, hints, and sample code for the student.
    4. Write the exercise class: Implement a PHP class that defines the exercise's metadata, type, and runtime arguments.

  7. Understand Listener Checks in PhpSchool

    Listener Checks are advanced verification components that allow developers to hook into the exercise verification and execution process with granular precision. Unlike Simple Checks, which run generally before or after verification, Listener Checks can execute code at any point where an event is dispatched by the framework. They are ideal for complex requirements such as managing external dependencies (e.g., databases) or performing multi-stage verification.

  8. Create a problem description file

    The problem file provides instructions to the student and is rendered in the terminal. It should be a markdown file located at: exercises/<exercise-name>/problem/problem.md.

    Best practices for problem files:

    • Provide a clear description of the problem.
    • Include sample code that students can modify.
    • Offer hints and tips.
    • Provide links to official PHP documentation or reputable sources.
    • Use the {appname} placeholder; it will be automatically replaced with the actual application name configured for the workshop.

  9. Set up PHP School environment on Windows

    Because of command line and console emulator differences, the recommended way to run PHP School Workshops on Windows is by installing Cygwin and ConEmu.

    1. Cygwin: Download from https://cygwin.com/install.html. During installation, ensure ALL PHP packages are selected. Installing GIT and VIM is also recommended.
    2. ConEmu: Download from https://conemu.github.io/. After installation, open ConEmu and select 'Cygwin Bash'.
    3. Path Verification: If workshops do not run immediately after installation, ensure the PHP School bin directory is in your $PATH.
    # Verify if bin directory is in $PATH
workshop-manager verify

  10. Implement a Listener Check using ListenableCheckInterface

    To create a Listener Check, implement the ListenableCheckInterface. This requires defining the check's name and specifying an optional interface that the exercise must implement to interact with the check. The attach method is used to register listeners with the EventDispatcher.
    namespace PhpSchool\SimpleMath;

use PhpSchool\PhpWorkshop\Check\ListenableCheckInterface;
use PhpSchool\PhpWorkshop\Event\EventDispatcher;

class CouchDbCheck implements ListenableCheckInterface
{
    public function getName()
    {
        return 'Couch DB Verification Check';
    }

    public function getExerciseInterface()
    {
        return CouchDbExerciseCheck::class;
    }

    public function attach(EventDispatcher $eventDispatcher)
    {
        // Register event listeners here
    }
}

  11. Implement a custom Listener Check for database verification

    A Listener Check allows the workshop framework to perform setup and verification tasks (like database seeding) by listening to specific framework events. To create one, implement the ListenableCheckInterface. The check must define its name, the interface that exercises requiring this check must implement, and the logic to attach listeners to the EventDispatcher.
    namespace PhpSchool\SimpleMath;

use PhpSchool\PhpWorkshop\Check\ListenableCheckInterface;
use PhpSchool\PhpWorkshop\Event\EventDispatcher;

class CouchDbCheck implements ListenableCheckInterface
{
    public function getName()
    {
        return 'Couch DB Verification Check';
    }

    public function getExerciseInterface()
    {
        // The interface the exercise must implement to use this check
        return CouchDbExerciseCheck::class;
    }

    public function attach(EventDispatcher $eventDispatcher)
    {
        // Define event listeners here
        $eventDispatcher->listen('verify.start', function (Event $e) {
            // Setup logic
        });
    }
}

  12. Transform solution code using AST

    Transformers allow for complex modifications of the entire solution using an Abstract Syntax Tree (AST). A transformer is a PHP callable that accepts an array of PhpParser\Node objects (the parsed solution) and returns a modified array of PhpParser\Node objects. This feature relies on the nikic/php-parser library.
    use PhpSchool\PhpWorkshop\Patch;
use PhpParser\Node\Stmt\TryCatch;
use PhpParser\Node\Stmt\Catch_;
use PhpParser\Node\Name;
use PhpParser\Node\Stmt\Echo_;
use PhpParser\Node\Expr\MethodCall;
use PhpParser\Node\Expr\Variable;

$wrapInTryCatch = function (array $statements) {
    return [
        new TryCatch(
            $statements,
            [
                new Catch_(
                    new Name('Exception'),
                    'e',
                    [
                        new Echo_([
                            new MethodCall(new Variable('e'), 'getMessage')
                        ])
                    ]
                )
            ]
        )
    ];
};

$patch = (new Patch())->withTransformer($wrapInTryCatch);