add documentation

public/index.php

@@ -24,13 +24,13 @@ function get_base_path() {
 }
 
 $basePath = get_base_path();
-$pdo = new Connexion(get_database());
+$con = new Connexion(get_database());
 
 // routes initialization
 $router = new AltoRouter();
 $router->setBasePath($basePath);
 
-$sampleFormController = new SampleFormController(new FormResultGateway($pdo));
+$sampleFormController = new SampleFormController(new FormResultGateway($con));
 $router->map("GET", "/", fn() => $sampleFormController->displayForm());
 $router->map("POST", "/submit", fn() => $sampleFormController->submitForm($_POST));
 

sql/database.php

@@ -1,7 +1,10 @@
 <?php
 
-function get_database()
-{
+/**
+ * @return PDO The PDO instance of the configuration's database connexion.
+ */
+function get_database(): PDO {
+    // defined by profiles.
     global $data_source_name;
     // The presence of the .guard file says that the database has already been initialized.
     $database_exists = file_exists(__DIR__ . "/.guard");
@@ -25,6 +28,8 @@ function get_database()
 
     //FIXME Server will need to explicitly set permissions to the `sql` folder
     // in order for the touch to work
+    //
+    // Workaround in CI by setting permissions to 777 to the folder
     touch(__DIR__ . "/.guard");
 
     return $pdo;

src/Connexion.php

@@ -15,6 +15,12 @@ class Connexion {
         $this->pdo = $pdo;
     }
 
+    /**
+     * execute a request
+     * @param string $query
+     * @param array $args
+     * @return void
+     */
     public function exec(string $query, array $args) {
         $stmnt = $this->pdo->prepare($query);
         foreach ($args as $name => $value) {
@@ -23,6 +29,12 @@ class Connexion {
         $stmnt->execute();
     }
 
+    /**
+     * Execute a request, and return the returned rows
+     * @param string $query the SQL request
+     * @param array $args an array containing the arguments label, value and type: ex: `[":label" => [$value, PDO::PARAM_TYPE]`
+     * @return array the returned rows of the request
+     */
     public function fetch(string $query, array $args): array {
         $stmnt = $this->pdo->prepare($query);
         foreach ($args as $name => $value) {