Bundled with

Explanation of App.php

App.php is a system file that is located in the project root folder.

It's important to have friendly server variables to use for links and includes, this is what App.php does for you.

It's pretty nice to be able to use <script src="<?=$app->url?>assets/script.js"></script> and not worry if your url structure is "localhost/myweb", "myweb" or "myweb.com"?

App.php can be included standalone, as it is. Though if you do it that way, it's important that the file is placed in your project root folder. If not, its parameters won't be accurate.

To enable App.php simply include it at the top of your first file that executes upon visit:

include_once "App.php";

then start App.php

$app = new App();

$app now consists of (for this project):

var_dump($app);

object(App)[1]
  public 'env' => string 'live' (length=4)
  public 'url' => string '/' (length=1)
  public 'server_url' => string '/' (length=1)
  public 'root' => string '/srv/www/topbot/' (length=16)
  public 'server_root' => string '/srv/www/topbot/' (length=16)
  public 'pointer' => string '' (length=0)
  public 'htmlbuffer' => string '' (length=0)

Working with config.json.php

When including App.php it will use default parameters as seen above. You can override those by creating a config.json.php file. Topbot bundles a placeholder file for this, containing the basic structure for your overrides. See SAMPLE.config.json.php

string '<?php
/*
  Remove SAMPLE. from my name and put me in project root
*/

$url = $_SERVER['PHP_SELF'];
if(strpos($url, '.php')) {
  $url = explode('.php', $url);
  array_pop($url);
  $url = implode('.php', $url);
  $explode = explode('/', $url);
  $end = end($explode);
  $url = str_replace($end, '', $url);
}

$json = array(
  'localhost' => array(
    'url'         => $url,
    'server_url'  => $url,
    'root'        => __DIR__.'/',
    'server_root' => __DIR__.'/',
    'mysql'       => array(
        'user'    => '',
        'pw'      => '',
        'host'    => '',
        'db'      => '',
        'prefix'  => ''
    ),
  ),
  'live' => array(
    'url'         => $url,
    'server_url'  => $url,
    'root'        => __DIR__.'/',
    'server_root' => __DIR__.'/',
    'mysql'       => array(
        'user'    => '',
        'pw'      => '',
        'host'    => '',
        'db'      => '',
        'prefix'  => ''
    )
  ),
);

echo json_encode($json);' (length=964)

App.php will notice if you are in LIVE or LOCALHOST environment and use the corresponding values to that.

If you decide to use a config.json.php file for you project, note that the config.json.php have to be positioned in your project root to get the server variables accurate.

For your App.php to detect where config.json.php is located, simply pass a string containing the path of where it is located like so:

$app = new App(array(), __DIR__.'/../');

$app will now contain the basic server variables, but also those that you choose to include, like in the example, mysql credentials.


Including files/classes to your project

$app is loaded with two functions that you'll have to keep in mind:

$app->get();

and

$app->includer();

Working with $app->get();

If you want to render any php element in your project, simply point to it using this function (after declaring $app object):

echo $app->get('pages/myphppage');

Notice! Don't use .php-endings in the call, ->get does that for you.

If you are unsatisfied with $app->get() including elements from root, you can simply specify a pointer from where to prioritize reading like so:

$app->pointer = 'public/';

$app->get('pages/myphppage') will then include 'public/pages/myphppage.php' from your project root.

$app->get works with its own scope, so it's not like a regular php include call. If you want to pass any variable, arrays or other datas into the element you are rendering, simply pass them into the function like so:

$app->get('pages/myphppage', array('variable' => $value, 'anothervariable' => 'staticvalue'));

This keeps your files clean from programming logics and only the variables passed in can be used.

Important to keep in mind is that your global $app object will be avaible in all your elements rendered by $app->get().

Working with $app->includer();

$app->includer(array()) scans the targeted directories for files/directories matching the inputs and includes those. This is very inconvenient instead of using phps "include" and/or "include_once" several times at the top of every page.

Simply do:

$app->includer(array('classes', 'misc/phptimefunctions', 'functions'));

to include files.

The code above will go through and do (in order):

  • A search for classes.php
  • If not found, a search for *.php in classes directory
  • If any of the above statements are fulfilled, include the files found
  • Search for phptimefunctions.php in misc directory
  • If not found, a search for *.php in misc/phptimefunctions directory
  • If any of the above statements are fulfilled, include the files found
  • Search for functions.php
  • If not found, a search for *.php in functions directory
  • If any of the above statements are fulfilled, include the files found

$app->includer() should be used right after declaring your $app object:

$app = new App();
$app->includer(array('includes', 'specificdir/include'));

Like $app->get(), $app->includer() also forwards your $app object into all files included. That way you can use any system variables set in you config.json.php in your included files.


Lastly

App.php is totally optional. You can remove the file and SAMPLE.config.json.php if so desired. They are not hooked onto any other file, so don't worry about crashes based on dependencies.

You can have several App.php setups in your project. Lets say you have two apps in your main app, and wants curresponding server variables to each app. Just make sure a copy of config.json.php is located in each and every app root.

When including files to your project, use $app->root. If you want to include something from your web root (not nessecarly the same as project root) use $app->server_root. When linking to pages or anything else, the same goes for $app->url and $app->server_url.

Now code happy! App.php ignores if you use "localhost/myproject", "myproject" or "myproject.com" as your developing url, it will give you the right system variables no matter what. This is very convenient when you are hosting your web live.

Kit made by @kortekim