Docs Wvm Logics

Window Logics

Logics are patterns that are designed to filter and resolve or authenticate urls. This filtering and authentication process are categorized into top level and low level logics. The top level logics are handled internally and automatically by the framework based on initial configuration while the low level logics are url validations that are handled through the use of shutter methods. In spoova, urls are categorized into three divisions or entry points which are the root, path and base entry points.

Top Level Logics
Top level logics are subcategorized into basic, index and standard logics. Each of these logics depending on the preferred logic, defines the main or root controller file that will be responsible for managing routes. The root controller file can be a single top level controller file or multiple top level controller files that are used to manage their relative subroutes.

Basic Logic
The basic logic involves the use of a single super controller file to handle routes. Under this logic, whenever any url is visited, the route management structure transfers that url to a specified super controller file which determines how all urls are resolved. Without that super controller file, no urls will be able to resolve. In order to use this method, the index.php file at the root of the project application must be configured to use the super controller name. This is done by supplying the super controller name in the Server::run() method. An example is shown below:
index.php
  <?php

  include 'icore/filebase.php';

  ↪ Server::run('basic');

Once this is done, then the application will assume that a windows/Routes/Basic.php file controls the entire application. The namespace is generated from the supplied super controller's file name (i.e basic). If the file (i.e class) exists within the predefined path, then the class will take the full ownership and control of how urls run. This means that every url will first land on that windows/Routes/Basic.php file which will then determine how such url is handled. In this manner, the Basic file is the sole distributor and manager of all urls. Without it, pages will not be able to load.

