<commit_before>Breeze
======

Breeze is a simple and intuitive micro-framework for PHP 5.3+.  The most basic example of a Breeze application is:

``` php
<?php

require_once 'Breeze.php';

get('/', function(){
    echo 'Hello World!';
});

run();
```

Getting Started
---------------

For help installing and configuring the Breeze framework, see the INSTALL.md file.

### Basic layout

All the instructions in this tutorial will assume that you already have a basic application running.  This means that most of the examples will leave off the following required elements.

``` php
<?php

// plugins go here

require_once 'Breeze.php';

// example code goes here

run();
```

The `require_once` statement is needed to include the framework libraries and `run()` is needed to start the routing process.  Without these elements, most examples will not run.

Routes
------

The routing API involves associating HTTP requests with PHP functions.  For example, the following code would print `hello world` if a GET request were made for `/`.

``` php
<?php

get('/', function(){
    echo 'Hello World!';
});
```

The routing system works with the 4 main HTTP request methods: GET, POST, PUT, DELETE.

``` php
<?php

get('/', function(){
    echo 'you made a GET request';
});

post('/', function(){
    echo 'you made a POST request';
});

put('/', function(){
    echo 'you made a PUT request';
});

delete('/', function(){
    echo 'you made a DELETE request';
});
```

Routes are matched in the order they are declared and once a route is matched no other routes will be matched.  This means you have to be careful when organizing your routes.  For example:

``` php
<?php

get('/', function(){
    echo 'Made it here.';
});

get('/', function(){
    echo 'This will never get echoed.';
});
```

### Pattern matching

Routes can be matched using a basic string or a regular expression.  The one caveat is that regular expressions can not be delimited by `/` as they are indistinguishable from basic strings.  For example, `/my/path/is` could be a basic string or a regular expression.  The Breeze convention is to use the semicolon `;` to delimit regular expressions, but any valid delimiter will due.

``` php
<?php

get('/basic/string/match', function(){
    echo "welcome to http://www.mysite.com/basic/string/match";
});

get(';^/basic/string/\w+$;', function(){
    echo "Wow, regexp matching!";
});
```

Of course, matching regular expressions isn't too useful unless you can capture groups.  Accordingly, Breeze passes any matches from your route as the second argument to your function.

``` php
<?php

# numeric matches
get(';^/hello/(\w+)$;', function($app, $params){
    echo 'Hello ' . $params[1];
});

# named matches
get(';^/hello/(?<name>\w+)$;', function($app, $params){
    echo 'Hello ' . $params['name'];
});
```

### Matching multiple methods

In some cases, it may be helpful to associate one PHP function with multiple request methods.  We will describe a number of uses for this after some more advanced techniques have been introduced, but a simple example is detailed below.

``` php
<?php

any(array('POST','PUT'), '/', function()){
    echo 'HTML 4 and XHTML 1 forms don\'t really support the PUT method. ' .
         'This is one way to handle it.';
});

any('/', function(){
    echo 'This matches all request methods.';
})
```

### Making PUT and DELETE work

The solution described above works, but it's certainly not the most graceful or preferred solution to this problem.  A standard exists in several other frameworks where you can use a hidden form field to indicate the request method you wish to use.  This allows you to keep your controller code concise while addressing the shortcomings of HTML in the HTML.

**Template.php:**

``` html
<form method="post" action="/process_my_form">
<input type="hidden" name="_method" value="PUT" />
...
</form>
```

**Controller.php:**

``` php
<?php

put('/process_my_form', function(){
    echo 'This will be echoed when the form is submitted.';
});
```

Pass
----

Earlier we said once a route is matched no other routes are matched.  This isn't entirely true.  A mechanism exists which allows escaping from an action to continue routing.  This is helpful in a variety of situation.  One common example is to do some pre-processing for a certain set of routes.  Consider the following code:

``` php
<?php

// Show a post
get(';^/posts/(?<id>\d+)$;', function() {
    // load a post and display it
});
<commit_msg>Small typo correction in README.md<commit_after>Breeze
======

Breeze is a simple and intuitive micro-framework for PHP 5.3+.  The most basic example of a Breeze application is:

``` php
<?php

