Skip to content

Commit 2235dfd

Browse files
authored
Overhaul basic-syntax and lasagna (#607)
Improve documentation. Simplify the exercise with functions boilerplate.
1 parent dc65c9f commit 2235dfd

File tree

10 files changed

+427
-178
lines changed

10 files changed

+427
-178
lines changed
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"blurb": "`basic syntax` concept in PHP",
2+
"blurb": "Structure and basic syntax of programs in PHP",
33
"authors": ["neenjaw"],
4-
"contributors": []
4+
"contributors": ["mk-mxp"]
55
}

concepts/basic-syntax/about.md

Lines changed: 158 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,146 @@
11
# Basics
22

3+
## General syntax
4+
5+
PHP is an interpreted language, meaning it executes the code you write directly.
6+
PHP code files are text files that contain a PHP opening tag `<?php` to mark the start of PHP code.
7+
If the file contains only PHP code, it is possible to omit the closing tag `?>` which is used to mark the end of PHP code.
8+
See [PHP tag docs][php-tag] to learn more about the PHP tag.
9+
10+
```php
11+
<?php
12+
13+
// All PHP code goes here
14+
15+
// No closing tag required at the end
16+
```
17+
18+
For easier reading, all code examples omit the PHP opening tag `<?php`.
19+
But we have it in all PHP exercises, so you don't have to add it yourself.
20+
21+
All statements, like assignments or function calls, must end with a `;` for instruction separation.
22+
Omitting `;` (like in JavaScript) is not allowed and results in syntax errors.
23+
Learn more about [instruction separation][php-semicolon] from the PHP documentation.
24+
25+
```php
26+
$message = "Success!"; // Statement correctly ends with `;`
27+
$message = "I know JavaScript." // PHP Parse error: syntax error, [...]
28+
```
29+
330
## Values and Variables
431

5-
PHP is a general-purpose dynamically-typed programming language.
32+
PHP is a dynamically-typed programming language.
633
Value types are only checked while the program is running.
734
Using the assignment `=` operator, any value type may be assigned to any variable name.
835
Variable names must start with a dollar `$` sign.
36+
To dig deeper into variables, see [PHP variable docs][php-variables].
937

1038
```php
11-
<?php
12-
$count = 1 // Assigned an integer value of 1
13-
$count = 2 // Re-assigned a new value to the variable
39+
$count = 1; // Assign an integer value of 1
40+
$count = 2; // Re-assign a new value to the variable
1441

15-
$count = false // You may assign any value type
42+
$count = false; // You may assign any value type
1643

1744
// Strings can be created by enclosing the characters
1845
// within single `'` quotes or double `"` quotes.
19-
$message = "Success!"
46+
$message = "Success!";
2047
```
2148

49+
## Functions and Methods
50+
51+
Literal values and values stored in variables can be passed to functions.
52+
New variables are created when defining function arguments to hold values passed in.
53+
54+
```php
55+
// Declare the window_width function
56+
function window_width($width)
57+
{
58+
echo $width; // Access the value passed into the function as $width
59+
// ...
60+
}
61+
62+
window_width(100); // Call the function with the literal value 100
63+
64+
$newWidth = 100;
65+
window_width($newWidth); // Call the function with the value stored in $newWidth
66+
```
67+
68+
Functions may return values using the keyword `return`.
69+
Values to return can be literals, stored in variables, or the result of an instruction.
70+
71+
```php
72+
function window_height()
73+
{
74+
$heightOffset = 10;
75+
76+
return 100 + $heightOffset;
77+
}
78+
```
79+
80+
Functions inside classes and their instances are called methods.
81+
To call a method, the name is preceeded by the instance and `->`.
82+
A class instance is created by the `new` operation.
83+
Methods have access to the special variable `$this`, which refers to the current instance.
84+
85+
```php
86+
<?php
87+
// Calculator.php
88+
89+
class Calculator {
90+
// ...
91+
92+
public function sub($x, $y)
93+
{
94+
return $this->add($x, -$y); // Calls the method add() of the current instance
95+
}
96+
97+
public function add($x, $y)
98+
{
99+
return $x + $y;
100+
}
101+
}
102+
103+
$calculator = new Calculator(); // Creates a new instance of Calculator class
104+
$calculator->sub(3, 1); // Calls the method sub() of the instance stored in $calculator
105+
// => 2
106+
```
107+
108+
We will dig deeper into functions and classes in later exercises.
109+
110+
## Simple debugging
111+
112+
As a basic form of debugging, printing values and contents of variables helps with understanding what happens.
113+
PHP can print values using:
114+
115+
- `echo $variable;` to output a string representation of the value
116+
- `print $variable;`, which is the same as `echo $variable;`
117+
- `var_dump($variable);` to get more insight into the value, e.g. the type PHP sees
118+
119+
When using `echo` or `print`: Empty strings, `false` and `null` will not show up.
120+
And classes and instances will make them error out.
121+
Use `var_dump()` to see these.
122+
123+
In the online editor, the output you produce is shown with the test results.
124+
When you are using the CLI, the output appears mixed with the progress indicator before test summary.
125+
22126
## Code organization
23127

24-
PHP code files are text files that start with `<?php`.
25-
If the file contains only php code, there is no closing `?>` tag.
26-
Code, functions, and classes may all be present in a single file, but usually classes are in their own file with a filename which matches the class.
128+
Files are basic units of code organisation in PHP and many other languages.
129+
For showing the name of the file to look at in a code block, we use a comment.
130+
You never have to add such comments to your files:
27131

28132
```php
29133
<?php
30-
// index.php
134+
// NameOfPhpFile.php
31135