Index Logic
Index logic is built upon the basic logic. In this logic, the windows\Routes\Index namespaced class takes the full ownership and control of how urls are handled. When an index page (e.g http://host_name/ or http://host_name/index) is visited, the namespaced index class will resolve the index page by calling its root() method. However when other urls whose entry names are not index are called, then spoova will try to resolve the urls by looking for a file with the root name within the windows/Routes directory. If the file does not exist, then spoova will return a 404 error page. The structure below is an example of how to set up an index logic.
index.php
  <?php

  include 'icore/filebase.php';

  ↪ Server::run('index');

windows/Routes/Index.php
  <?php

  namespace spoova\mi\windows\Routes;
  
  use Window;

  class Index extends Window {

    function __construct(){

      if(self::isIndex($this)){
      
         self::call($this, [
    
            window('root') => 'index', //call index method for only index pages
            
         ]);

      } else {

         //call other pages using the currently visited url's root name as the route controller class name
         //if route controller class name does not exist, close and return 404 response.
         if(!self::callRoute(window('root'))) self::close();

      } 
    
      function index() {

         //this method is only called for index page

      }

    }

  }

In the code above, by setting the index.php file to Server::run('index'), the application will try to call the windows\Routes\Index.php. If the file exists and the currently requested url is an index page, the windows\Routes\Index.phpfile will in turn call its index() method using the shutter method call(). However, if a different url is called whose entry point name is not "index", rather than call the index() method, the management structure will check if the route file exists first within the windows\Routes directory and try to use the class to resolve the url. The self::callRoute() method ensures that the window tries to load every page using a class entry window name that exists within the windows\Routes directory. If the url handler or window router file does not exist, then a 404 reponse is returned through the self::close() method. To further explain this, let's take a look at two sample urls below: 

  http://localhost/app/home window('root') => home
  http://somesite.com/home  window('root') => home
In the two sample urls above, spoova internally determines the url's entry point as "home". The self::callRoute() will try to see if the Home route class exists in the windows/Routes directly and automatically load it. If the file does not exist, it will return a false value which will trigger the self::close() method that returns a 404 error page. Assuming we have a localhost url http://localhost/app/home, then the window('root') of that url will be "home". In any given url, the root entry name returned by window('root') or window(':') is always the name that comes after the domain url. In localhost, it is the path name that comes after the project folder name. In the first url sample above, the project folder name is app, hence the window root is "home". However, in the second url since somesite.com will most likely be the domain url, then the first path that follows becomes the window root. If there is no path found after these urls, this will be assumed as the index page.


Standard Logic
Unlike other logics, standard logic suggests that all urls must have a window entry point corresponsing to a server or route entry file that takes ownership of its relative sub-urls. When a url is visited, standard logic will split the url into divisions to obtain an entry point name. The entry point name of that url must have a correspoing controller class that determines how the url is loaded. This means that a url http://localhost/app/home and http://localhost/app/home/user/... for example, will be handled by a route file "Home" where http://localhost/app is assumed to be the parent domain part of the localhost url. This Home file must be an extension of Window class within the windows/Routes directory and it will determine how its relative sub-paths are resolved. If the required route file does not exist, then a 404 error page is returned. Futher explanation is given on window entry point here. In order to define a standard logic, the Server::run() code in root config file index.php must have no arguments.
index.php
  Server::run(); // use standard logic

windows/Routes/Index.php
  <?php
  
  namespace spoova\mi\windows\Routes;
  
  use Window;

  class Index extends Window {

    function __construct(){

        self::call($this, [

            window(':') => 'root',
            window(':user') => 'user_method',
        
        ]);

    }

    function root() {

        //call this on index page

    }

    function user_method() {

        //call this on index/user page

    }

  }

In the code above, note that window(':') will return a requested (or current) url's entry point name. Since, Index is the entry server file, then, index will be returned. Also, window(':user') will return index/user. Since call() is a direct shutter method, if the method user_method() does not exist when the http://domain/index/user, page is visited, then a 404 error will be returned. Once a method is defined, developer is left to handle how to close such urls. Any of a window's method can use the shutter methods.

Low Level Logics
Low level logics are designed to validate and authenticate urls through the use of shutter methods. Once a url validation is done, a relative method or a class supplied will be executed. However, if the route url validation fails, then a 404 error page is returned. The route validations are done through url entry points divisions. This divisions makes it easier to manage urls better based on desired requirements. The sample below best explains how urls are subdivided or categorized for proper validation.

Window url entry points

    

      Type 
      Url sample 
      root 
      path 
      base
    

    

      local 
      http://localhost/myapp/users/some/path 
      users 
      some/path 
      users/some/path
    

    

      remote 
      http://site.com/users/some/path 
      users 
      some/path 
      users/some/path
In the sample above, the first url is a local url (i.e localhost). The name that usually follow a localhost url is the project folder name. Spoova takes note of this and properly adjusts the url divisions to start after the project folder name "myapp". However, when it comes to remote live domain urls, the url divisions starts immediately after the domain name site.com because it is assumed that site.com is equivalent to localhost/myapp. For this reason, both localhost/myapp and site.com will be given an alias of {domain}. Using this alias, we can generalize the urls above in a new way below:
Window url entry points

    

      Url sample 
      root 
      path 
      base
    

    

      http://{domain}/users/some/path 
      users 
      some/path 
      users/some/path
    

  
 
  :where {domain} = "localhost/myapp" or "site.com"
Using the sample above as reference, we can go on to understand the three subdivisions of any url.
url:root
The root part of any url is the first name that follows the {domain} path of any url. From the sample above, this is equivalent to "users". Hence, the "users" is the root division of the sample url. This division is the main entry point to any url and it is sometimes referred to be the Window or entry point of any url. This is because this root part is the main controller of how urls are resolved. In standard logic, the url root entry point is used mainly for top level controller files.

url:path
The path section (or part) of any url is the entire path that follows the root section of any url. From the sample above, this is equivalent to "some/path".

url:base
The base section of any given url refers to the entire path that follows the {domain} section. In simple terms, this is the conjuction of the root and the path divisions of any url. From the sample above, the base division is equivalent to "users/some/path".
The url samples below provides a better understanding of how the urls are resolved.
Entry points samples

    

      Url sample 
      root 
      path 
      base
    

    

      http://localhost/myapp/ 
      index 
      {empty} 
      index
    

    

      http://localhost/myapp/index 
      index {empty} 
      index
    

    

      http://localhost/myapp/users 
      users {empty} 
      users
    

    

      http://localhost/myapp/users/some/path 
      users 
      some/path 
      users/some/path
    

    

      http://www.site.com/ index 
      {empty} 
      index
    

    

      http://www.site.com/index 
      index 
      {empty} 
      index
    

    

      http://www.site.com/users/some/path 
      users some/path 
      users/some/path
From the samples above, it is important to notice that when there is no root part supplied, as in the case of the first and fifth url samples, the root name is automatically termed as "index"
The url entry points are designed to be used for authenticating urls through the use of relative shutter methods. For every url entry point division metioned above, there is an equivalent shutter method that can be used to validate it. Although, there are only 3 url divisions available, as in the case of shutters, there are four shutter method that are used for managing url entry points. These shutters are rootcall(), pathcall(), basecall() and call() methods.

  • The rootcall() method validates the root section of a url only. No validation is done for relative subpaths.
  • The pathcall() method validates the path section of a url only. No validation is done for the root entry point.
  • The basecall() methods validates the specified base section of a url and does not validate subpaths.
  • The call() method validates the entire base section of a url allowing no subpaths.
Each of the shutters above are only designed for routes to be able to perform url validations only on their relative divisions of any url visited. These methods also provides extended functionalities like preload or shut down middlewares for any visited route. There are more details on shutter methods provided here
Docs Wvm Logics