Merge pull request #108 from php-school/problem-files-common-language

Problem files common language

exercises/array-we-go/problem/problem.md

@@ -2,18 +2,17 @@ Write a program that takes an array of filepaths as arguments, filtering out fil
 
 Finally output the basename of the files, each on a new line.
 
-The full path of the files to read will be provided as the command line arguments. You do not need to make your own test files. 
+The full path of the files to read will be provided as command line arguments. You do not need to make your own test files. 
 
 ----------------------------------------------------------------------
 ## HINTS
 
-Remember the first argument will be the programs file path and not an argument passed to the program.
+Remember, the first argument will be the programs file path and not an argument passed to the program.
 
 You will be expected to make use of core array functions, `array_shift`, `array_filter` and `array_map`. 
 
 To check a file exists you will need to use `file_exists($filePath)`. This method will *return* a *boolean* `true` or `false`.
 
-Documentation on the `SplFileObject` class can be found by pointing your browser here:
-  [http://php.net/manual/en/class.splfileobject.php]()
+{{ doc 'SplFileObject' en class.splfileobject.php }}
 
 ----------------------------------------------------------------------

exercises/baby-steps/problem/problem.md

@@ -8,16 +8,24 @@ You can access command-line arguments via the global `$argv` array.
 To get started, write a program that simply contains:
 
 ```php
+<?php
 var_dump($argv);
 ```
 
+{{ cli }}
 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:
+{{ cli }}
+
+{{ cloud }}
+Run it by pressing the `Run` button in the editor.
+{{ cloud }}
+
+The output should be an array looking something like:
 
 ```php
 array(4) {
@@ -32,10 +40,15 @@ array(4) {
 }
 ```
 
-You'll need to think about how to loop through the number of arguments so you can output just their sum. 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'll need to think about how to loop through the number of arguments so you can output just their sum. The first element of the `$argv` array is always the name of your script. eg `solution.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.
 
 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.
+{{ cli }}
+{{ 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.
+{{ cli }}
 
+{{ cloud }}
+PHP school will be supplying arguments to your program when you click `Verify` in the editor. To test your program without verifying it, you can just execute it by pressing the `Run` button in the editor.
+{{ cloud }}
 ----------------------------------------------------------------------

exercises/concerned-about-separation/problem/problem.md

@@ -1,12 +1,12 @@
-This problem is the same as the previous but introduces the concept of **classes**. You will need to create two files to solve this.
+This problem is the same as the previous but introduces the concept of **classes**. You will need to create two files to solve this problem.
 
 Create a program that prints a list of files in a given directory, filtered by the extension of the files. The first argument is the directory name and the second argument is the extension filter. Print the list of files (one file per line) to the console.
 
-You must write a *class* file to do most of the work. The file must *define* a single class with a single function that takes **two** arguments: the directory name and the filename extension string in that order. The filename extension argument must be the same as what was passed to your program. Don't turn it into a regular expression or prefix with "." or do anything except pass it to your class method where you can do what you need to make your filter work.
+You must write a *class* in a file to do most of the work. The file must *define* a single class with a single function that takes **two** arguments: the directory name and the filename extension, in that order. The filename extension argument must be the same as what was passed to your program. Don't turn it into a regular expression or prefix with `.` or do anything except pass it to your class method where you can do what you need to make your filter work.
 
 You **must** not print directly to the console from your class, only from your original program.
 
-The benefit of having a contract like this is that your class can be used by anyone who expects this contract. So your class could be used by anyone else who does learnyouphp, or the verifier, and just work.
+The benefit of having a contract like this is that your class can be used by anyone who expects this contract. So your class could be used by anyone else who attempts this exercise, or the verifier, and just work.
 
 ----------------------------------------------------------------------
 ## HINTS
@@ -25,7 +25,7 @@ class DirectoryFilter
 }
 ```
 
-To use your new class in your original program file, use the `require_once` construct with the filename. So, if your file is named mymodule.php then:
+To use your new class in your original program file, use the `require_once` construct with the filename. So, if your file is named `mymodule.php` then use:
 
 ```php
 <?php
@@ -41,12 +41,7 @@ $myFilter = new DirectoryFilter;
 
 You can then call the method you defined with its required arguments.
 
-Documentation on class basics can be found here:
-
-[http://php.net/manual/en/language.oop5.basic.php]()
-
-Documentation on `require_once` can be found here:
-
-[http://php.net/manual/en/function.require-once.php]()
+* {{ doc 'class basics' en language.oop5.basic.php }}
+* {{ doc require_once en function.require-once.php }}
 
 ----------------------------------------------------------------------

exercises/database-read/problem/problem.md

@@ -4,22 +4,22 @@ Display the information of all the users in the database table `users` whose age
 
 `User: Jim Morrison Age: 27 Sex: male`
 
-Finally you will be given a random name as the second argument to your program, you should update the row in the `users` table which corresponds to this name. You should change the name to `David Attenborough`.
+Finally, you will be given a random name as the second argument to your program, you should update the row in the `users` table which corresponds to this name. You should change the name to `David Attenborough`.
 
 ----------------------------------------------------------------------
 ## HINTS
 
 This is an exercise introducing databases and PDO. PDO is a powerful abstraction library for dealing with different database vendors in a consistent manner. You can read the PDO manual here:
 
-  [http://php.net/manual/en/book.pdo.php]()
+  [http://php.net/manual/en/book.pdo.php](http://php.net/manual/en/book.pdo.php)
 
 A short introduction can be found here:
 
-  [http://www.phptherightway.com/#pdo_extension]()
+  [http://www.phptherightway.com/#pdo_extension](http://www.phptherightway.com/#pdo_extension)
 
 The most interesting class will be `\PDO`. The first parameter is the DSN string. The second and third are the username and password for the database. They are not needed for this exercise and can be left out.
 
-The `users` table is structured as follows
+The `users` table is structured as follows:
 
 ```
 +----+-----------------+-----+--------+
@@ -40,11 +40,11 @@ foreach ($pdo->query('SELECT * FROM users') as $row) {
 }
 ```
 
-`$row` is now an array of data. The key will be the columns and the value is the database value
+`$row` is now an array of data. The key will be the column name and the value is the database value.
 
 
 You should use prepared statements to perform the updating. You should be most interested in the `prepare` and `execute` methods.
 
-Remember the first argument will be the program's file path and not an argument passed to the program.
+Remember, the first argument will be the program's file path and not an argument passed to the program.
 
 ----------------------------------------------------------------------

exercises/dependency-heaven/problem/problem.md

@@ -38,8 +38,8 @@ The library works by accepting a PSR7 request and returns to you a PSR7 response
 
 There are a few other components we need, in order to use `league/route`:
 
- * **laminas/laminas-diactoros** - For the PSR7 requests and responses.
- * **laminas/laminas-httphandlerrunner** - For outputting the PSR7 response to the browser.
+ * `laminas/laminas-diactoros` - For the PSR7 requests and responses.
+ * `laminas/laminas-httphandlerrunner` - For outputting the PSR7 response to the browser.
 
 `laminas/laminas-diactoros` is a PSR7 implementation. PSR's are standards defined by the PHP-FIG, a committee of PHP projects, attempting to increase interoperability in the PHP ecosystem. PSR7 is a standard for modelling HTTP requests. We can use the `laminas/laminas-diactoros` package to marshal a PSR7 request object from the PHP super globals like so:
 
@@ -91,9 +91,15 @@ Finally, you will also be required to use `symfony/string` to manipulate the dat
 ----------------------------------------------------------------------
 ## HINTS
 
+{{ cli }}
 Point your browser to [https://getcomposer.org/doc/00-intro.md](https://getcomposer.org/doc/00-intro.md) which will walk you through **Installing Composer** if you haven't already!
 
-Use `composer init` to create your `composer.json` file with interactive search. 
+Use `composer init` to create your `composer.json` file with interactive search.
+{{ cli }}
+
+{{ cloud }}
+Composer is installed and ready to go on cloud, use the `Composer Deps` button in the editor to search for and install your dependencies. While you should read the documentation for [Composer](https://getcomposer.org/doc/00-intro.md), it's important to note that the way we manage dependencies on PHP School cloud, is not how you would manage them in your own projects. We abstract away the `composer.json` file to keep it simple. 
+{{ cloud }}
 
 For more details look at the docs for...
 

exercises/exceptional-coding/problem/problem.md

@@ -6,14 +6,13 @@ Every file should exist but under exceptional circumstances some files may not.
 Unable to open file at path '/file/path'
 ```
 
-The full path of the files to read will be provided as the command line arguments. You do not need to make your own test files. 
+The full path of the files to read will be provided as command line arguments. You do not need to make your own test files. 
 
 ----------------------------------------------------------------------
 ## HINTS
 
-You are urged to use `try... catch` logic here along with the SplFileObject contruct which throws a `RuntimeException` when a file does not exist.
+You are urged to use `try... catch` logic here along with the `SplFileObject` contruct which throws a `RuntimeException` when a file does not exist.
 
-Documentation on the `SplFileObject` class can be found by pointing your browser here:
-  [http://php.net/manual/en/class.splfileobject.php]()
+{{ doc SplFileObject en class.splfileobject.php }}
 
 ----------------------------------------------------------------------

exercises/filtered-ls/problem/problem.md

@@ -1,13 +1,15 @@
-Create a program that prints a list of files in a given directory, filtered by the extension of the files. You will be provided a directory name as the first argument to your program (e.g. '/path/to/dir/') and a file extension to filter by as the second argument.
+Create a program that prints a list of files in a given directory, filtered by the extension of the files. You will be provided a directory name as the first argument to your program (e.g. `/path/to/dir/`) and a file extension to filter by as the second argument.
 
-For example, if you get 'txt' as the second argument then you will need to filter the list to only files that **end with .txt**. Note that the second argument _will not_ come prefixed with a '.'.
+For example, if you get `txt` as the second argument then you will need to filter the list to only files that **end with .txt**. Note that the second argument _will not_ come prefixed with a full stop (`.`).
 
-The list of files should be printed to the console, one file per line.
+The list of files should be printed out, one file per line.
 
 ----------------------------------------------------------------------
 ## HINTS
 
-The `DirectoryIterator` class takes a pathname as its first argument. Using an iterator in a `foreach` loop will provide you with a `SplFileInfo` object for each file.
+The `DirectoryIterator` class takes a pathname as its first argument.
+
+Using an iterator in a `foreach` loop will provide you with a `SplFileInfo` object for each file.
 
 ```php
 <?php
@@ -16,13 +18,10 @@ foreach (new DirectoryIterator('/some/path') as $file) {
 }
 ```
 
-Documentation on the `SplFileInfo` class can be found by pointing your browser here:
-
-[http://php.net/manual/en/class.splfileinfo.php]()
+{{ doc SplFileInfo en class.splfileinfo.php }}
 
-You may also find `SplFileInfo`'s `getExtension()` method helpful
+You may also find `SplFileInfo`'s `getExtension()` method helpful.
 
-Documentation on the `getExtension()` method can be found by pointing your browser here:
-[http://php.net/manual/en/splfileinfo.getextension.php]()
+{{ doc getExtension() en splfileinfo.getextension.php }}
 
 ----------------------------------------------------------------------

exercises/hello-world/problem/problem.md

@@ -2,13 +2,24 @@ Write a program that prints the text "Hello World" to the console (stdout).
 
 ----------------------------------------------------------------------
 ## HINTS
-
+{{ cli }}
 To make a PHP program, create a new file with a `.php` extension and start writing PHP! Execute your program by running it with the
 `php` command. e.g.:
 
 ```sh
 $ php program.php
 ```
+{{ cli }}
+
+{{ cloud }}
+
+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. 
+
+{{ cloud }}
 
 You can write to the console from a PHP program with the following code:
 
@@ -17,9 +28,11 @@ You can write to the console from a PHP program with the following code:
 echo "text";
 ```
 
-The first line tells the PHP to interpret the code following it. It is required before any PHP code is written. Read more here: [http://php.net/manual/en/language.basic-syntax.phptags.php]()
-The second line is the instruction to print out some text.
+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.
+
+{{ doc 'PHP tags' en language.basic-syntax.phptags.php }}
 
+{{ cli }}
 Place the code in to a text file using your favourite text editor, some popular editors are listed below:
 
 * Sublime Text: [https://www.sublimetext.com/]()
@@ -30,19 +43,32 @@ Switch back to the terminal and run your code again with the same command as abo
 ```sh
 $ php program.php
 ```
+{{ cli }}
+
+{{ cloud }}
+Try pressing the `Run` button in the bottom right corner to execute your program.
+{{ cloud }}
 
 You should see the word "text" printed out on the console.
 
-Now you must adapt the code to pass the challenge presented. Remember the challenge was: Write a program that prints the text "Hello World" to the console (stdout).
+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.
 
+{{ cli }}
 We have created you a file named `hello-world.php` in your current working directory, feel free to use it!
+{{ cli }}
 
-When you have finished and saved the file you must run the following (substituting program.php to the name of the file you created which contains your code)
+{{ cli }}
+When you have finished editing your program and saved the file you must run the following (substituting program.php to the name of the file you created which contains your code)
 
 ```sh
 $ {appname} verify program.php
 ```
+{{ cli }}
+
+{{ cloud }}
+When you have finished editing your program you must verify it. Click the `Verify` button in the bottom right corner.
+{{ cloud }}
 
-to proceed. Your program will be tested, a report will be generated, and the lesson will be marked 'completed' if you are successful.
+Your program will be tested, a report will be generated, and the lesson will be marked 'completed' if you are successful.
 
 ----------------------------------------------------------------------