32-
$sum = add(1, 2);
136+
[...]
33137
```
34138

139+
Code, functions, and classes may all be present in a single file.
140+
But usually these kinds of code units are in separate files.
141+
142+
It is common practice to have one class per file with a filename which matches the class.
143+
35144
```php
36145
<?php
37146
// Calculator.php
@@ -46,23 +155,56 @@ class Calculator {
46155
}
47156
```
48157

158+
Functions usually are grouped together in files describing their common theme.
159+
160+
```php
161+
<?php
162+
// window_handling.php
163+
164+
function window_paint()
165+
{
166+
// ...
167+
}
168+
169+
function window_size($width, $height)
170+
{
171+
// ...
172+
}
173+
174+
function window_move($x, $y)
175+
{
176+
// ...
177+
}
178+
```
179+
180+
And often there are files containing statements for direct execution, like an `index.php` that is commonly used as the entrypoint of a web application.
181+
182+
```php
183+
<?php
184+
// index.php
185+
186+
$sum = add(1, 2);
187+
// ...
188+
```
189+
49190
## Naming conventions
50191

51192
Classnames should all be `PascalCase`.
52-
Depending on the style standard; variables, functions, method names may be either `camelCase` or `snake_case`.
193+
Depending on the style standard; variables, functions, and method names may be either `camelCase` or `snake_case`.
53194
Names may contain letters `a-zA-Z`, numbers `0-9`, and underscores `_` but they cannot start with a number.
54195

55196
## Comments
56197

57-
Single line comments start with `//`, and a block of text can be wrapped with `/*` and `*/` to become a comment.
198+
Single-line comments start with `//`, and a block of text can be wrapped with `/*` and `*/` to become a multi-line comment.
58199

59200
```php
60-
<?php
61-
62-
// Single line comment
201+
// Single-line comment
63202

64203
/*
65204
Multi-line comment
66205
*/
67206
```
68207

208+
[php-tag]: https://www.php.net/manual/en/language.basic-syntax.phptags.php
209+
[php-semicolon]: https://www.php.net/manual/en/language.basic-syntax.instruction-separation.php
210+
[php-variables]: https://www.php.net/manual/en/language.variables.basics.php

concepts/basic-syntax/introduction.md

Lines changed: 51 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,81 @@
11
# Basics
22

3-
## Values and Variables
3+
For more detailed information about these topics visit the [concept page][exercism-concept].
4+
5+
## General syntax
46

5-
PHP is a general-purpose dynamically-typed programming language.
6-
Value types are only checked while the program is running.
7-
Using the assignment `=` operator, any value type may be assigned to any variable name.
8-
Variable names must start with a dollar `$` sign.
7+
The PHP opening tag `<?php` marks the start of PHP code.
8+
All statements must end with a `;` for instruction separation.
99

