<commit_before>Writing controllers
===================

In this document, we will see how to create a controller.
You will also learn more about what makes a controller.

Note: if you are using *Mouf*, Splash comes with a [controller creation wizard (a nice user interface)](writing_controllers.md).

What is a controller?
---------------------

In Splash, a controller is a class that contains a number of _Actions_.
_Actions_ are methods that can be directly accessed from the browser.

There are several ways to declare a method to be an action. The most common ways are:
 - The *@URL* annotation
 - The *@Action* annotation


The @URL annotation
-------------------

This is the preferred way of declaring an action:

```php
<?php
namespace Test\Controllers;

use Mouf\Mvc\Splash\Annotations\URL;

class MyController {
    
    /**
     * My first action.
     *
     * @URL("/path/to/my/action")
     * @param string $var1
     * @param string $var2
     */
    public function myUrl($var1, $var2) {
        $str = "<html><head></head>";
        $str .= "<body>";
        $str .= "var1 value is ".htmlentities($var1)." and var2 value is ".htmlentities($var2);
        $str .= "</body>";
        return new HtmlResponse($str);
    }
}
```

Note: this class must be auto-loadable by Composer. Be sure to put the class in the correct repository according to your *composer.json* `autoload` section.

First thing you can see: the `MyController` class extends the `Controller` class provided by Splash.

The *@URL* annotation points to the web path the action is bound to.

The action takes 2 parameters: `$var1` and `$var2`. This means that the page needs both parameters passed
either in GET or POST.

In order to test this, we must first create an instance of the controller in your container.
How you do this really depends on the container you are using. See the [installation section for more information](install/index.md).

Finally, we must also register this controller in Splash. How this is done essentially depends on your Splash installation.

 - if you are using Mouf, you have nothing to do. Splash will automatically detect your controllers.
 - if you are using Splash service provider, you need to put in your container an entry named 'thecodingmachine.splash.controllers' that is an array of controller identifiers.
   The way to do this depends on the container you are using, but might be something similar to:
    ```php
    $container->set('thecodingmachine.splash.controllers', [
       'myController',
       'myOtherController',
    ]);
    ```

Now, let's test our code.
By browsing to `http://localhost/{my_app}/path/to/my/action?var1=42&var2=24`, we should see the message displayed!

*Troubleshooting:* If for some reason, your controller is not detected, you can try to purge your cache.

Done? Then let's move on! 
 
The @Get / @Post annotations
----------------------------<commit_msg>Fixing documentation<commit_after>Writing controllers
===================

In this document, we will see how to create a controller.
You will also learn more about what makes a controller.

Note: if you are using *Mouf*, Splash comes with a [controller creation wizard (a nice user interface)](writing_controllers.md).

What is a controller?
---------------------

In Splash, a controller is a class that contains a number of _Actions_.
_Actions_ are methods that can be directly accessed from the browser.

There are several ways to declare a method to be an action. The most common ways are:
 - The *@URL* annotation
 - The *@Action* annotation


The @URL annotation
-------------------

This is the preferred way of declaring an action:

```php
<?php
namespace Test\Controllers;

use Mouf\Mvc\Splash\Annotations\URL;

class MyController {
    
    /**
     * My first action.
     *
     * @URL("/path/to/my/action")
     * @param string $var1
     * @param string $var2
     */
    public function myUrl($var1, $var2) {
        $str = "<html><head></head>";
        $str .= "<body>";
        $str .= "var1 value is ".htmlentities($var1)." and var2 value is ".htmlentities($var2);
        $str .= "</body>";
        return new HtmlResponse($str);
    }
}
```

Note: this class must be auto-loadable by Composer. Be sure to put the class in the correct repository according to your *composer.json* `autoload` section.


The *@URL* annotation points to the web path the action is bound to.

The action takes 2 parameters: `$var1` and `$var2`. This means that the page needs both parameters passed
either in GET or POST.

In order to test this, we must first create an instance of the controller in your container.
How you do this really depends on the container you are using. See the [installation section for more information](install/index.md).

Finally, we must also register this controller in Splash. How this is done essentially depends on your Splash installation.

 - if you are using Mouf, you have nothing to do. Splash will automatically detect your controllers.
 - if you are using Splash service provider, you need to put in your container an entry named 'thecodingmachine.splash.controllers' that is an array of controller identifiers.
   The way to do this depends on the container you are using, but might be something similar to:
    
    ```php
    $container->set('thecodingmachine.splash.controllers', [
       'myController',
       'myOtherController',
    ]);
    ```

Now, let's test our code.
By browsing to `http://localhost/{my_app}/path/to/my/action?var1=42&var2=24`, we should see the message displayed!

*Troubleshooting:* If for some reason, your controller is not detected, you can try to purge your cache.

Done? Then let's move on! 
 
The @Get / @Post annotations
----------------------------
{'fraction_non_alphanumeric': 0.11418624891209747, 'fraction_numerical': 0.005918189730200174, 'mean_word_length': 3.2281089036055923, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1668849', 'n_tokens_mistral': 1606, 'n_tokens_neox': 1531, 'n_words': 740}