Getting Started

Installation

WaterPipe is a composer package, so the easiest way to add it to your project is:

composer require elementaryframework/water-pipe

Once installed, you can access WaterPipe classes through the namespace \ElementaryFramework\WaterPipe

Your first pipe 🎉

WaterPipe helps you create endpoints for your app in an easy declarative manner, with a set of methods from the WaterPipe class:

• get(string $uri, callable $action): Used to create a GET request endpoint at the given $uri.
• post(string $uri, callable $action): Used to create a POST request endpoint at the given $uri.
• put(string $uri, callable $action): Used to create a PUT request endpoint at the given $uri.
• delete(string $uri, callable $action): Used to create a DELETE request endpoint at the given $uri.
• patch(string $uri, callable $action): Used to create a PATCH request endpoint at the given $uri.
• head(string $uri, callable $action): Used to create a HEAD request endpoint at the given $uri.
• options(string $uri, callable $action): Used to create a OPTIONS request endpoint at the given $uri.

All callable actions are functions/class methods/closures which have exactly two (02) parameters, the Request and the Response.

An example of simple web app using WaterPipe for URL routing can be:

<?php

use ElementaryFramework\WaterPipe\WaterPipe;

use ElementaryFramework\WaterPipe\HTTP\Request\Request;

use ElementaryFramework\WaterPipe\HTTP\Response\Response;
use ElementaryFramework\WaterPipe\HTTP\Response\ResponseStatus;
use ElementaryFramework\WaterPipe\HTTP\Response\ResponseHeader;

// Create the root pipe
$root = new WaterPipe;

// Add a new endpoint to the pipe with HTTP GET method (the home page)
$root->get("/", function (Request $req, Response $res) {
    $res->sendHtml("<b>Welcome to my web app !</b> <a href=\"/login\">Click here to login</a>");
});

// Add a new endpoint to the pipe with HTTP GET method (the login page)
$root->get("/login", function (Request $req, Response $res) {
    $res->sendFile("./pages/login.html", ResponseStatus::OkCode);
});

// Add a new endpoint to the pipe with HTTP POST method (the login page form validation)
// NOTE that the endpoint path is the same than the previous, only the HTTP method differ!
$root->post("/login", function (Request $req, Response $res) {
    // Get $_POST values
    $body = $req->getBody();
    $username = $body["username"];
    $password = $body["password"];

    if (validate_username($username) && validate_password($password)) {
        // Checks if the client access this route with an AJAX request
        if ($req->isAjax()) {
            $res->sendJson(array(
                "success" => true
            ));
        } else {
            // Redirect the user to the members page
            $res->redirect("/members/{$username}");
        }
    } else {
        // Checks if the client access this route with an AJAX request
        if ($req->isAjax()) {
            $res->sendJson(array(
                "success" => false
            ));
        } else {
            // Redirect the user to the members page
            $res->redirect("/login");
        }
    }
});

// Add a new endpoint to the pipe with HTTP GET method (the member's dashboard page)
$root->get("/members/:username", function (Request $req, Response $res) {
    $res->sendHtml("Welcome to your dashboard <b>{$req->uri['username']}</b> !");
});

// Finally... Run the pipe
$root->run();

// Nothing will be executed after a call of WaterPipe->run();

Deploy it!

Since when used, WaterPipe handle all your incoming requests, it's important to configure your HTTP server to redirect all (or some of) your incoming requests to the root pipe of your project (in this case, index.php).

Apache

For Apache, you have to edit the .htaccess file located in the root of your app, and add these lines:

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

This will send all requests to the index.php file (you can replace it with any other file which contains your root pipe).

NGiNX

Configure NGiNX is pretty easy, you just have to add (or update) the location / command of your server block. It have to look like:

location / {
    try_files $uri $uri/ /index.php?$args;
}

This will say to NGiNX to redirect all non existing paths to the index.php file (you can replace it with any other file which contains your root pipe).

If you want to redirect all paths without distinction, you have to do:

location / {
    try_files $uri /index.php?$args;
}

What next ?

Read the advanced guide to go further with WaterPipe.