require_once 'Breeze.php';

get('/', function(){
    echo 'Hello World!';
});

run();
```

Getting Started
---------------

For help installing and configuring the Breeze framework, see the INSTALL.md file.

### Basic layout

All the instructions in this tutorial will assume that you already have a basic application running.  This means that most of the examples will leave off the following required elements.

``` php
<?php

// plugins go here

require_once 'Breeze.php';

// example code goes here

run();
```

The `require_once` statement is needed to include the framework libraries and `run()` is needed to start the routing process.  Without these elements, most examples will not run.

Routes
------

The routing API involves associating HTTP requests with PHP functions.  For example, the following code would print `hello world` if a GET request were made for `/`.

``` php
<?php

get('/', function(){
    echo 'Hello World!';
});
```

The routing system works with the 4 main HTTP request methods: GET, POST, PUT, DELETE.

``` php
<?php

get('/', function(){
    echo 'you made a GET request';
});

post('/', function(){
    echo 'you made a POST request';
});

put('/', function(){
    echo 'you made a PUT request';
});

delete('/', function(){
    echo 'you made a DELETE request';
});
```

Routes are matched in the order they are declared and once a route is matched no other routes will be matched.  This means you have to be careful when organizing your routes.  For example:

``` php
<?php

get('/', function(){
    echo 'Made it here.';
});

get('/', function(){
    echo 'This will never get echoed.';
});
```

### Pattern matching

Routes can be matched using a basic string or a regular expression.  The one caveat is that regular expressions can not be delimited by `/` as they are indistinguishable from basic strings.  For example, `/my/path/is` could be a basic string or a regular expression.  The Breeze convention is to use the semicolon `;` to delimit regular expressions, but any valid delimiter will due.

``` php
<?php

get('/basic/string/match', function(){
    echo "welcome to http://www.mysite.com/basic/string/match";
});

get(';^/basic/string/\w+$;', function(){
    echo "Wow, regexp matching!";
});
```

Of course, matching regular expressions isn't too useful unless you can capture groups.  Accordingly, Breeze passes any matches from your route as the second argument to your function.

``` php
<?php

# numeric matches
get(';^/hello/(\w+)$;', function($app, $params){
    echo 'Hello ' . $params[1];
});

# named matches
get(';^/hello/(?<name>\w+)$;', function($app, $params){
    echo 'Hello ' . $params['name'];
});
```

### Matching multiple methods

In some cases, it may be helpful to associate one PHP function with multiple request methods.  We will describe a number of uses for this after some more advanced techniques have been introduced, but a simple example is detailed below.

``` php
<?php

any(array('POST','PUT'), '/', function()){
    echo 'HTML 4 and XHTML 1 forms don\'t really support the PUT method. ' .
         'This is one way to handle it.';
});

any('/', function(){
    echo 'This matches all request methods.';
})
```

### Making PUT and DELETE work

The solution described above works, but it's certainly not the most graceful or preferred solution to this problem.  A standard exists in several other frameworks where you can use a hidden form field to indicate the request method you wish to use.  This allows you to keep your controller code concise while addressing the shortcomings of HTML in the HTML.

**Template.php:**

``` html
<form method="post" action="/process_my_form">
<input type="hidden" name="_method" value="PUT" />
...
</form>
```

**Controller.php:**

``` php
<?php

put('/process_my_form', function(){
    echo 'This will be echoed when the form is submitted.';
});
```

Pass
----

Earlier we said once a route is matched no other routes are matched.  This isn't entirely true.  A mechanism exists which allows escaping from an action to continue routing.  This is helpful in a variety of situations.  One common example is to do some pre-processing for a certain set of routes.  Consider the following code:

``` php
<?php

// Show a post
get(';^/posts/(?<id>\d+)$;', function() {
    // load a post and display it
});

{'fraction_non_alphanumeric': 0.12824783477681545, 'fraction_numerical': 0.0013324450366422385, 'mean_word_length': 3.7909574468085108, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 13, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, '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': '1232479', 'n_tokens_mistral': 2621, 'n_tokens_neox': 2468, 'n_words': 1214}