1010
```php
1111
<?php
12-
$count = 1 // Assigned an integer value of 1
13-
$count = 2 // Re-assigned a new value to the variable
1412

15-
$count = false // You may assign any value type
13+
$message = "Success!"; // Statement correctly ends with `;`
14+
$message = "I fail." // PHP Parse error: syntax error, [...]
15+
```
16+
17+
For easier reading, all code examples omit the PHP opening tag `<?php`.
18+
19+
## Comments
20+
21+
Single line comments start with `//`.
22+
23+
```php
24+
// Single line comment
25+
```
26+
27+
## Values and Variables
28+
29+
Using the assignment `=` operator, a value may be assigned to a variable.
30+
Variable names must start with a dollar `$` sign and follow the [naming conventions][exercism-concept-naming-conventions].
31+
32+
```php
33+
$count = 1; // Assign value of 1
1634

1735
// Strings can be created by enclosing the characters
1836
// within single `'` quotes or double `"` quotes.
19-
$message = "Success!"
37+
$message = "Success!";
2038
```
2139

22-
## Code organization
40+
## Functions and Methods
2341

24-
PHP code files are text files that start with `<?php`.
25-
If the file contains only php code, there is no closing `?>` tag.
26-
Code, functions, and classes may all be present in a single file, but usually classes are in their own file with a filename which matches the class.
42+
Values and variables can be passed to functions.
43+
Function arguments become new variables to hold values passed in.
44+
Functions may return any value using the keyword `return`.
2745

2846
```php
29-
<?php
30-
// index.php
47+
function window_height($height)
48+
{
49+
return $height + 10;
50+
}
3151

32-
$sum = add(1, 2);
52+
window_height(100);
53+
// => 110
3354
```
3455

56+
Functions inside classes and their instances are called methods.
57+
To call a method, the name is preceeded by the instance and `->`.
58+
Methods have access to the special variable `$this`, which refers to the current instance.
59+
3560
```php
3661
<?php
37-
// Calculator.php
3862

3963
class Calculator {
40-
// ...
64+
public function sub($x, $y)
65+
{
66+
return $this->add($x, -$y); // Calls the method add() of the current instance
67+
}
4168

42-
function add($x, $y)
69+
public function add($x, $y)
4370
{
4471
return $x + $y;
4572
}
4673
}
47-
```
48-
49-
## Naming conventions
50-
51-
Classnames should all be `PascalCase`.
52-
Depending on the style standard; variables, functions, method names may be either `camelCase` or `snake_case`.
53-
Names may contain letters `a-zA-Z`, numbers `0-9`, and underscores `_` but they cannot start with a number.
54-
55-
## Comments
56-
57-
Single line comments start with `//`, and a block of text can be wrapped with `/*` and `*/` to become a comment.
58-
59-
```php
60-
<?php
61-
62-
// Single line comment
6374

64-
/*
65-
Multi-line comment
66-
*/
75+
$calculator = new Calculator(); // Creates a new instance of Calculator class
76+
$calculator->sub(3, 1); // Calls the method sub() of the instance stored in $calculator
77+
// => 2
6778
```
6879

80+
[exercism-concept]: /tracks/php/concepts/basic-syntax
81+
[exercism-concept-naming-conventions]: /tracks/php/concepts/basic-syntax#h-naming-conventions

config.json

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -936,6 +936,11 @@
936936
]
937937
},
938938
"concepts": [
939+
{
940+
"name": "Basics",
941+
"slug": "basic-syntax",
942+
"uuid": "1cf9fb39-5520-4c93-ba7a-7162586e2955"
943+
},
939944
{
940945
"name": "Variable Scope",
941946
"slug": "variable-scope",
@@ -1011,11 +1016,6 @@
10111016
"slug": "null-values",
10121017
"uuid": "ed4c9916-e8ae-473c-b6f2-29c93357faf7"
10131018
},
1014-
{
1015-
"name": "Basics",
1016-
"slug": "basic-syntax",
1017-
"uuid": "1cf9fb39-5520-4c93-ba7a-7162586e2955"
1018-
},
10191019
{
10201020
"name": "Classes",
10211021
"slug": "class-basics",

0 commit comments

Comments
 (0)