Building Web App

Welcome to the guide on how to build web app using PHPy 2 framework.

Setup PHP & Nginx

It's recommended to use PHP & Nginx for serving apps based on PHPy. Install latest stable versions:

Creating PHPy app

Clone PHPy:

Create empty folder for the new app:

Init new app:

This will generate app structure and show Nginx config to use for the app:

server {
  root /var/www/my-app/web;
  index index.php;

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

  location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php-fpm.sock;
  }
}

Make sure fastcgi_pass points to your fpm socket and add to Nginx (reload configs with nginx -s reload).

Point browser to http://localhost (or other host configured, like localhost:88 in our case) and check if you see the following:

Layout & default action

You'll find following files under my-app folder:

web/             # images, styles and other public resources goes here
   /index.php    # entry point to process all app requests

app/             # our app is implemented here 
   /layout.php   # global HTML layout (actions are rendered inside)
   /default.php  # default action (for "/" requests) to process and render

Layout

Global app/layout.php file is used to render common app elements and resources (that appear on all pages). Let's edit it:

As you can see, there's a phpy() function call. What is does, is executes and renders nested action based on request URI.

Default action

When we call root / path of our app, default.php action is being called and rendered (inside layout.php). We'll edit it a little:

Now let's check how it all looks in the browser:

Creating & nesting actions

Request URIs are automatically mapped to actions. E.g. in order to process /test URI, we should create app/test.php action:

Now let's look what http://localhost/test shows:

We can put actions into folders. E.g. creating app/docs/article.php will handle http://localhost/docs/article requests. Infinite level of folding is allowed.

We can also create default.php file under folders, which will be executed when URI is the same as folder path. E.g. let's create app/my/default.php action:

Navigate our browser to http://localhost/my to see the following:

Nesting

We can nest actions to keep files small, which is highly recommended. E.g. let's add app/my/menu.php action:

In order to nest this action into my/default.php action we need to use phpy() function with an action we want to nest:

Navigate our browser to http://localhost/my to see how nesting works:

We can pass variables to nested actions as a second phpy() argument:

Infinite level of nesting is allowed.

Client-side actions & handlers

PHPy comes with Javascript layer to manipulate actions on the client side. Button elements are recommended to be used to trigger actions. Let's add a button to default.php action:

Now /time action will be called once button is clicked:

Let's create time.php action to render something in return once button is clicked:

PHPy will automatically find DOM element with id=time and place action rendered output to it:

Any number of DOM elements can be updated from single action:

Custom Javascript handlers

We can call custom Javascript functions as well. Let's add one more button that calls hi() function:

The Javascript hi() function itself can be defined anywhere, but it's recommended to place relevant JS implementations under separate JS files for each action. That's why we create app/default.js with the following code:

By default, all JS files are automatically collected and loaded to app, so we don't have to do anything else before checking browser:

Forms

Forms are handled by PHPy in the same manner as buttons. We just declare form and specify endpoint action to process submitted data. Let's create a form in /my/default.php action

This form will be submitted to /my/submit action. We have also created empty #result element which we'll use to render response from action. Let's declare /my/submit.php action:

After we fill form field and click "Go" button, we can see result rendered by server:

CSS

CSS is also automatically collected and loaded. It is recommended to put action-related styles into separate files and have global styles in layout.css file:

app/
   /layout.css  # General CSS styles
   ...
   /action.php  # PHP action implementation
   /action.js   # Javascript client-side handlers/listeners/...
   /action.css  # CSS styles for this action

Let's add some styling to our lauout.css file:

Now everything feels a bit better:

Custom routing

If we need to process specific endpoint in a highly custom way, we can do that using phpy::on() in web/index.php file:

This callback function will be executed once http://localhost/test URI is called:

curl http://localhost/test
Custom response!!!

If callback returns true then standard flow will be executed after function is finished:

We can use regular expressions as well as stack multiple handlers:

Sessions & authentication

Session are not started automatically, so we need to add session_start() to web/index.php if you plan you use sessions:

Now standard PHP session becomes accessible in any part of the app:

Authentication

User specific areas access control can be easily implemented using sessions and custom routing handlers:

This will allow access to all /my* endpoints only for users with declared $_SESSION['user_id'] variable (which should obviously be set within while processing signin form).