+
+ Note: You do not need to require this check yourself, it is done so automatically.
+ Learn how to use
+
diff --git a/assets/components/Website/Docs/CodeBlock.vue b/assets/components/Website/Docs/CodeBlock.vue
new file mode 100644
index 00000000..1af31dd9
--- /dev/null
+++ b/assets/components/Website/Docs/CodeBlock.vue
@@ -0,0 +1,87 @@
+
+
+
+ There are numerous services exposed via the DI container. The services exposed to user-land code are listed below. These can be used in your exercises, custom-checks and other services you may
+ create as part of your workshop.
+
+
+
+ There are actually many more services exposed but these are for internal use of the workshop framework only. These services should not be used. If you decide to ignore the advice given here, you
+ should take caution as backwards compatibility breaks may be introduced in minor versions. If you feel a service should be public, contact us and we can discuss it!
+
+
+
+
+
Colors\Color
+
+ An instance of
+ Colors\Color
+ . Use this to apply ANSI styles to strings. For example, to colour a string ready to be printed to the console.
+
+
+
+
PhpSchool\PhpWorkshop\Output\OutputInterface
+
A utility class to print content to the standard output stream. Currently this is the standard out connected to the terminal.
+
+
+
PhpSchool\PhpWorkshop\ExerciseRepository
+
This is a repository of exercises allowing to retrieve exercises and get information regarding them.
+
+
+
PhpSchool\PhpWorkshop\ExerciseRepository
+
This is a repository of exercises allowing to retrieve exercises and get information regarding them.
+
+
+
PhpSchool\PhpWorkshop\Event\EventDispatcher
+
EventDispatcher allows listening to events and inserting verifiers at certain points throughout the verifying
+ An instance of
+ PhpParser\Parser
+ which allows to parse PHP code in to an AST structure.
+
+
+
+
PhpSchool\PhpWorkshop\CodePatcher
+
Utility to apply patches to PHP code from Exercises.
+
+
+
PhpSchool\CliMenu\Terminal\TerminalInterface
+
+ An implementation of
+ PhpSchool\CliMenu\Terminal\TerminalInterface
+ which allows to retrieve and control the current terminal. For example getting the current terminal width.
+
+
+
+
PhpSchool\PhpWorkshop\MarkdownRenderer
+
A utility to render Markdown to a string which should display nicely in a console terminal using ANSI escape sequences to format the output.
+
+
+
PhpSchool\PhpWorkshop\UserState
+
This object provides access to the list of the exercises the student has completed and the exercise they are currently studying.
+
+
+
PhpSchool\PSX\SyntaxHighlighter
+
+ An instance of
+ PhpSchool\PSX\SyntaxHighlighter
+ which highlights PHP code using ANSI escape sequences ready to output on a console terminal.
+
+ This article documents each of the checks bundled with the workshop framework and how to use them. Remember the exercise types from the
+ Exercise Types documentation
+ ?
+ CLI
+ ,
+ CGI
+ &
+ CUSTOM
+ .
+
+
+
Well, checks can support one or more of these exercise types types. So inspect the table below to see if the check you want to use actually supports your exercise type.
+
+
+
+
+ This check verifies that the student's solution file actually exists. This check is always registered as the first check and verifying will abort if it fails.
+
+
+
+
+ This check verifies that the student's solution file can actually be parsed. Parsing is done with
+ nikic/php-parser
+
+
+
+
+ This check verifies that the student's solution file contains valid PHP syntax. This is as simple as
+ php -l <submission-file>
+
+
+
+
+ This check verifies that the students submission contains usages of some required functions and also does not use certain functions. This check is useful if you want to ban a certain way of
+ achieving something, for example, teaching how to manually write a function that already existing in the standard library.
+
+
+
+
+ This check verifies that the student used Composer to install the required dependencies of the exercise. It checks that a
+ composer.lock
+ files exists and contains entries for the required packages.
+
+
+
+
+ This check sets up a database and a
+ PDO
+ object. It prepends the database DSN as a CLI argument to the student's solution so they can connect to the database. The
+ PDO
+ object is passed to the exercise before and after the student's solution has been executed, allowing you to first seed the database and then verify the contents of the database.
+
+
+
+
+ Functional Requirements Check
+
+ Here is an example of how to force the student to use the function
+ curl_exec
+ and ban the usage of
+ file_get_contents
+ . This could be useful if you wanted to teach advanced configuration of data transfers.
+
+ Here is an example of how to force the student to require the
+ nikic/fast-route
+ package via Composer. This is useful if you want to focus on a specific problem or promote popular/battle tested packages.
+
+ A number of failures can occur here, the student may not even have a
+ composer.json
+ or a
+ composer.lock
+ file. If this is the case, the check will fail and a message will be printed. If the required files are present, but the package has not been found, the output will look like the following:
+
+ Here is an example where we require that the student insert a record in to the
+ users
+ table which we will create in the
+ seed
+ method of our check. We will then verify that there are some records in the
+ users
+ table.
+
+ After a student's solution has been verified, the result set is rendered to the console. The result set is made up of several individual results. Verification is deemed to have failed if any one
+ of those results is a failure. Each result represents a different thing, for example, each check will likely inject a result in to the result set. The output verification will be a single result,
+ the parsing of the file will be a single result, and so on.
+
+
+
Each Result class has an associated renderer, the renderers job is to take the information from the result and render in to the console.
+
+
+ Results are what
+ Exercise Checks
+ should return and inject. You will learn more about how to actually use the results in your checks in a
+ later article
+ .
+
+
+ The Result Set
+
+ The result set is an instance of
+ PhpSchool\PhpWorkshop\ResultAggregator
+ and results are added to it with
+ add(ResultInterface $result)
+ . Note the interface
+ PhpSchool\PhpWorkshop\Result\ResultInterface
+ . Every result must implement this interface.
+
+
+ Success or Failure?
+
+ So, how do we know if a result is a success or failure? Well there are two other interfaces, extending from
+ ResultInterface
+ , which are:
+
+
+
+
PhpSchool\PhpWorkshop\Result\SuccessInterface
+
PhpSchool\PhpWorkshop\Result\FailureInterface
+
+
+
Both of these interfaces add no extra methods, they are purely for determining whether a result is considered a success or failure.
+
+ Result Interface
+
+ The interface for
+ ResultInterface
+ is very simple:
+
+
+
+
+<?php
+
+interface ResultInterface
+{
+ /**
+ * @return string
+ */
+ public function getCheckName();
+}
+
+
+
This method should just return the name of the check associated with this result. This is used when rendering the result to the console.
+
+ Implementations
+
+ There are default implementations for
+ SuccessInterface
+ &
+ FailureInterface
+ for you to use in your checks. If you need something more bespoke to render the failure of your check, you should
+ create your own
+ .
+
+
+ PhpSchool\PhpWorkshop\Result\Success
+
As you saw from the interface, the only required piece of information is the check name. So construction would look like the following.
+ If you are within a Check (eg
+ $this
+ refers to
+ PhpSchool\PhpWorkshop\Check\CheckInterface
+ ) then you can use the static constructor
+ fromCheck(CheckInterface $check)
+ which just pulls the check name from the actual check for convenience.
+
+ The default implementation of
+ FailureInterface
+ needs one more piece of information other than the check name: the reason for the failure. Construction is fairly similar:
+
+
+
+
+<?php
+
+use PhpSchool\PhpWorkshop\Result\Failure;
+
+//constructor
+$failure = new Failure('My Check', 'Something went wrong!');
+
+//static constructor
+$failure = Failure::fromNameAndReason('My Check', 'Something went wrong!');
+
+//static constructor with check
+$myCheck = new MyCheck;
+$failure = Failure::fromCheckAndReason($check, 'Something went wrong!');
+
+
+
+ Bundled Failure Implementations
+
+ There are a number of
+ FailureInterface
+ implementations bundled with the framework for some of the other checks:
+
+ When you want to report information that is not simple a message, you will need to create your own result class. If you would build a check that verifies the contents of a database, you may want
+ to provide a list of missing records as an array instead of just a message. You would then write a renderer that may render each row as a new line with a bullet point preceding it. Learn how to
+ create your own checks
+ in a later article
+ .
+
+
+ Result Renderers
+
+ Each result renderer must implement the interface
+ PhpSchool\PhpWorkshop\ResultRenderer\ResultRendererInterface
+ which looks like below.
+
+ PhpSchool\PhpWorkshop\ResultAggregator
+ is rendered by
+ PhpSchool\PhpWorkshop\ResultRenderer\ResultsRenderer
+ . It loops each result, passing the result to
+ PhpSchool\PhpWorkshop\Factory\ResultRendererFactory
+ which returns the correct renderer. The
+ render
+ method is called and then the output of each is written to the console.
+
+
+
+ When each renderer is created, it is passed the
+ ResultInterface
+ as the first constructor argument.
+ render
+ is called with an instance of
+ PhpSchool\PhpWorkshop\ResultRenderer\ResultsRenderer
+ and it should return a string representation of the
+ ResultInterface
+ instance it was constructed with.
+
+
+
+ PhpSchool\PhpWorkshop\ResultRenderer\ResultsRenderer
+ has some helper methods on it for rendering styling:
+
+
+
+
+ style($string, $colourOrStyle)
+ - Use to style a string, eg.
+ bold
+ ,
+ green
+ . It accepts an array of styles or one style as a string
+
+
+ lineBreak()
+ - Use to render a line break, to separate content.
+
+
+ center()
+ - Pad a string according to the terminal width so it displays in the center
+
+
+
+ Result Renderer Mappings
+
+ The workshop framework picks a result renderer based on the mappings in
+ PhpSchool\PhpWorkshop\Factory\ResultRendererFactory
+ .
+
+
+
+
+
+ If you create a new implementation of
+ FailureInterface
+ you will need to map it to an existing renderer, or most likely you will need to write a custom renderer, and map it to that.
+
+
+ Summary
+
+ The whole process may sound complicated, however, this is not true. To summarise, your check should return a result. The result should be mapped to a renderer. The results are rendered by the
+ framework. It will pick the correct renderer based on the mapping.
+
+
+ Create a custom result
+
+ In the next set of articles we will learn about and build a check. Once the check is complete, we will build a custom result and result renderer for it, you can jump
+ straight there if you want
+ .
+
+
diff --git a/templates/docs/reference/creating-custom-result-renderers.phtml b/assets/components/Website/Docs/Sections/Reference/CreatingCustomResultRenderers.vue
similarity index 53%
rename from templates/docs/reference/creating-custom-result-renderers.phtml
rename to assets/components/Website/Docs/Sections/Reference/CreatingCustomResultRenderers.vue
index d517e677..cdc4cd02 100644
--- a/templates/docs/reference/creating-custom-result-renderers.phtml
+++ b/assets/components/Website/Docs/Sections/Reference/CreatingCustomResultRenderers.vue
@@ -1,18 +1,25 @@
-
If you don't know what result renderers are, go ahead and read
- this article first. We will be continuing on from the previous article,
- let's go ahead and create the renderer.
+
+
+
+ If you don't know what result renderers are, go ahead and read
+ this article
+ first. We will be continuing on from the previous article, let's go ahead and create the renderer.
+
This is really simple: the render(ResultsRenderer $renderer) just returns a string
-representation of the result, we style the results a little in a bullet pointed list, highlighting them red.
-We also add a title which describes the coding standard used.
-
-
That's basically it - we just need to register the renderer with the application.
-
-
3. Register the renderer
-
Now you need to tell the application about your new result. Open up app/bootstrap.php and
-after the application object is created you just call addResult with the result class name
- and the result renderer class name. Your final app/bootstrap.php file should look something like:
-
-
<?php
+
+
+
+
+ This is really simple: the
+ render(ResultsRenderer $renderer)
+ just returns a string representation of the result, we style the results a little in a bullet pointed list, highlighting them red. We also add a title which describes the coding standard used.
+
+
+
That's basically it - we just need to register the renderer with the application.
+
+ 3. Register the renderer
+
+ Now you need to tell the application about your new result. Open up
+ app/bootstrap.php
+ and after the application object is created you just call
+ addResult
+ with the result class name and the result renderer class name. Your final
+ app/bootstrap.php
+ file should look something like:
+
-
-renderContentHeader('try-it-out', 'Try it out!') ?>
-
-
Run the workshop and select the Mean Average exercise. Verifying a solution which does not pass the
- PSR2 coding standard will yield the following output:
You can see the finished, working code on the custom-result branch of the
- tutorial repository.
+
+
+
+ Try it out!
+
+
+ Run the workshop and select the Mean Average exercise. Verifying a solution which does not pass the
+ PSR2
+ coding standard will yield the following output:
+
In this article we will build a custom result for our PSR2 check. In the next article, we will build the renderer for it, as the result is fairly useless without it.
+
+
+ We want to be able to list out each of the coding standard violations as part of the feedback to the student. To do this, we will write our result (which is mostly a simple object containing the
+ data) and then we will update our check to parse the violations and use the new result class.
+
+
+ Getting Started
+
If you are carrying on from the previous article then you can skip this first step of grabbing the tutorial workshop.
+
+
+ As usual we will use the already built tutorial workshop as a base - the finished code is available on the
+ custom-result
+ branch of the
+ tutorial repository
+ . We will start fresh from the
+ custom-interface-check
+ branch for this tutorial, so if you haven't already got it, git clone it and install the dependencies:
+
+
+
+
+ 1. Create the folder and class
+
+
+ 2. Write the result class
+
+
+
+ This is a simple class which takes in the check name, the standard used & and an array of violations.
+ getCheckName()
+ should return the name of the check this result represents, this is used when rendering the results to the student by the workshop framework. This is the only method required by the interface
+ PhpSchool\PhpWorkshop\Result\FailureInterface
+ .
+
+
+ 3. Update the Check
+
+
+ We need to update our check to use the new result class, and we need to parse the violations from
+ phpcs
+ . We will only be making changes in the
+ check
+ method and the final method should look like the following:
+
+ We add the option
+ --report=json
+ to give us the report in json, which makes it easier to parse.
+
+
+ We
+ json_decode
+ the first line of output from
+ phpcs
+ .
+
+
We grab the violations for the students submission.
+
We format each violation in to a string consisting of the line number, column and message.
+
Return a instance of our new result class containing the check name, coding standard and an array of violations.
+
+
+ That's it! Move on to the next article to build the renderer.
+ If you try to run verify the exercise now, the program will crash as it cannot find a renderer for the new result.
+
diff --git a/assets/components/Website/Docs/Sections/Reference/CreatingListenerChecks.vue b/assets/components/Website/Docs/Sections/Reference/CreatingListenerChecks.vue
new file mode 100644
index 00000000..96a8f2ab
--- /dev/null
+++ b/assets/components/Website/Docs/Sections/Reference/CreatingListenerChecks.vue
@@ -0,0 +1,1125 @@
+
+
+
+ In the previous section, we learned of all the events dispatched throughout the process of verifying and running a student's solution to an exercise. In this this section we will learn how these
+ events can be used to build a
+ Listener Check
+ .
+
+
+ What is a Listener Check?
+
+
+ We learned about
+ Simple Checks
+ in
+ Exercise Checks
+ , they are simple pieces of code which can run before or after verifying a student's solution to an exercise.
+ Listener Checks
+ allow us to hook in to the verifying and running process with more granular precision.
+ Listener Checks
+ can run pieces of code at any point where an event is dispatched. Check the
+ Events
+ page for a list of available events which your
+ Listener Check
+ can listen to.
+
+
+
+ Listener Checks are one of the most complex components of the workshop application, so in order to demonstrate their use-case, we will build a
+ Listener Check
+ which allows us to interact with
+ Couch DB
+ . We will then build an exercise in our tutorial application which utilises this check.
+
Before we build anything we should design our check. What should it do?
+
+
Couch DB is a NoSQL database, which stores data as JSON documents and it's API is provided via regular HTTP.
+
+
So, we want to introduce the features of Couch DB via this Listener Check. What should it do?
+
+
+
+ Be applicable to only
+ CLI
+ type exercises.
+
+
Create 2 databases, one for the student solution and one for the reference solution.
+
Pass the databases names to the programs.
+
Remove the databases at the end of the verify/run process and in case of any failures.
+
Allow for exercises to seed the two databases with data.
+
Allow for exercises to verify the data in the database after the solutions have executed.
+
+
+ What events to use?
+
+
Reading this specification we can see that we will need to hook in to various events to provide this functionality, we will now break down each point and decide what events to listen to.
+
+ Creating the databases
+
+ We will need to create databases in both
+ verify
+ &
+ run
+ mode, we can do this immediately in our
+ attach
+ method, which is automatically called when we register our check within an exercise.
+
+
+ Seed the database
+
+ We will need to allow the exercise to seed the database, we should do this early on
+ verify.start
+ &
+ run.start
+ are the earliest events dispatched. These sound like good candidates to perform this task. We will pass a client object to the exercise
+ seed
+ method so they can create documents.
+
+
+ Pass database name to the programs
+
+ We will need to pass the database names to the programs (student's solution & the reference solution) so the programs can access it via the
+ $argv
+ array. We can do this with any events which trigger with an instance of
+ CliExecuteEvent
+ . We can use
+ cli.verify.reference-execute.pre
+ ,
+ cli.verify.student-execute.pre
+ &
+ cli.run.student-execute.pre
+ .
+
+
+ Verify the database
+
+
+ We will need to allow the exercise to verify the database, we should do this after output verification has finished. We can pick one of the last events triggered,
+ verify.finish
+ will do! We will pass the database client object again to the exercise
+ verify
+ method so they can verify the state of the database.
+
+
+ Cleanup the database
+
+ We will need to remove the databases we created at the end of the process. We can use
+ verify.finish
+ &
+ run.finish
+ to do this. We will also listen to
+ cli.verify.reference-execute.fail
+ so in case something goes wrong, we still cleanup.
+
+
+ Now let's build the check!
+
+
+ The finished
+ Couch DB check
+ is available as a separate Composer package for you to use in your workshops right away, but, for the sake of this tutorial we will build it using the
+ tutorial application
+ as a base so we do not have to setup a new project with composer files, register it with
+ Packagist
+ and so on.
+
+
+
+ We will start fresh from the
+ master
+ branch for this tutorial, so if you haven't already got it, git clone it and install the dependencies:
+
+
+
+
+ 1. Require doctrine/couchdb as a dependency
+
We will use this library to interact with Couch DB.
+
+
+ 2. Create the folders and classes
+
+
+ 3. Define our interface
+
+ We mentioned before that we needed a way for the exercise to seed and verify the database, so we will define an interface which describes these methods which the exercise must implement for the
+ Couch DB check. These methods will automatically be invoked by the check. Open up
+ src/ExerciseCheck/CouchDbExerciseCheck.php
+ and add the following code to it:
+
+ We define, two methods
+ seed()
+ &
+ verify()
+ , both receive an instance of
+ CouchDBClient
+ which will be connected to the database created for the student,
+ seed()
+ should be called before the student's solution is run and
+ verify()
+ should be called after the student's solution is run.
+
+
+ 4. Write the check
+
+
+ For this check, we assume that Couch DB is always running at
+ http://localhost:5984/
+ as is default when Couch DB is installed.
+
+
+
+ Now we write the check - there is quite a lot of code here so we will do it in steps, open up
+ src/Check/CouchDbCheck.php
+ and start with the following:
+
+
+
+
+<?php
+
+namespace PhpSchool\SimpleMath;
+
+use Doctrine\CouchDB\CouchDBClient;
+use Doctrine\CouchDB\HTTP\HTTPException;
+use PhpSchool\PhpWorkshop\Check\ListenableCheckInterface;
+use PhpSchool\PhpWorkshop\Event\EventDispatcher;
+use PhpSchool\SimpleMath\ExerciseCheck\CouchDbExerciseCheck;
+
+class CouchDbCheck implements ListenableCheckInterface
+{
+ /**
+ * @var string
+ */
+ private static $studentDb = 'phpschool-student';
+
+ /**
+ * @var string
+ */
+ private static $solutionDb = 'phpschool';
+
+ /**
+ * Return the check's name
+ *
+ * @return string
+ */
+ public function getName()
+ {
+ return 'Couch DB Verification Check';
+ }
+
+ /**
+ * This returns the interface the exercise should implement
+ * when requiring this check
+ *
+ * @return string
+ */
+ public function getExerciseInterface()
+ {
+ return CouchDbExerciseCheck::class;
+ }
+
+ /**
+ * @param EventDispatcher $eventDispatcher
+ */
+ public function attach(EventDispatcher $eventDispatcher)
+ {
+
+ }
+}
+
+
+
+
+ There is not much going on here - we define
+ getName()
+ which is the name of our check, and
+ getExerciseInterface()
+ which should return the FQCN (Fully Qualified Class Name) of the interface we just defined earlier. This is so the workshop framework can check the exercise implements it. We also define some
+ properties which describe the names of the Couch DB databases we will setup: one for the student and one for the reference solution.
+
+
+
+ The most important thing to note in this check is that we implement
+ PhpSchool\PhpWorkshop\Check\ListenableCheckInterface
+ instead of
+ PhpSchool\PhpWorkshop\Check\SimpleCheckInterface
+ . They both inherit from
+ PhpSchool\PhpWorkshop\Check\CheckInterface
+ which introduces
+ getName()
+ &
+ getExerciseInterface()
+ .
+ ListenableCheckInterface
+ brings in one other additional method:
+ attach()
+ . This method is called immediately when an exercise requires any
+ Listener Check
+ and is passed an instance of
+ PhpSchool\PhpWorkshop\Event\EventDispatcher
+ allowing the check to listen to any events which might be dispatched throughout the verifying/running process.
+
+
+
Our check will listen to a number of those events so we will build this method up step by step.
+
+ Create the databases
+
+ The first thing we need to do is create the two databases, so we create two Couch DB clients and issue the
+ createDatabase
+ method:
+
+ We need to allow the exercise to seed the database to create documents, for example. The database for the student and the reference solution should contain the same data, but they must be
+ different databases.
+
+
+
+ The reason why both programs need their own database is fairly simple. Say the exercise's lesson was to teach how to remove a document in the database. It would first need to create a document in
+ the database using the
+ seed
+ method. The student's solution should remove that document. If the student's solution and the reference solution shared one database, then the reference solution would run first and remove the
+ row. Then the student's solution would run...it can't remove the document because it's not there anymore!
+
+
+
+ We can't just call
+ seed()
+ again because
+ seed()
+ can return dynamic data and then the student's solution and the reference solution would run with different data sets; which makes it impossible to compare their output.
+
+
+
+
+$eventDispatcher->listen('verify.start', function (Event $e) use ($studentClient, $solutionClient) {
+ $e->getParameter('exercise')->seed($studentClient);
+ $this->replicateDbFromStudentToSolution($studentClient, $solutionClient);
+});
+
+
+
+
+ We listen to the
+ verify.start
+ event which (as you can probably infer) triggers right at the start of the verify process. The listener is an anonymous function that grabs the exercise instance from the event and calls the
+ seed()
+ method passing in the
+ CouchDBClient
+ which references the database created for the student. We also need to seed the database for reference solution, we need it to be exactly the same as the student's so we basically select all
+ documents from the student database and insert them in to the reference solution database. We do this in the method
+ replicateDbFromStudentToSolution
+ . This method looks like the following:
+
+ When in run mode, no output is compared - we merely run the student's solution - so we only need to seed the student's database. There is a similar event to
+ verify.start
+ when in run mode, aptly named
+ run.start
+ , let's use that:
+
+
+
+
+$eventDispatcher->listen('run.start', function (Event $e) use ($studentClient) {
+ $e->getParameter('exercise')->seed($studentClient);
+});
+
+
+
+ Adding the database name to the programs' arguments
+
+ We need the programs (student solution & the reference solution) to have access to their respective database names, the best way to do this is via command line arguments - we can add arguments to
+ the list of arguments to be sent to the programs with any event which triggers with an instance of
+ CliExecuteEvent
+ . It exposes the
+ prependArg()
+ &
+ appendArg()
+ methods.
+
+
+
+ We use
+ cli.verify.reference-execute.pre
+ to prepend the reference database name to the reference solution program when in
+ verify
+ mode and we use
+ cli.verify.student-execute.pre
+ &
+ cli.run.student-execute.pre
+ to prepend the student database name to the student solution in
+ verify
+ &
+ run
+ mode, respectively.
+
+ After the programs have been executed, we need a way to let the exercise verify the contents of the database. We hook on to an event during the
+ verify
+ process named
+ verify.finish
+ (this is the last event in the verify process) and insert a verifier function. We don't need to verify the database in
+ run
+ mode because all we do in run mode is
+ run
+ the students submission in the correct environment (with args and database).
+
+ Verify functions are used to inject results into the result set, which is then reported to the student. So you can see that if the
+ verify
+ method returns
+ true
+ we return a
+ Success
+ to the result set but if it returns false we return a
+ Failure
+ result, with a message, so the student knows what went wrong.
+
+
+ The Event Dispatcher takes care of running the verifier function at the correct event and injects the returned result in to the result set.
+
+ Cleanup the databases
+
+ The final stage is to remove the databases, we listen to
+ verify.post.execute
+ for the verify process &
+ run.finish
+ for the run process:
+
+
+
+ Build an exercise using the Couch DB check
+
+
+ So then, this Couch DB check is not much use if we don't utilise it! let's build an exercise which retrieves a document from a database, sums a bunch of numbers and adds the total to the document,
+ finally we should output the total. The document with the numbers in it will be automatically created by our exercise in the
+ seed()
+ method and will be random.
+
We will use the check that is available in the already built Composer package, so, pull it in to your project:
+
+
+
+
+ We have to manually require
+ doctrine/couchdb
+ even though it is a dependency of
+ php-school/couch-db-check
+ because there is no stable release available. Indirect dependencies cannot install non-stable versions.
+
+
+ Problem file
+
+
+ Create a problem file in
+ exercises/couch-db-exercise/problem/problem.md
+ . Here we describe the problem we mentioned earlier when we decided what we wanted our exercise to do:
+
+
+
+
+Write a program that accepts the name of database and a Couch DB document ID. You should load this document using the
+provided ID from the provided database. In the document will be a key named `numbers`. You should add them all up
+and add the total to the document under the key `total`. You should save the document and finally output the total to
+the console.
+
+You must have Couch DB installed before you run this exercise, you can get it here:
+ [http://couchdb.apache.org/#download]()
+
+----------------------------------------------------------------------
+## HINTS
+
+You could use a third party library to communicate with the Couch DB instance, see this doctrine library:
+ [https://github.com/doctrine/couchdb-client]()
+
+Or you could interact with it using a HTTP client such as Guzzle:
+ [https://github.com/guzzle/guzzle]()
+
+Or you could simply use `curl`.
+
+Check out how to interact with Couch DB documents here:
+ [http://docs.couchdb.org/en/1.6.1/intro/api.html#documents]()
+
+You will need to do this via PHP.
+
+You specifically need the `GET` and `PUT` methods, or if you are using a library abstraction, you will need to
+`find` and `update` the document.
+
+
+You can use the doctrine library like so:
+
+```php
+<?php
+require_once __DIR__ . '/vendor/autoload.php';
+
+use Doctrine\CouchDB\CouchDBClient;
+$client = CouchDBClient::create(['dbname' => $dbName]);
+
+//get doc
+$doc = $client->findDocument($docId);
+
+//update doc
+$client->putDocument($updatedDoc, $docId, $docRevision);
+```
+
+`{appname}` will be supplying arguments to your program when you run `{appname} verify program.php` so you don't need to supply them yourself. To test your program without verifying it, you can invoke it with `{appname} run program.php`. When you use `run`, you are invoking the test environment that `{appname}` sets up for each exercise.
+
+----------------------------------------------------------------------
+
+
+
+
We note that the student must have Couch DB installed, we give a few links, an example of how to use the Doctrine Couch DB client and we describe the actual task.
+
+ Write the exercise
+
+
+ Create the exercise in
+ src/Exercise/CouchDbExercise.php
+ :
+
+ So - in
+ seed
+ we create a random number of random numbers and insert a document containing these numbers under a key named
+ numbers
+ . We store the total (for verification purposes) and also the document ID (this is auto generated by Couch DB) so we can pass it to the solutions as an argument.
+
+
+
+ In the
+ verify
+ method, we try load the document with the stored ID, check for the presence of the
+ total
+ property and check that it is equal to the stored total we set during
+ seed
+ .
+
+
+
+ In
+ configure()
+ we require our Couch DB check and in
+ getType()
+ we inform the the workshop framework that this is a CLI type exercise.
+
+
+
+ In
+ getArgs()
+ we return the Document ID we set during
+ seed
+ .
+
+
+ Because
+ seed
+ is invoked from an event which is dispatched before
+ getArgs
+ , we can rely on anything set there.
+
+
+
+ The students solution would therefore be invoked like:
+ php my-solution.php phpschool-student 18
+ . The argument
+ phpschool-student
+ being the database name created for the student by the check (remember the check prepends this argument to the argument list) and 18 being the ID of the document we created!
+
+
+ Write the reference solution
+
+
+ Our reference solution will also use the Doctrine Couch DB library - let's go ahead and create the solution in
+ exercises/couch-db-exercise/solution
+ . We will need three files
+ composer.json
+ ,
+ composer.lock
+ and
+ solution.php:
+
+
+
+ composer.lock
+
+ composer.lock
+ is auto generated by Composer, by running
+ composer install
+ in
+ exercises/couch-db-exercise/solution
+
+
+ Wire it all together
+
+
+ Now we have to add the factories for our check and exercise and register it with the application, add the following to
+ app/config.php
+ and don't forget to import the necessary classes.
+
+ Finally we need to tell the application about our new check and exercise in
+ app/bootstrap.php
+ . After the application object is created you just call
+ addCheck
+ &
+ addExercise
+ with the name of check class and exercise class respectively. Your final
+ app/bootstrap.php
+ file should look something like:
+
+
+
+
+<?php
+
+ini_set('display_errors', 1);
+date_default_timezone_set('Europe/London');
+switch (true) {
+ case (file_exists(__DIR__ . '/../vendor/autoload.php')):
+ // Installed standalone
+ require __DIR__ . '/../vendor/autoload.php';
+ break;
+ case (file_exists(__DIR__ . '/../../../autoload.php')):
+ // Installed as a Composer dependency
+ require __DIR__ . '/../../../autoload.php';
+ break;
+ case (file_exists('vendor/autoload.php')):
+ // As a Composer dependency, relative to CWD
+ require 'vendor/autoload.php';
+ break;
+ default:
+ throw new RuntimeException('Unable to locate Composer autoloader; please run "composer install".');
+}
+
+use PhpSchool\CouchDb\CouchDbCheck;
+use PhpSchool\PhpWorkshop\Application;
+use PhpSchool\SimpleMath\Exercise\CouchDbExercise;
+use PhpSchool\SimpleMath\Exercise\Mean;
+
+$app = new Application('Simple Math', __DIR__ . '/config.php');
+
+$app->addExercise(Mean::class);
+$app->addExercise(CouchDbExercise::class);
+$app->addCheck(CouchDbCheck::class);
+
+$art = <<<ART
+ ∞ ÷ ∑ ×
+
+ PHP SCHOOL
+SIMPLE MATH
+ART;
+
+$app->setLogo($art);
+$app->setFgColour('red');
+$app->setBgColour('black');
+
+return $app;
+
+
+
+ Our exercise is complete - let's try it out!
+
+ Try it out!
+
+
+ Make sure you have Couch DB installed, run the workshop and select the
+ Couch DB Exercise
+ exercise.
+
+
+
+ Try verifying with the solution below which incorrectly sets the total to
+ 30
+ , hopefully you will see a failure.
+
+ There are various events triggered throughout the verifying and running of exercises. These events can be used by
+ Listener Checks
+ to hook in to the process at various stages. This article details the events and the arguments available.
+
+
+
+ Each event implements
+ PhpSchool\PhpWorkshop\Event\EventInterface
+ where you can grab the parameters like
+ $event->getParameter('myParam');
+ some events may have convenience methods for accessing certain parameters, please refer to the particular event class for more info.
+
+
+
There are 4 routes through the application, and the lists of events below each represent a timeline of one of those routes.
+
+
CLI Verify
+
+ This is the route taken when using the
+ verify
+ command on a
+ CLI
+ type exercise.
+
+
CLI Run
+
+ This is the route taken when using the
+ run
+ command on a
+ CLI
+ type exercise.
+
+
CGI Verify
+
+ This is the route taken when using the
+ verify
+ command on a
+ CGI
+ type exercise.
+
+
CGI Run
+
+ This is the route taken when using the
+ run
+ command on a
+ CGI
+ type exercise.
+
+
+ Listening to Events
+
+
Events can be listened to by attaching to the event dispatcher with any valid PHP callable:
+
+
+
+<?php
+
+$eventDispatcher = $container->get(PhpSchool\PhpWorkshop\Event\EventDispatcher:class);
+$eventDispatcher->listen('verify.start', function (Event $event) {
+ //do something
+});
+
+// you can also listen to multiple events in one call
+
+$eventDispatcher->listen(['verify.start', 'run.start'], function (Event $event) {
+ //do something
+});
+
+
+
+
+ With the event dispatcher you can even do more interesting things, such as, at any event, you can insert a verifier (any valid PHP callable) - it will be passed the event, the same as a normal
+ listener, but it must return an implementation of
+ PhpSchool\PhpWorkshop\Result\ResultInterface
+ . This will be evaluated and injected in to the results for reporting on the CLI.
+ PhpSchool\PhpWorkshop\Result\SuccessInterface
+ instances will be treated as successes and
+ PhpSchool\PhpWorkshop\Result\FailureInterface
+ instances will be treated as failures. So you can actually fail a verification attempt via an event.
+
+
+
+ Learn more about results
+ here
+ .
+
+
+
+ This is useful for
+ Listener Checks
+ , for example, towards the end of the verifying process, you may want to verify that some data was inserted to a database. If it was not you will return a failure, which will be displayed on the
+ CLI and will cause the verification attempt to fail.
+
+
+
How to insert verifiers:
+
+
+
+<?php
+
+$eventDispatcher = $container->get(PhpSchool\PhpWorkshop\Event\EventDispatcher:class);
+$eventDispatcher->insertVerifier('verify.finish', function (Event $event) {
+ if (!$this->checkDb()) {
+ return Failure::fromNameAndReason('DB Check', 'DB Verification failed!');
+ }
+ return new Success('DB Check');
+});
+
+
+
+ Events
+
+
+
+
+
+
+
+
+
+
+
+
+ This event is triggered before the arguments to a command are resolved. Resolving arguments checks that all required arguments have been passed to the command.
+
+
+
+ This event is triggered just before a command is executed.
+
+
+
+ This event is triggered right at the start of the exercise dispatcher verification process.
+
+
+
+
+ This event is triggered after the
+ before
+ checks have successfully finished running, and before the exercise is passed to the specific exercise runner.
+
+
+
+
+ This event is triggered right at the start of the CLI runner verification process.
+
+
+
+
+ This event is triggered just before the reference solution is executed.
+
+
+
+
+ This event is triggered while the reference solution is being executed. Here you can actually interact with the program, for example if it kicked of a TCP server.
+
+
+
+
+ This event is only triggered if the reference solution failed to execute correctly, that is, it returned a non-zero exit code.
+
+
+
+
+ This event is triggered just before the student's solution is executed.
+
+
+
+
+ This event is triggered while the student's solution is being executed. Here you can actually interact with the program, for example if it kicked of a TCP server.
+
+
+
+
+ This event is only triggered if the student's solution failed to execute correctly, that is, it returned a non-zero exit code.
+
+
+
+
+ This event is triggered right at the end of the CLI runner verification process.
+
+
+
+
+ This event is triggered after the exercise runner has finished and right before the after checks are run.
+
+
+
+
+ This event is triggered after the
+ after
+ checks have finished running.
+
+
+
+
+ This event is triggered right at the end of the exercise dispatcher verification process.
+
+
+
+
+
+
+
+
+ This event is triggered before the arguments to a command are resolved. Resolving arguments checks that all required arguments have been passed to the command.
+
+
+
+ This event is triggered just before a command is executed.
+
+
+
+ This event is triggered right at the start of the exercise dispatcher run process.
+
+
+
+
+ This event is triggered right at the start of the CLI runner run process.
+
+
+
+
+ This event is triggered just before the student's solution is executed.
+
+
+
+
+ This event is triggered while the student's solution is being executed. Here you can actually interact with the program, for example if it kicked of a TCP server.
+
+
+
+
+ This event is triggered right at the end of the CLI runner run process.
+
+
+
+
+ This event is triggered right at the end of the exercise dispatcher run process.
+
+
+
+
+
+
+
+
+ This event is triggered before the arguments to a command are resolved. Resolving arguments checks that all required arguments have been passed to the command.
+
+
+
+ This event is triggered just before a command is executed.
+
+
+
+ This event is triggered right at the start of the exercise dispatcher verification process.
+
+
+
+
+ This event is triggered after the
+ before
+ checks have successfully finished running, and before the exercise is passed to the specific exercise runner.
+
+
+
+
+ This event is triggered right at the start of the CGI runner verification process.
+
+
+
+
+ This event is triggered just before the reference solution is executed.
+
+
+
+
+ This event is triggered while the reference solution is being executed. Here you can actually interact with the program, for example if it kicked of a TCP server.
+
+
+
+
+ This event is only triggered if the reference solution failed to execute correctly, that is, it returned a non-zero exit code.
+
+
+
+
+ This event is triggered just before the student's solution is executed.
+
+
+
+
+ This event is triggered while the student's solution is being executed. Here you can actually interact with the program, for example if it kicked of a TCP server.
+
+
+
+
+ This event is only triggered if the student's solution failed to execute correctly, that is, it returned a non-zero exit code.
+
+
+
+
+ This event is triggered right at the end of the CGI runner verification process.
+
+
+
+
+ This event is triggered after the exercise runner has finished and right before the after checks are run.
+
+
+
+
+ This event is triggered after the
+ after
+ checks have finished running.
+
+
+
+
+ This event is triggered right at the end of the exercise dispatcher verification process.
+
+
+
+
+
+
+
+
+ This event is triggered before the arguments to a command are resolved. Resolving arguments checks that all required arguments have been passed to the command.
+
+
+
+ This event is triggered just before a command is executed.
+
+
+
+ This event is triggered right at the start of the exercise dispatcher run process.
+
+
+
+
+ This event is triggered right at the start of the CGI runner run process.
+
+
+
+
+ This event is triggered just before the student's solution is executed.
+
+
+
+
+ This event is triggered while the student's solution is being executed. Here you can actually interact with the program, for example if it kicked of a TCP server.
+
+
+
+
+ This event is triggered right at the end of the CGI runner run process.
+
+
+
+
+ This event is triggered right at the end of the exercise dispatcher run process.
+
+
+
+
+
+
+
diff --git a/assets/components/Website/Docs/Sections/Reference/ExerciseChecks.vue b/assets/components/Website/Docs/Sections/Reference/ExerciseChecks.vue
new file mode 100644
index 00000000..caed1cb4
--- /dev/null
+++ b/assets/components/Website/Docs/Sections/Reference/ExerciseChecks.vue
@@ -0,0 +1,143 @@
+
+
+
+ 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?
+
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
+
+ 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?
+
+ 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.
+
+ 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:
+
As we learned in the previous article, we can implement simple checking directly in our exercise if we don't want to build a check.
+
+
However, Self Checking is rather un-flexible in that you can only hook in to the verify/run process at one particular point, immediately after all other checks have run.
+
+
+ We also described the events features in previous chapters
+ Events
+ &
+ Creating Listener Checks
+ . Well, as it goes, any events you can listen to in
+ Listener Checks
+ , you can listen to directly in your exercises!
+
+ You can grab the
+ EventDispatcher
+ from
+ ExerciseDispatcher
+ and listen to any events and insert verifiers just like we did in
+ Creating Listener Checks
+ when we inserted a verifier function which verifies the state of a Couch DB database.
+
+
+
+ You can listen to any of the events listed on
+ Events
+ .
+
+
diff --git a/assets/components/Website/Docs/Sections/Reference/ExerciseSolutions.vue b/assets/components/Website/Docs/Sections/Reference/ExerciseSolutions.vue
new file mode 100644
index 00000000..10715367
--- /dev/null
+++ b/assets/components/Website/Docs/Sections/Reference/ExerciseSolutions.vue
@@ -0,0 +1,389 @@
+
+
+
Every CGI & CLI type exercise must have a reference solution. The solution represents a complete working example of how to solve the exercise's problem.
+
+
The solution is used for a few things in the workshop:
+
+
When verifying a student's solution to an exercise, the reference solution is invoked and the output of the two are compared.
+
To display to the student as the proposed solution after they have completed the exercise. This is useful if they solved the problem in a less optimal albeit working way.
+
+
+
+ A solution is represented by an implementation of
+ PhpSchool\PhpWorkshop\Solution\SolutionInterface
+ .
+
+
+ The workshop framework ships with two implementations of
+ PhpSchool\PhpWorkshop\Solution\SolutionInterface
+ to cover most scenarios:
+
+
+
+
+ PhpSchool\PhpWorkshop\Solution\SingleFileSolution
+ - When your reference solution is just one file. For example
+ solution.php
+
+
+ PhpSchool\PhpWorkshop\Solution\DirectorySolution
+ - When your reference solution comprises of multiple files.
+
+
+
+ SingleFileSolution
+
+ This is the default used by
+ PhpSchool\PhpWorkshop\Exercise\AbstractExercise
+ . So if you don't override the
+ getSolution()
+ method, the solution will be a single file named
+ solution.php
+ contained in the directory
+ exercises/exercise-name/solution
+ .
+
+
+
This would look like the following if you were to manually construct it:
+ It is possible that your solution contains more than one PHP file. Maybe you have some classes separated into different files, maybe you also pull in some dependencies via Composer. In either
+ case, you should use
+ PhpSchool\PhpWorkshop\Solution\DirectorySolution
+ .
+
+
+
+ Usage is simple, just pass it the directory and an (optional) entry point. You can also provide an optional list of files to exclude, more on that later. The entry point defaults to
+ solution.php
+ . The following is a depiction of a directory structure and the code to encompass the solution:
+
+ To return a directory solution when using the
+ PhpSchool\PhpWorkshop\Exercise\AbstractExercise
+ as a base for your exercise you can override the
+ getSolution
+ method with the following:
+
+
+
+<?php
+
+public function getSolution()
+{
+ return DirectorySolution::fromDirectory('/path/to/workshop/exercises/exercise-name');
+}
+
+
+
+ This would load any files in the directory given and treat
+ solution.php
+ as the entry point. Constructed manually this might look like:
+
+ If your solution looked like the below where your entry point is named
+ index.php
+ , you can provide the optional third parameter to the static constructor:
+ fromDirectory
+ . It must be the relative path of the file from the solution base directory.
+
+
+
+
+ The convention is for the entry point file to be named
+ solution.php
+ to keep things simple.
+
+
+ DirectorySolution
+ will throw an instance of
+ InvalidArgumentException
+ if the entry point does not exist in the directory given.
+
+
+ Excluding files from the solution directory
+
+ The method
+ getFiles
+ is used to find all the files in an solution. One use case is to display the contents of the files to the student when they have finished an exercise. This way they can compare Notes. Sometimes
+ you may want some files to be excluded from this. Perhaps you don't want the
+ composer.lock
+ file to be printed to the terminal as this can be quite long. To exclude some files from the solution, simply provide an array of excludes, relative to the base directory:
+
+ It is not actually necessary to exclude
+ composer.lock
+ or
+ vendor
+ as these are automatically appended to the list of excludes when using the static constructor
+ fromDirectory
+ .
+
+
+ Overriding the default excluded files
+
+ The following files are excluded by default when using the static constructor
+ fromDirectory
+ :
+
+
+
composer.lock
+
vendor
+
+
+
+ If for some reason you do not want to ignore, say
+ composer.lock
+ but still
+ vendor
+ you can use the
+ __construct
+ method which does not have any default values:
+
+
+
+
+ The argument order for
+ __construct
+ and
+ fromDirectory
+ are slightly different.
+ __construct
+ is: $directory, $entryPoint, $excludes.
+ fromDirectory
+ is: $directory, $excludes, $entryPoint.
+
+
+ Using Composer Libraries in your solution
+
+ If you use a library via Composer then you should include the
+ composer.json
+ and
+ composer.lock
+ file in the solution base directory.
+ DirectorySolution
+ will detect the Composer files automatically. If there are Composer files available, the workshop will run a
+ composer install
+ in the solution base directory before invoking the solution.
+
+
+ This means that you don't need to commit the vendor directory for each reference solution.
+
+ Creating your own Exercise Solution Type
+
+
+ If the
+ SingleFileSolution
+ or
+ DirectorySolution
+ implementations do not cover your needs, you can create your own by implementing the following interface:
+
+
+
+interface SolutionInterface
+{
+ /**
+ * @return string
+ */
+ public function getEntryPoint();
+
+ /**
+ * @return SolutionFile[]
+ */
+ public function getFiles();
+
+ /**
+ * @return string
+ */
+ public function getBaseDirectory();
+
+ /**
+ * @return bool
+ */
+ public function hasComposerFile();
+}
+
+
+ getEntryPoint()
+
This method should return the name of the file which should be the entry point to your solution, in absolute form.
+
+ getFiles()
+
+ This method should return an array of files. Each file should be represented by an instance of
+ PhpSchool\PhpWorkshop\Solution\SolutionFile
+ .
+
+
+ getBaseDirectory()
+
This should return the absolute path to the directory of the solution.
+
+ hasComposerFile()
+
+ This should return a boolean value depending on whether the solution has a
+ composer.lock
+ file present. If it does, before invoking the solution,
+ composer install
+ will be executed in the solution base directory. This saves you having to bundle the vendor directory in your workshop.
+
+ The exercise type indicated how the exercise should be verified, each exercise must have a type. There are three types of exercise types as of writing
+ CLI
+ ,
+ CGI
+ &
+ CUSTOM
+ . In this section we will detail what the verification process for each exercise type is.
+
+
+
When selecting your exercise type you must return the valid type and implement the respective interface.
+
+ CLI
+
+
+ You choose the CLI type if you want the user to interact with the
+ $argv
+ and
+ $argc
+ super globals.
+
+
+
+
+ Implementing getArgs
+
+ getArgs
+ should return an array of string arrays. These are the arguments to be passed to the PHP CLI executable. The number of arguments which can be returned is not limited. All arguments should be
+ strings. If multiple sets of arguments are specified then the program will be executed each time with those arguments.
+
+ You choose the CGI type if you want the user to interact with the
+ $_GET
+ ,
+ $_POST
+ ,
+ $_SERVER
+ , etc super globals.
+
+
This exercise type allows to simulate a real HTTP request to a PHP script.
+
+
+
+ Implementing getRequests
+
+
+ getRequests
+ should return an array of PSR-7 Requests. The number of requests is not limited. Check
+ here
+ for more information about PSR-7. The method is currently type hinted to return an array of the
+ Psr\Http\Message\RequestInterface
+ interface. You will need to use a library which implements the PSR-7 standard. Currently
+ zendframework/zend-diactoros
+ is shipped with
+ php-school/php-workshop
+ so you can just use that, or feel free to pull in a different implementation.
+
+ We use the
+ php-cgi
+ binary to setup the PHP environment. The
+ php-cgi
+ binary uses environment variables and standard input to configure itself, we export these variables based on the information you provide in
+ getRequests
+ .
+
+
+
+
+
+ You can return multiple request from
+ getRequests
+ .
+
+
Each request can have a different method.
+
Each request can have any amount of headers as you need.
+
+
+
+ CUSTOM
+
+
+ You choose the CUSTOM type if you want the user to perform some arbitrary task that does not involve writing PHP code. For example the exercise could be to ask the user to download and install a
+ program and then we could check that it is running.
+
+
This exercise type allows to simulate a real HTTP request to a PHP script.
+
+
+
+ Implementing verify
+
+ This is where you perform your verification. The method needs to return an instance of
+ PhpSchool\PhpWorkshop\Result\ResultInterface
+ . Depending on whether you want a success or failure to be recorded it will be an instance of
+ PhpSchool\PhpWorkshop\Result\SuccessInterface
+ or
+ PhpSchool\PhpWorkshop\Result\FailureInterface
+ . Learn about results
+ here
+ .
+
+
+
+
+<?php
+
+namespace PhpSchool\MyWorkshop\Exercise;
+
+use PhpSchool\PhpWorkshop\Exercise\AbstractExercise;
+use PhpSchool\PhpWorkshop\Exercise\CustomVerifyingExercise;
+use PhpSchool\PhpWorkshop\Exercise\ExerciseInterface;
+use PhpSchool\PhpWorkshop\Exercise\ExerciseType;
+use PhpSchool\PhpWorkshop\Result\Success;
+use PhpSchool\PhpWorkshop\Result\Failure;
+
+class MyExercise extends AbstractExercise implements ExerciseInterface, CustomVerifyingExercise
+{
+ ...snip
+
+ /**
+ * @return ResultInterface
+ */
+ public function verify()
+ {
+ if (//program is running) {
+ return new Success('My Program Check');
+ }
+ return new Failure('My Program Check', 'Program is running!');
+ }
+
+ /**
+ * @return ExerciseType
+ */
+ public function getType()
+ {
+ return ExerciseType::CGI();
+ }
+}
+
+
+
When a student runs the verify command your verify method will be invoked and the results will be displayed to the student!
+ This is the fun bit! - In this article we will show how we can modify the student's solution, injecting, modifying and wrapping code. Before we get down to it, a little background to explain why
+ we built this feature.
+
+
+
Why?
+
+ We wanted a way to make sure that
+ display_errors
+ and
+ error_reporting
+ were always configured correctly, we also thought that we might want to wrap solutions in
+ try/catch
+ blocks so we could give more structured feedback to the student. We figured, in order to do this in a robust manner, we would have to patch the student's solution on the fly and revert the changes
+ after the framework has verified/run the solution.
+
+
+
+ We decided this feature may be useful for workshop developers, we thought there may be possibilities where you want to concentrate on a verify specific problem like "Here is a variable - transform
+ it to this", well with this feature, you could inject that variable at the start of the script so it is already available to the student!
+
+
+
How?
+
There are two type of modifications you can do to a solution:
+
+
Insertion (Insert code at the beginning or end of a solution)
+
Transformer (Use a callable to modify an AST representation of the solution)
+
+
+
+ In order to inform the workshop framework that an exercise would like to patch a solution it must implement
+ PhpSchool\PhpWorkshop\Exercise\SubmissionPatchable
+ and return an instance of
+ PhpSchool\PhpWorkshop\Patch
+ .
+
+
+
+ The
+ Patch
+ object is where you specify your
+ Insertions
+ &
+ Transformers
+ . The API looks like this:
+
+
+
+
+ The
+ Patch
+ class is immutable so you will need to assign the result of any calls to
+ with*
+ methods.
+
+
+ Insertions
+
Insertions allow to insert a block of code at either the beginning or end of the student's solution. The API is very simple:
+
+
+
+<?php
+
+use PhpSchool\PhpWorkshop\CodeInsertion;
+
+$before = new CodeInsertion(CodeInsertion::TYPE_BEFORE, 'echo "Before";');
+$after = new CodeInsertion(CodeInsertion::TYPE_AFTER, 'echo "After";');
+
+
+
+ Transformers
+
+ Transformers allow to modify the whole solution via an AST. A transformer is any valid PHP
+ callable
+ that returns an
+ array
+ of
+ PhpParser\Node
+ objects. The callable will be passed an
+ array
+ of
+ PhpParser\Node
+ objects which represent the parsed student's solution.
+
+
+
+ Lets see how you can build a transformer that wraps the solution in a
+ try/catch
+ block that then outputs the exception message.
+
+ Note that the AST modification is fairly complicated, the feature is provided by the
+ nikic/php-parser
+ library and you should refer to that project for documentation on the AST.
+
+
+ Wiring it together
+
+ Let's write a patch that will wrap the solution in a
+ try/catch
+ block, add
+ echo 'Start';
+ at the beginning and add
+ echo 'Finish';
+ at the end:
+
+<?php
+
+echo "Hello World"
+throw new InvalidArgumentException('What is this magic?');
+
+
+
+
Then the code that is actually invoked by the workshop framework would be the following:
+
+
+
+<?php
+
+echo 'Start';
+try {
+ echo "Hello World"
+ throw new InvalidArgumentException('What is this magic?');
+} catch (Exception $e) {
+ echo $e->getMessage();
+}
+echo 'Finish';
+
+
+
+ The students solution will be reverted to the original form at the end of the verifying/running process so the student will never see the code in their solution file.
+
diff --git a/assets/components/Website/Docs/Sections/Reference/ReferenceHome.vue b/assets/components/Website/Docs/Sections/Reference/ReferenceHome.vue
new file mode 100644
index 00000000..d7f15888
--- /dev/null
+++ b/assets/components/Website/Docs/Sections/Reference/ReferenceHome.vue
@@ -0,0 +1,98 @@
+
+
+
In this section you will learn about the internals of the workshop application which will enable you to build robust and advanced workshops.
+
You can use this section as a useful reference to refer back to during the development of your workshop.
+
+ For a walk through approach detailing the initial setup of a workshop and the development of your first exercise, check out the
+ Workshop Tutorial
+ .
+
+
+ Sections
+
+
+ The Container
+
+
The workshop utilises a container to build and publish services. Learn how to register new services and replace existing ones.
+
+
+ Available Services
+
+
Learn about the services exposed by the container, many of them utilities you can use in your exercises, checks and other services.
+
+
+ Exercise Types
+
+
+ Exercises can be of either
+ CLI
+ or
+ CGI
+ type. Learn about the differences here and which one is right for your exercise.
+
+
+
+ Exercise Solutions
+
+
Exercise solutions can consist of one or many files, which could consist of an entire application. They can also contain Composer dependencies in order to model real-world scenarios.
+
+
+ Results & Renderers
+
+
Learn about Results and Result Renderers.
+
+
+ Exercise Checks
+
+
Learn what Exercise Checks are and how to use them in your exercise.
+
+
+ Bundled Checks
+
+
Learn about the available Exercise Checks in the workshop framework and how to use them.
+
+
+ Creating Simple Checks
+
+
Learn how to create your own Simple Check.
+
+
+ Creating Custom Results
+
+
Create a custom result to use in your check.
+
+
+ Creating Custom Result Renderers
+
+
Create a renderer for your result.
+
+
Events
+
Learn about all the events available for listening to in the workshop framework and how to listen to them.
+
+
+ Creating Listener Checks
+
+
Learn how to utilise events to build a Listener Check by following a tutorial to build a Couch DB check.
+
+
+ Self Checking Exercise
+
+
Add simple checking logic directly in your exercise.
+
+
+ Exercise Events
+
+
Listen to events directly in your exercise instead of building a custom check.
+
+
+ Patching Exercise Solutions
+
+
+ Learn how to modify the student's solution on the fly, injecting variables, wrapping code in in
+ try/catch
+ blocks, registering error handlers and so on.
+
+ As we have seen in the previous articles, you can build your own custom checks. Checks can be used in as many exercises as you want - you could even create a package which consists of common
+ checks you might want to use in your workshops. The check we built in the
+ Creating Simple Checks
+ article is a good example of a reusable check; you might want to include this in all your exercises.
+
+
But what if you want to perform a check that you don't think you will use again? You don't really want to create a class to encompass this logic when it is only to be used in one exercise.
+
Enter the Self Checking feature!
+
+
+ The Self Checking feature allows your exercise to implement an interface which contains one method -
+ check()
+ during the verification process of the student's solution, your method will be called and passed the input arguments passed to our workshop, which will contain the file name of the student's
+ solution. In this method you can do whatever you want: parse the code into an AST using the
+ PhpParser\Parser
+ service, lint it using a third party tool or whatever else you can think of.
+
+
+
+ To give you an example of how you might use it - we use it
+ here in Learn You PHP!
+ to check that a submission contains an
+ include
+ /
+ require
+ statement as the exercise is teaching how to separate code over multiple files. We want to enforce the student to include a separate file.
+
+
+ Creating a self checking exercise
+
+
+ Creating a self checking exercise requires implementing the interface
+ PhpSchool\PhpWorkshop\ExerciseCheck\SelfCheck
+ , adding your check logic and returning a
+ result
+ . Depending on whether you want a success or a failure to be recorded it will be an instance of
+ PhpSchool\PhpWorkshop\Result\SuccessInterface
+ or
+ \PhpSchool\PhpWorkshop\Result\FailureInterface
+ .
+
+
+
The interface looks like this:
+
+
+<?php
+
+namespace PhpSchool\PhpWorkshop\ExerciseCheck;
+
+use PhpSchool\PhpWorkshop\Result\ResultInterface;
+use PhpSchool\PhpWorkshop\Input\Input;
+
+interface SelfCheck
+{
+ /**
+ * The method is passed the absolute file path to the student's solution and should return a result
+ * object which indicates the success or not of the check.
+ *
+ * @param Input $input The command line arguments passed to the command.
+ * @return ResultInterface The result of the check.
+ */
+ public function check(Input $input);
+}
+
+
+
+
You can implement like so:
+
+
+<?php
+
+class Mean extends AbstractExercise implements ExerciseInterface, CliExercise, SelfCheck
+{
+
+ ...omitting methods described in ExerciseInterface
+
+ /**
+ * @param Input $input
+ * @return ResultInterface
+ */
+ public function check(Input $input)
+ {
+ //do some checking with $input
+
+ if ($someResult) {
+ return new Success('My Check');
+ }
+
+ return new Failure('My Check', "Something didn't go well!");
+ }
+}
+
+
+
+
+ As you can see, you do the checking logic and then return a result object. The result object is used to render the results to the student. In this case the first argument to
+ PhpSchool\PhpWorkshop\Result\Success
+ is the name of the check being performed. The same is true for the failure
+ PhpSchool\PhpWorkshop\Result\Failure
+ , however, it takes an optional second argument which should describe what went wrong.
+
+
+
+ Learn more about results
+ here
+ .
+
+
+ Example PSR2 self checking exercise
+
+ Contrary to what we said earlier (a PSR2 check would be a good candidate for a re-usable check), let's build that as a self check. We will use the already built example workshop as a base - the
+ finished code is available on the
+ self-checking-exercise
+ branch of the
+ tutorial repository
+ .
+
+
+ We will start fresh from the
+ master
+ branch for this tutorial, so if you haven't already got it, git clone it and install the dependencies:
+
+
+
+
+
+ Our check will run the
+ PHP_CodeSniffer
+ tool against the student's solution and report a success or failure based on the result.
+
+
+ 1. Require the PHP_CodeSniffer tool as a dependency
+
+
+
+ 2. Modify the exercise to implement the SelfCheck interface
+
+ As you can see, our check does nothing at the minute. Let's add the logic to execute
+ phpcs
+ on the student's solution using the
+ PSR2
+ standard. As we brought in the tool via Composer, we can rest assured that the binary
+ phpcs
+ is available in our projects
+ vendor
+ directory.
+
+
Our method might look something like this - nothing new going on:
+
+
+
+/**
+ * @param Input $input
+ * @return ResultInterface
+ */
+public function check(Input $input)
+{
+ $phpCsBinary = __DIR__ . '/../../vendor/bin/phpcs';
+ $cmd = sprintf('%s %s --standard=PSR2', $phpCsBinary, $input->getArgument('program'));
+ exec($cmd, $output, $exitCode);
+
+ if ($exitCode === 0) {
+ return new Success('PSR2 Code Check');
+ }
+
+ return new Failure('PSR2 Code Check', 'Coding style did not conform to PSR2!');
+}
+
+
+
+
+ If the
+ phpcs
+ binary returns a non-zero exit code - a failure occurred: probably the solution did not pass the coding standard check. So we return a failure with an error message. Otherwise a Success is
+ returned.
+
+
+
+ Verifying a solution which does not pass the
+ PSR2
+ coding standard will yield the output:
+
+
+
+ And a solution which
+ does
+ pass would yield the output:
+
+ In this article we will learn how to create a simple check. If you don't fully understand what checks are, head over to the
+ Exercise Checks
+ article.
+
+
+
We will build a fairly boring check which verifies that a student's solution passes the PSR2 coding standard. Lets get started!
+
+
+ Creating a check begins with creating a file and a class for our check . We need to implement the interface
+ PhpSchool\PhpWorkshop\Check\SimpleCheckInterface
+ which extends from
+ PhpSchool\PhpWorkshop\Check\CheckInterface
+ . Let's breakdown these methods before we start coding:
+
+
+ getName()
+
+ This method should just return a
+ string
+ which represents the name of the check. This will be printed on the terminal during the verification process. This will be
+ PSR2 Code Check
+ for our check.
+
+
+ getExerciseInterface()
+
+ This method should just return a
+ string
+ which is the FQCN (Fully Qualified Class Name) of the interface that the exercise needs to implement when requiring our check. Because we don't need any extra information for our check we can just
+ use
+ PhpSchool\PhpWorkshop\Exercise\ExerciseInterface
+ .
+
+
+ canRun(ExerciseType $exerciseType)
+
+ This method receives an
+ ExerciseType
+ instance which represents the type of exercise, we use this to inform the workshop which exercise types our check works with:
+ CLI
+ ,
+ CGI
+ or
+ CUSTOM
+ . We will support
+ CLI
+ &
+ CGI
+ .
+
+ This is the method where we actually perform our check logic, executing PHP_CodeSniffer. This method receives an instance of the current exercise and the input arguments passed to our workshop,
+ which will contain the file name of the student's solution.
+
+
+
+ This method needs to return an instance of
+ PhpSchool\PhpWorkshop\Result\ResultInterface
+ . Depending on whether you want a success or failure to be recorded it will be an instance of
+ PhpSchool\PhpWorkshop\Result\SuccessInterface
+ or
+ PhpSchool\PhpWorkshop\Result\FailureInterface
+ . Learn about results
+ here
+ .
+
+
+ getPosition()
+
+
+ This method should return one of two constants
+ PhpSchool\PhpWorkshop\Check\SimpleCheckInterface::CHECK_BEFORE
+ ,
+ PhpSchool\PhpWorkshop\Check\SimpleCheckInterface::CHECK_AFTER
+ . This value indicates when the check should be run.
+
+
+ The verification process
+
+
The process of verifying a student's solution looks something like the following (pseudo code):
+
+
+
+//run before checks
+foreach ($beforeChecks as $check) {
+ $result = $check->check($exercise, $submissionFilePath);
+
+ if (!$result->isSuccessful()) {
+ return;
+ }
+}
+
+//compare output of student solution and reference solution
+$this->verifier->compareOutput($exercise);
+
+foreach ($afterChecks as $check) {
+ $result = $check->check($exercise, $submissionFilePath);
+ //store result
+}
+
+
+
+ Before Verifying
+
+ When a check uses
+ CHECK_BEFORE
+ mode it is run before the output verification. The process is also short circuited if a check returns a failure. No more checks will be run and the output will not be compared.
+
+
+ After Verifying
+
+ When a check use
+ CHECK_AFTER
+ mode it is run after the output verification. This means that the check is run after the student's solution has been run. After checks are useful for verifying that something was actually
+ performed in the students submission, for example, inserting a row into the database.
+
+
+ Build the check
+
+
+ Now - let's build it! We will use the already built tutorial workshop as a base - the finished code is available on the
+ custom-simple-check
+ branch of the
+ tutorial repository
+ . We will start fresh from the
+ master
+ branch for this tutorial, so if you haven't already got it, git clone it and install the dependencies:
+
+
+
+
+
+ Our check will run the
+ PHP_CodeSniffer
+ tool against the student's submission and report a success or failure based on the result.
+
+
+ 1. Require the PHP_CodeSniffer tool as a dependency
+
+
+ 2. Create the folder and class
+
+
+ 3. Write the class
+
+
+<?php
+
+namespace PhpSchool\SimpleMath\Check;
+
+use PhpSchool\PhpWorkshop\Check\SimpleCheckInterface;
+use PhpSchool\PhpWorkshop\Exercise\ExerciseInterface;
+use PhpSchool\PhpWorkshop\Exercise\ExerciseType;
+use PhpSchool\PhpWorkshop\Result\Failure;
+use PhpSchool\PhpWorkshop\Result\Success;
+use PhpSchool\PhpWorkshop\Input\Input;
+
+class Psr2Check implements SimpleCheckInterface
+{
+
+ public function getName()
+ {
+ return 'PSR2 Code Check';
+ }
+
+ public function getExerciseInterface()
+ {
+ return ExerciseInterface::class;
+ }
+
+ public function canRun(ExerciseType $exerciseType)
+ {
+ return in_array($exerciseType->getValue(), [ExerciseType::CGI, ExerciseType::CLI]);
+ }
+
+ public function check(ExerciseInterface $exercise, Input $input)
+ {
+ $phpCsBinary = __DIR__ . '/../../vendor/bin/phpcs';
+ $cmd = sprintf('%s %s --standard=PSR2', $phpCsBinary, $input->getArgument('program'));
+ exec($cmd, $output, $exitCode);
+
+ if ($exitCode === 0) {
+ return new Success($this->getName());
+ }
+
+ return new Failure($this->getName(), 'Coding style did not conform to PSR2!');
+ }
+
+ public function getPosition()
+ {
+ return static::CHECK_BEFORE;
+ }
+}
+
+
+
+
+ If the
+ phpcs
+ binary returns a non-zero exit code - a failure occurred: probably the solution did not pass the coding standard check. So we return a failure with an error message. Otherwise a Success is
+ returned.
+
+
+
+ As we brought in the tool via Composer, we can rest assured that the binary
+ phpcs
+ is available in our projects
+ vendor
+ directory.
+
+
+ 4. Register the Check and add a factory
+
+ Now you need to tell the application about your new check. We need to register a factory.
+ What's a factory?
+ Open up
+ app/config.php
+ and add an entry for your check. The resulting file should look like:
+
+
+
+
+<?php
+
+use function DI\factory;
+use function DI\object;
+use Interop\Container\ContainerInterface;
+use PhpSchool\SimpleMath\Check\Psr2Check;
+use PhpSchool\SimpleMath\Exercise\Mean;
+use Symfony\Component\Filesystem\Filesystem;
+
+return [
+ //Define your exercise factories here
+ Mean::class => object(),
+
+ //my checks
+ Psr2Check::class => object(),
+];
+
+
+
+
+ Note the new entry for
+ Psr2Check::class => object(),
+ . Finally, we need to tell the application about our check in
+ app/bootstrap.php
+ . After the application object is created you just call
+ addCheck
+ with the name of check class. Your final
+ app/bootstrap.php
+ file should look something like:
+
+
+
+
+<?php
+
+ini_set('display_errors', 1);
+date_default_timezone_set('Europe/London');
+switch (true) {
+ case (file_exists(__DIR__ . '/../vendor/autoload.php')):
+ // Installed standalone
+ require __DIR__ . '/../vendor/autoload.php';
+ break;
+ case (file_exists(__DIR__ . '/../../../autoload.php')):
+ // Installed as a Composer dependency
+ require __DIR__ . '/../../../autoload.php';
+ break;
+ case (file_exists('vendor/autoload.php')):
+ // As a Composer dependency, relative to CWD
+ require 'vendor/autoload.php';
+ break;
+ default:
+ throw new RuntimeException('Unable to locate Composer autoloader; please run "composer install".');
+}
+
+use PhpSchool\PhpWorkshop\Application;
+use PhpSchool\SimpleMath\Check\Psr2Check;
+use PhpSchool\SimpleMath\Exercise\Mean;
+
+$app = new Application('Simple Math', __DIR__ . '/config.php');
+
+$app->addExercise(Mean::class);
+$app->addCheck(Psr2Check::class);
+
+$art =<<<ART
+ ∞ ÷ ∑ ×
+
+ PHP SCHOOL
+SIMPLE MATH
+ART;
+
+$app->setLogo($art);
+$app->setFgColour('red');
+$app->setBgColour('black');
+
+return $app;
+
+
+
+ 5. Require the check in an exercise
+
+ Open up the Mean Average exercise file:
+ src/Exercise/Mean.php
+ and add in the following method, take care to import the necessary classes (
+ PhpSchool\PhpWorkshop\ExerciseDispatcher
+ &
+ PhpSchool\SimpleMath\Check\Psr2Check
+ ):
+
+
+
+
+public function configure(ExerciseDispatcher $dispatcher)
+{
+ $dispatcher->requireCheck(Psr2Check::class);
+}
+
+
+
Hopefully you will remember this from the previous section - we are just telling the exercise to use our custom check!
+
+ Try it out!
+
+
+ Run the workshop and select the Mean Average exercise. Verifying a solution which does not pass the
+ PSR2
+ coding standard will yield the output:
+
+ When you build checks, sometimes you need extra information from the exercise to configure the check. For example, the
+ FunctionRequirementsCheck
+ check calls
+ getRequiredFunctions()
+ &
+ getBannedFunctions()
+ on the exercise, these methods are defined on the extra interface
+ FunctionRequirementsExerciseCheck
+ which the exercise must implement if it requires the
+ FunctionRequirementsCheck
+ check.
+
+
+
+ Maybe we want to make the standard for our check configurable - it could be
+ PSR1
+ ,
+ PSR2
+ ,
+ PEAR
+ or any of the other standards PHP_CodeSniffer supports. We will make this configuration available through the method
+ getStandard()
+ .
+
+
+ 1. Define our interface
+
We need an interface to define our required method. Let's do that first:
+
+
+
+
+ Now would probably be a good idea to change our check name to something a little less specific, but we'll leave that up to you, probably
+ PhpCsCheck
+ might be a little better. Okay, lets define our interface. We want the one method
+ getStandard
+ to return a string representing one of the
+ available standards
+ :
+
+ We need to update the
+ getExerciseInterface()
+ method in our check to return the name of our new interface. Open up
+ src/Check/Psr2Check.php
+ and change the
+ getExerciseInterface()
+ method to match below:
+
+
+
+
+public function getExerciseInterface()
+{
+ return Psr2ExerciseCheck::class;
+}
+
+
+
+
+ We also need to modify our
+ check()
+ method to actually use this data:
+
+
+
+
+public function check(ExerciseInterface $exercise, $fileName)
+{
+ if (!$exercise instanceof Psr2ExerciseCheck) {
+ throw new \InvalidArgumentException;
+ }
+
+ $standard = $exercise->getStandard();
+
+ if (!in_array($standard, ['PSR1', 'PSR2', 'PEAR'])) {
+ throw new \InvalidArgumentException('Standard is not supported');
+ }
+
+ $phpCsBinary = __DIR__ . '/../../vendor/bin/phpcs';
+ $cmd = sprintf('%s %s --standard=%s', $phpCsBinary, $input->getArgument('program'), $standard);
+ exec($cmd, $output, $exitCode);
+
+ if ($exitCode === 0) {
+ return new Success($this->getName());
+ }
+
+ return new Failure($this->getName(), 'Coding style did not conform to PSR2!');
+}
+
+
+
+ We've added a couple of things here - we make sure the exercise actually implements our required interface, if not we throw an exception. We check if the standard provided is in a small subset of
+ supported standards, and finally, we pass the standard along to the
+ phpcs
+ command.
+
+
+ 3. Update our exercise
+
+ Now we have to implement the new interface and methods in our exercise, for our Mean Average exercise, we will still require
+ PSR2
+ as the coding standard. The final exercise should look similar to below:
+
You should be able to run it just the same as before we added the extra interface. You can now easily update your exercise to use a different coding standard without modifying the check.
+
+
+ Maybe you could try updating the check to take into account the standard when returning the result? It currently has
+ PSR2
+ hardcoded in the message!
+
+
+
+ You can see the finished, working code on the
+ custom-interface-check
+ branch of the
+ tutorial repository
+ .
+
+ Internally, the workshop framework uses a
+ dependency injection container
+ . This allows you to request other services from the application and replace services with your own implementations. We use the
+ PHP-DI
+ package for dependency injection, a
+ container-interop
+ compatible dependency injection container.
+
+
+ Services are configured in
+ app/config.php
+ . You can use all of the features of
+ PHP-DI
+ so check the docs there.
+
+
+
+ The file
+ app/config.php
+ should return an array of service definitions for the container. The key being the name of the service and the value the actual factory.
+
+
+ Defining Factories
+
+ Simple Object with No dependencies
+
+ \DI\Object()
+ is a helper function to create a factory which will simply run
+ new $yourClassName
+ when asking for the service from the container.
+
+ PHP-DI provides more powerful features such as being able to use anonymous functions and any valid PHP
+ callables
+ as a factory. When using a callable your callable will be injected with the container itself which you can pull other services from!
+
+
+ If you pulled in a third party library for random number generation you might define a service like below. We use the battle tested package:
+ ircmaxell/random-lib
+ as an example.
+
+
We use an anonymous function and pull the strength parameter from the container and create a new random number generator based on that.
+ As your workshop configuration is merged into default workshop framework configuration, you can override existing services with your own implementation. Maybe you want to override the
+ \Symfony\Component\Filesystem\Filesystem
+ service with your own version, maybe you extended it to add some methods.
+
+
+ The below definition would replace the
+ Symfony\Component\Filesystem\Filesystem
+ service with your own implementation:
+ MyFileSystem
+ which extends from
+ \Symfony\Component\Filesystem\Filesystem
+ .
+
+ Now when you ask the container for
+ Symfony\Component\Filesystem\Filesystem
+ you will receive an instance of
+ MyFileSystem
+ .
+
+
+ Be aware that anything already using the
+ Symfony\Component\Filesystem\Filesystem
+ service will expect it to be an instance of
+ \Symfony\Component\Filesystem\Filesystem
+ , so if you replace it with an altogether different object, expect things to break!
+
+
+
+ Check
+ Available Services
+ for a list and description of services available to you.
+
A workshop is a fairly useless without any exercises, so here we will learn how to create them.
+ It may be a good idea for exercises to start off simple and gradually increase in difficulty. You could try to explain concepts and build on them with each exercise.
+
+ Exercise checklist
+
+
Decide on a topic to teach.
+
Create a working reference solution.
+
Create a problem file.
+
Write the exercise.
+
+
+
We will decide on a topic of basic PHP operators, more specifically working out the mean average of a given set of numbers.
+
+ Exercise specification
+
+
+
The student should print out the mean average and nothing else. No new lines or whitespace.
+
The numbers passed to the program should be random.
+
The amount of numbers passed to the program should be random.
+
The numbers should be passed to the program as command line arguments.
+
+
+
Given this specification we could write a program which would serve as our reference solution.
+ We should place this file in
+ exercises/mean-average/solution/solution.php
+
+
+
+ Reference solutions are known, working programs which pass the exercise. When running a students's solution to an exercise, the reference solution is executed and the output compared to the
+ student's.
+
+
+ The next step is to create a problem file. A problem file contains the instructions for the exercise. It should be a markdown file. This file is rendered in the Terminal to the student when they
+ select the exercise.
+
+
+ Tips for a good problem file
+
+
Provide a solid description of the problem.
+
Provide some sample code which may need to be modified.
+
Provide hints and tips.
+
Provide links to the PHP documentation and good articles from reputable sources regarding key areas of the problem.
+
+
+
Our problem file might look like the following.
+
+
+Write a program that accepts one or more numbers as command-line arguments and prints the mean average of those numbers to the console (stdout).
+
+----------------------------------------------------------------------
+## HINTS
+
+You can access command-line arguments via the global `$argv` array.
+
+To get started, write a program that simply contains:
+
+```php
+var_dump($argv);
+```
+
+Run it with `php program.php` and some numbers as arguments. e.g:
+
+```sh
+$ php program.php 1 2 3
+```
+
+In which case the output would be an array looking something like:
+
+```php
+array(4) {
+[0] =>
+string(7) "program.php"
+[1] =>
+string(1) "1"
+[2] =>
+string(1) "2"
+[3] =>
+string(1) "3"
+}
+```
+
+You'll need to think about how to loop through the number of arguments so you can output just their mean average. The first element of the `$argv` array is always the name of your script. eg `program.php`, so you need to start at the 2nd element (index 1), adding each item to the total until you reach the end of the array. You will then need to work out the average based on the amount of arguments given to you.
+
+You can read how to work out an average here:
+ [https://www.mathsisfun.com/mean.html]()
+
+Also be aware that all elements of `$argv` are strings and you may need to *coerce* them into numbers. You can do this by prefixing the property with a cast `(int)` or just adding them. PHP will coerce it for you.
+
+`{appname}` will be supplying arguments to your program when you run `{appname} verify program.php` so you don't need to supply them yourself. To test your program without verifying it, you can invoke it with `{appname} run program.php`. When you use `run`, you are invoking the test environment that `{appname}` sets up for each exercise.
+
+----------------------------------------------------------------------
+
+
+
+ Any instances of
+ {appname}
+ will be replaced with the actual application name, this will most likely be the configuration you set when creating your workshop as this is inferred from the command the student executed to run
+ the workshop.
+
+
+ Drop this file in
+ exercises/mean-average/problem/problem.md
+ .
+
+
+ Write the exercise
+
+
Now we write the code, there is not much to it, this is a simple exercise!
+ Place the above in
+ src/Exercise/Mean.php
+ .
+
+
Now lets break this down.
+
This class represents our exercise, it describes how the programs will be executed, the student's and our reference solution.
+
+ AbstractExercise
+
+ The
+ AbstractExercise
+ class implements a few interesting methods for us. Mainly
+ getSolution
+ and
+ getProblem
+ . These methods are responsible for locating your solution and problem files. By default they take your exercise's name, normalise it (remove anything that is not A-Za-z or a dash, lowercase and
+ replace spaces with dashes) and look in the
+ exercises/<normalised-name>/solution
+ and
+ exercises/<normalised-name>/problem
+ folders for files named
+ solution.php
+ and
+ problem.md
+ respectively. There maybe be cases when you need to override these methods, and in that case you probably don't need to extend from
+ AbstractExercise
+ .
+
+
+ You may need to override the methods
+ getSolution
+ and
+ getProblem
+ if you want to organise your problems and solutions in a different structure. We would advise against this in the name of consistency but if you have a good enough reason then the option is there.
+ There may also be the case that your solution is not simply one file. Jump over to
+ Exercise Solutions
+ to learn more, if that is the case.
+
+
+ Exercise Type
+
+ Each exercise must have a type, there are currently two types of exercise:
+ CGI
+ ,
+ CLI
+ &
+ CUSTOM
+ . Head over to
+ Exercise Types
+ to learn more. We are currently building a
+ CLI
+ type exercise, this means our reference solution and the student's solution programs will be invoked using the PHP CLI binary. The arguments will come from our exercise class. We inform the
+ workshop of our exercise type by returning an instance of
+ ExerciseType
+ from the
+ getType
+ method.
+ ExerciseType
+ is an ENUM. In conjunction with this, our exercise should implement the respective interface. For
+ CLI
+ type exercises this is
+ CliExercise
+ .
+
+
+ CliExercise
+
+ This interface defines one method:
+ getArgs
+ . This method should return an array of arrays containing string arguments which will be passed to our reference solution and the student's solution at runtime. Each set of arguments will be sent
+ to the solution. So you could essentially run the student's solution as many times as you wanted with different arguments. This method can return random records and random numbers of arguments so
+ that each time the student runs the verification process they receive different arguments. This makes sure the solution is robust.
+
+ Try passing arguments which will test the boundaries of the student's solution, for example using minimum and maximum values and using random values on each invocation.
+
+ Do Note that although your implementation of
+ getArgs
+ may return random arguments, your reference solution and the student's solution will always receive the same arguments as the
+ getArgs
+ method is only called once.
+
+
Our exercise simply returns one set of random number of arguments between 0 and 10, each being a random number between 0 and 100.
+
+ Name and description
+
+ The remaining methods to implement are
+ getName
+ and
+ getDescription
+ .
+ getName
+ is the name of the exercise to be displayed in the menu and
+ getDescription
+ is a short description of the exercise. This is not actually used anywhere yet but is useful when glancing through the code.
+
+
+ Registering the exercise and adding a factory
+
+
+ Internally, the workshop application uses a
+ dependency injection container
+ . This allows you to request other services from the application and replace services with your own implementations. In order for the application to locate your exercise, you need to register it
+ with the application and also provide a factory for it. We use the
+ PHP-DI
+ package for dependency injection.
+
+
+ First, lets create a factory for our exercise. Open up
+ app/config.php
+ .
+
+
+
+
+return [
+ Mean::class => \DI\object(),
+];
+
+
+ The file
+ app/config.php
+ should return an array of service definitions for the container. The key being the name of the service and the value the actual factory. For the case of exercises the service name should
+ always
+ be the class name.
+ \DI\object()
+ is a helper function to create a factory which will simply run
+ new $yourClassName
+ when asking for the service from the container.
+
+
+
+ See the section on
+ The Container
+ for more information on service definitions.
+
+
+
+ You are almost done! we have registered the factory which tells the application how to create your exercise. We just need to make it aware of your exercise. We do this in
+ app/bootstrap.php
+ . After the
+ Application
+ object is created you just call
+ addExercise
+ with the name of your exercise class. Your final
+ app/bootstrap.php
+ file should look something like the following:
+
+
+
+<?php
+ini_set('display_errors', 1);
+date_default_timezone_set('Europe/London');
+switch (true) {
+ case (file_exists(__DIR__ . '/../vendor/autoload.php')):
+ // Installed standalone
+ require __DIR__ . '/../vendor/autoload.php';
+ break;
+ case (file_exists(__DIR__ . '/../../../autoload.php')):
+ // Installed as a Composer dependency
+ require __DIR__ . '/../../../autoload.php';
+ break;
+ case (file_exists('vendor/autoload.php')):
+ // As a Composer dependency, relative to CWD
+ require 'vendor/autoload.php';
+ break;
+ default:
+ throw new RuntimeException('Unable to locate Composer autoloader; please run "composer install".');
+}
+
+use PhpSchool\PhpWorkshop\Application;
+use PhpSchool\SimpleMath\Exercise\Mean;
+
+$app = new Application('Simple Math', __DIR__ . '/config.php');
+
+$app->addExercise(Mean::class);
+
+$art = <<<ART
+ ∞ ÷ ∑ ×
+
+ PHP SCHOOL
+SIMPLE MATH
+ART;
+
+$app->setLogo($art);
+$app->setFgColour('red');
+$app->setBgColour('black');
+
+return $app;
+
+
+
+
That's it! You should now see your exercise in the menu when you run the app.
+ In this tutorial we will be building a simple workshop which is available
+ here on GitHub
+ as a reference, if you have any problems, you can double check your work.
+
+
+
+ In order to create a workshop the first thing you will need to do is to setup a new project and configure the dependencies and wire it all together. Luckily for you we have created a starter kit
+ which does this all for you, prompting you along the way. Simply execute the following command in your shell.
+
+
+
+
+
+ Where
+ <your-workshop-name>
+ is the name of the directory you want to setup your workshop in. For this tutorial we will create a workshop teaching some basic math concepts so we will use the name
+ simple-math
+ . You will be prompted for a few things:
+
+
+ Composer package name
+
+ The name for your workshop to be put in the
+ composer.json
+ file. This should follow the pattern
+ vendor/package
+ . In the case of our flagship workshop
+ Learn You PHP!
+ this is
+ php-school/learn-you-php
+ . Name your package
+ php-school/simple-math
+ .
+
+ A short description of your workshop which will be added to the
+ composer.json
+ file. Add a short description here, something like:
+ Learn the basics of math with PHP!
+
+ The namespace which will be used in the project so it can be added to the autoload configuration in the
+ composer.json
+ file. In the case of
+ Learn You PHP!
+ this is
+ PhpSchool\LearnYouPhp
+ . We will use
+ PhpSchool\SimpleMath
+ .
+
+ This is the actual command students will execute to run your workshop. In the case of
+ Learn You PHP!
+ this is
+ learnyouphp
+ . You should set this as
+ simple-math
+ .
+
+
+
+
+
+
After you have entered the required information the workshop dependencies will be downloaded and the autoload files will be generated.
+
+
Generate the autoload information for our Namespace:
+
+
+ Assuming everything went well and your are in the root of your new workshop you should be able to run the workshop!
+
+
+
+ Where
+ <binary-name>
+ is the name your previously entered during the
+ create-project
+ command. In our case:
+
+
+
+
+
+
+
+ If you don't see the menu above, then something went wrong. Get in touch with us and bring any helpful information such as error messages with you!
+
diff --git a/assets/components/Website/Docs/Sections/Tutorial/ModifyTheme.vue b/assets/components/Website/Docs/Sections/Tutorial/ModifyTheme.vue
new file mode 100644
index 00000000..8c84109a
--- /dev/null
+++ b/assets/components/Website/Docs/Sections/Tutorial/ModifyTheme.vue
@@ -0,0 +1,59 @@
+
+
+
+ You can alter the colours, logo and text of your workshop very easily. Look in
+ app/bootstrap.php
+ and you should see the following code.
+
+ You can modify any of these settings. Available colours are black, red, green, yellow, blue, magenta, cyan, white.
+ setLogo
+ takes a
+ string
+ and can be used display ascii art!
+
+
+ You can set the title of your workshop which will be displayed on the terminal by changing the
+ null
+ argument to
+ Application
+ to a title of your choice. For example:
+
+
+
+
$app = new Application('My Workshop', __DIR__ . '/config.php');
+
+
+
We will customise the theme a little to be more representative of our subject:
+
+
+
+$art = <<<ART
+ ∞ ÷ ∑ ×
+
+ PHP SCHOOL
+SIMPLE MATH
+ART;
+
+$app->setLogo($art);
+$app->setFgColour('red');
+$app->setBgColour('black');
+ So.. you want to create your own workshop? You want to teach a subject using the workshop environment? You want to make a meetup more hands on? You want to showcase your tool? You've come to the
+ right place!
+
+
+ We will be building a simple workshop which is available
+ here on GitHub
+ as a reference. So if you have any problems, you can double check your work.
+
+
+ Tutorial Sections
+
+
+ 1. Creating your own workshop
+
+
Learn how to create and setup your very own workshop.
+
+ 2. Modifying the theme of your workshop
+
+
Customise the look and feel of your workshop, personalise to your brand or subject.
Write a program that prints the text "Hello World" to the console (stdout).
+
+
HINTS
+
+ We've created you an empty file, look in the file tree for
+ solution.php
+ . That's your starting point.
+
+
+ We'll execute your solution file for you when you press the
+ Run
+ or
+ Verify
+ buttons. The
+ Run
+ button simply runs your program and captures the output, displaying it for you to view. The
+ Verify
+ button runs your program but performs some extra tasks, such as comparing the output, checking for certain structures and function calls, etc. It then displays the result of those
+ verifications.
+
+
+ Both
+ Run
+ and
+ Verify
+ execute your program with random inputs which are determined by the current exercise. For example one exercise might generate a bunch of numbers to pass to your program, where another one
+ might pass you a JSON encoded string.
+
+
You can write to the console from a PHP program with the following code:
+
+
+ The first line tells PHP to interpret the code following it. It is required before any PHP code is written. The second line is the instruction to print out some text.
+
+ Try pressing the
+ Run
+ button in the bottom right corner to execute your program.
+
+
You should see the word "text" printed out on the console.
+
Now you must adapt the code to pass the presented challenge. Remember, the challenge was: Write a program that prints the text "Hello World" to the console.
+
+ When you have finished editing your program you must verify it. Click the
+ Verify
+ button in the bottom right corner.
+
+
Your program will be tested, a report will be generated, and the lesson will be marked 'completed' if you are successful.
+
diff --git a/assets/components/Website/Pages/Home/Section/BuildYourOwn.vue b/assets/components/Website/Pages/Home/Section/BuildYourOwn.vue
new file mode 100644
index 00000000..9fb964b6
--- /dev/null
+++ b/assets/components/Website/Pages/Home/Section/BuildYourOwn.vue
@@ -0,0 +1,71 @@
+
+
+
+
+
+ Build your own workshop
+
+ + Host it on PHP School
+
+
+
+
+
Explore the Documentation
+
+ We're sure you're eager to jump in and start coding, but you're gonna have to slow down a little. The first step to creating your own workshop is to read the documentation:
+
+
+
+
+
+
Build your workshop
+
+ Now it's time to build - you will create your base application, define a theme and a topic, design a set of exercises which progress in difficulty and introduce new and advanced topics to
+ the student. All in PHP.
+
+
+
+
+
+
+
+
Submission and review
+
+ Once you've built your workshop, you
+ submit
+ it to us. We will perform a few basic automated checks and then a further manual review. Once it's approved, it will be installable via
+ workshop-manager
+ and then later on, as part of PHP School Online!
+
+
+
+
+
Open to the world
+
+ Your workshop is available for the world to see, use and learn from. Not only that but it's open source, it's available for other developers to update, fix, improve the copy, translate and
+ so on!
+
+
+
+
+
+
diff --git a/assets/components/Website/Pages/Home/Section/GettingStarted.vue b/assets/components/Website/Pages/Home/Section/GettingStarted.vue
new file mode 100644
index 00000000..29dec3fe
--- /dev/null
+++ b/assets/components/Website/Pages/Home/Section/GettingStarted.vue
@@ -0,0 +1,78 @@
+
+
+
+
+ Getting Started
+
+
+ PHP School workshops are a set of exercises focused on a specific topic or overarching theme, such as new language versions or tools and techniques. See the
+ below section
+ for the list of available workshops.
+
+
+
+ Workshops can be run in your browser or you can download them and run them on your own computer. Running them on your own computer is a little bit more involved, however, it is also more
+ flexible and self contained.
+
+
+
+
+
+
+ Online Browser Based
+
+
Simply login or register with your GitHub account, head to the dashboard, select an exercise and go.
+
+ Not all exercises are available in the online IDE, for example if some workshops are not kept up to date they may get dropped. However, you will always be able to install them on your own
+ computer.
+
Naturally, you need to be comfortable in a terminal such as iTerm and know your way around a decent text editor or IDE.
+
+
+
+
+
+
+ {{ line }}
+
+
+
+
+
+
+
+
+
+ {{ line }}
+
+
+
+
+
+ To the workshops
+
+
+ To the installation instructions
+
+
+
+
+
diff --git a/assets/components/Website/Pages/Home/Section/TheWorkshops.vue b/assets/components/Website/Pages/Home/Section/TheWorkshops.vue
new file mode 100644
index 00000000..ce152fe4
--- /dev/null
+++ b/assets/components/Website/Pages/Home/Section/TheWorkshops.vue
@@ -0,0 +1,102 @@
+
+
+
+
+ The Workshops
+
+
+
+
+
core
+
+ Workshops meticulously crafted by the PHP School team with the utmost quality to help
+ you
+ learn the core concepts of PHP and web development.
+
+
+
+
+
+
Community
+
+ Community workshops are those created by, well, you! They are not officially maintained by the PHP School team and not all of them are compatible with the online system. Compatible ones are
+ labeled, otherwise, you can always run them
+ offline
+ .
+
+
+
+ Documentation
+
+ Ready for the next steps? Use the PHP School workshop documentation to build you own workshop and help teach others how to code with PHP!
+
+
+
+ Test your solution at any time to get instant feedback. If you get it wrong, we’ll show you how and what went wrong versus what we expected. Maybe you just need a simple tweak, or to
+ altogether reconsider your approach. When you solve an exercise, your profile is updated and the exercise is marked as completed. Before proceeding you have the opportunity to see our
+ official solution so you can compare notes and optimise your own solution. Maybe your solution is better!
+
+
+ Try writing:
+ echo "Hello World";
+ in the input below to see how we verify your solution and provide feedback.
+
+
+
+
+ PHP School on the
+
+ Command Line
+
+
+
+ In order to get started with PHP School workshops, you first need to install the workshop manager. Before we can do this we need to check you have a few things
+
+
+
+
+ Getting Started
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Requirements Check
+
+ In order to get started with PHP School workshops, you first need to install the workshop manager. Before we can do this we need to check you have a few things:
+
+
+
+
+
+
+
You will need PHP with a version of at least 7.1 although we recommend using the latest available.
+
+
+
+
You will also need a Text Editor so you can work through the workshops. You can try Atom or Sublime if you don't already have one.
+
+
+
+
+
Once the above are satisfied, run the following commands in your terminal, to install the workshop manager.
+
+
+
+
+
+
+
+
+
+ Troubleshooting
+
+
+
+
+
+
+
+
Apple Mac
+
+
+
+
+
+
Linux
+
+
+
+
+
+
Windows
+
+
+
+
+
+
Apple Mac
+
Common issues with Mac OSX installations include not having a new enough version of PHP and not having Composer available.
+
+
+
If you have a PHP version less than 8.1, you will need to update it to at least 8.1, you can do so with the following commands
+
+
+ You can check your PHP version with
+ php -v
+
+
+
+
+
+
+ After installing a workshop using the workshop manager you may find it's not available to run immediately. If this happens the simplest remedy is to make sure PHP School's workshop
+ bin directory is available in the
+ $PATH
+ environment variable. You can check this with
+ workshop-manager
+ verify which will also provide the relevant details on how to resolve the issue. To learn more about the
+ $PATH
+ environment, click
+ here
+ .
+
+
+
+
+
+
Linux
+
Common issues with Linux installations include not having a new enough version of PHP and not having Composer available.
+
+
+
If you have a PHP version less than 8.1, you will need to update it to at least 8.1, you can do so with the following commands
+
+
+ You can check your PHP version with
+ php -v
+
+
+
+
+
+
+ After installing a workshop using the workshop manager you may find it's not available to run immediately. If this happens the simplest remedy is to make sure PHP School's workshop
+ bin directory is available in the
+ $PATH
+ environment variable. You can check this with
+ workshop-manager
+ verify which will also provide the relevant details on how to resolve the issue. To learn more about the
+ $PATH
+ environment, click
+ here
+ .
+
+
+
+
+
+
Windows
+
+ Windows is a difficult system to cater for in the PHP world. Unfortunately, it has various differences on the command line and console emulators which PHP unfortunately doesn't
+ support. The best way to get PHP School Workshops running is to install Cygwin + ConEmu. Once the initial setup of these are complete, the process of installing workshops is the same
+ as Linux and Mac OSX operating systems.
+
+ After installing a workshop using the workshop manager you may find it's not available to run immediately. If this happens the simplest remedy is to make sure PHP School's workshop
+ bin directory is available in the
+ $PATH
+ environment variable. You can check this with
+ workshop-manager
+ verify which will also provide the relevant details on how to resolve the issue. To learn more about the
+ $PATH
+ environment, click
+ here
+ .
+
+
+
+ Submit your workshop
+
+ PHP School is nothing without the community so it's awesome you are considering building and submitting a workshop.
+
+
+
+
+
+
Built a workshop?
+
+ Through this form you can submit your workshop for approval, once approved your workshop will appear on the website and be installable by the workshop manager. To learn how to build a
+ workshop, head over to the
+ docs
+ or jump on to
+ slack
+ for any help!
+
+
+
What is the approval process?
+
+ We are just making sure the quality is high and there is not lots of duplicated content across the workshops. We want PHP School to lead the way in quality education material.
+
+
+ 
+
+
+ 
+
+
+ 
+
+ 
+
+
diff --git a/assets/components/Website/Docs/Sections/Reference/CheckResults.vue b/assets/components/Website/Docs/Sections/Reference/CheckResults.vue
new file mode 100644
index 00000000..f23ccd2e
--- /dev/null
+++ b/assets/components/Website/Docs/Sections/Reference/CheckResults.vue
@@ -0,0 +1,294 @@
+
+
+ 
-
-
-
-
+
+
+ 
+
+
diff --git a/assets/components/Website/Docs/Sections/Reference/EventDescription.vue b/assets/components/Website/Docs/Sections/Reference/EventDescription.vue
new file mode 100644
index 00000000..aa65fbbb
--- /dev/null
+++ b/assets/components/Website/Docs/Sections/Reference/EventDescription.vue
@@ -0,0 +1,34 @@
+
+
+
+ 
+ 
+
+ 
+
+ 
+
+
+ 
+
+ 
+
+
+ 
+
+
diff --git a/assets/components/Website/Docs/Sections/Tutorial/TutorialHome.vue b/assets/components/Website/Docs/Sections/Tutorial/TutorialHome.vue
new file mode 100644
index 00000000..0f73b035
--- /dev/null
+++ b/assets/components/Website/Docs/Sections/Tutorial/TutorialHome.vue
@@ -0,0 +1,29 @@
+
+
+ 
+ 
+
+ 
+ 
+ 
+ 
+ 
+ 
+