Latest release: Master: Dev:

Table of Contents

1. What is this?
2. Licence
3. Structure [General | Namespaces]
4. Workflow [Main Concept | The global Alo class | Controllers | Views]
5. Routing
6. Logging
7. Initial setup
8. Updating
9. Running tests
10. Latest Changes
11. External Libraries

What is this?

AloFramework is an incredibly lightweight and flexible MVC framework for PHP 5.4+. It has a lot of built-in functionality including but not limited to:

• Memcached wrapper
• Database connection class
• MySQL or Memcached-based session manager
• HTML form validator
• Code testing suite
• Email sender
• Crontab editor
• Object-oriented cURL wrapper
• Object-oriented file manager
• Remote SFTP file manager
• Code testing suite
• Code profiler

^TOC

Licence

This product is licenced under the GNU General Public Licence Version 3

^TOC

Structure

General

You will find code documentation under the docs directory, some setup scripts under setup and source files under src. In src the main components are app, *resources, sys and files under the directory root.

• sys contains all the framework files
• resources is where you're meant to put all your images, css and whatnot
• app is where your code should go
• .htaccess makes sure requests get routed correctly
• index.php contains some core constants

^TOC

Namespaces

The class, trait and interface directories found under src/app and src/sys follow a namespaced structure, e.g. the class Alo\Db\MySQL would be found in the file class/alo/db/mysql.php. Please not that all directory and file names should be lowercase.

^TOC

Workflow

Main concept

For most projects, you will want to write your own classes that extend those of the framework's. That way you will be completely safe from losing any code during a framework upgrade. The built-in autoloader will automatically load any required interfaces found in app/class, app/interface, sys/class and sys/interface.

^TOC

The global Alo class

This class is always loaded by default and contains static references to objects which are in most cases used as singletons. You should try to load most of your classes into its static properties, e.g. you will usually only need one database connection, so you can assign it to Alo::$db and access it from anywhere in your code.

^TOC

Controllers

All controllers must go under app/controllers (accessible via the DIR_CONTROLLERS method), have the Controller namespace and extend the class Alo\Controller\AbstractController. To make this easier, you can write your own Abstract controller and extend that of Alo\ from within, for example:

app/class/controller/abstractcontroller.php

namespace Controller;

class AbstractController extends Alo\Controller\AbstractController {
   //Your code
}

app/class/controller/home.php

namespace Controller;

class Home extends AbstractController {
   //Your code
}

Only public, non-abstract, non-static methods will be used for routing. The default method for most controllers is index(). Controllers can be in any of DIR_CONTROLLERS' subdirectories.

^TOC

Views

Any view can be loaded via Alo\Controller\AbstractController's protected method loadView:

/**
  * Loads a view
  *
  * @author Art <a.molcanovas@gmail.com>
  * @param string  $name   The name of the view without ".php".
  * @param array   $params Associative array of parameters to pass on to the view
  * @param boolean $return If set to TRUE, will return the view, if FALSE,
  *                        will echo it
  * @return null|string
  */
  protected function loadView($name, $params = [], $return = false) {
     // Code
  }

This will load a view under app/view/$name.php. You can provide parameters to pass on to the view via $params, e.g. if you pass on ['foo' => 'bar'] and echo $foo in the view, the output will be bar. If instead of echoing the output you want to retrieve it, provide $return with true. Each view can be reused during the same execution.

^TOC

Routing

All routing is done in the router.php config file. By default, if a route is not found, the router will look in your controllers directory's root for an automatically calculated route: www.domain.com/controller/method/arg1/arg2[...]/argN. This can be overwritten in the $routes array, where the array keys are case-insensitive regular expressions for the request URI (without delimiters or modifiers) and the values are configuration arrays containing the following keys (bold values mean the default values if the key is not set):

• dir => the controller subdirectory [./]
• class => which controller class to load [$default_controller] or URL-based
• method => which method to load [index or URL-based]
• args => array of arguments to pass on to the method. These can be hardcoded values or placeholders ('\$1', '\$2' etc) which will replace items in the regular expression (key). [empty array]

^TOC

Logging

All logging is done via the global static class \Log's public methods - please refer to the documentation. You will can set the logging level (during the Initial Setup phase described below).

^TOC

Initial setup

• You will want to copy the contents of sys/config into app/config. Open them and set the values as appropriate.
• Open index.php, scroll to // ===== General setup BEGIN ===== and set the values as you please.
• Next you'll want to run the appropriate files under setup if you are using that functionality.

^TOC

Updating

Updates are applied by following these 6 steps:

1. Look through the changelog for to see if any changes will cause issues (e.g. a deprecated method being removed), prepare your code if necessary.
2. Make a copy of your index.php and .htaccess files.
3. Delete the above, as well as the sys directory.
4. Extract the new code. It will never contain files other than blank index.htmls and sample.phps under app/, so no application code will be overwritten.
5. If there are any changes to .htaccess, merge them with your version.
6. Re-apply your personal settings under index.php's // ===== General setup BEGIN =====

^TOC

Running tests

When running PPHUnit tests be sure to use the phpunit.php bootstrap file from the root directory. It will make sure that all classes are loaded correctly and that the framework behaviour is altered to not interfere with the tests. Please note that in PHPUNIT mode the framework does not automatically initialise the Router - you will have to run the code below to test a controller:

$router = new \Alo\Controller\Router();
$router->init(); //Or ->initNoCall() if you just want to initialise it, but not call the relevant controller

^TOC

Latest changes

See changelog.md for a full changelog of previous versions.

1.0 (2015-05-08)

Reworked

• Router fully reworked. Refer to README for documentation on the new router.

Major bugfixes

• Fixed the error message (and subsequent die() statement) when the log level is set to LOG_LEVEL_DEBUG.

Misc bugfixes

• Changed the event definition in setup/create_session_table_and_cleaner.sql to use the correct table name
• Debug output in MemcachedWrapper->getAllMemcache() removed
• Logger & error handler paths fixed for PHPUNIT
• Cookie clease tweaked for PHPUNIT
• Fixed exception throwing if-else order in MemcachedSession. It now makes sure the MemcachedWrapper class is loaded and all its static properties are loaded before calling is_available()
• Fixed multiple validation errors in the testing suite
• Crontab should now correctly reload if it fetches an empty string
• Fixed code line detection in log messages

Added features

• It's now possible to force a session write operation during runtime via AbstractSession->forceWrite()
• clear(), getTokenExpected() and getTokenActual() and refreshToken() added to AbstractSession
• clearCrontab() method at crontab editor
• Possibility to automatically commit crontab changes. Use with caution!
• getAtIndex() method in Cron
• \Alo\Statics\Security class added
• __isset() and __unset() added to all classes that had __get() or __set() defined
• \Alo\Statics\Format::is_ipv4_ip() method added

Removed items

• Format::isBoolean()

Miscellaneous

• Switched to ApiGen as the code documentation provider
• SQLSession now uses the ALO_SESSION_TABLE_NAME instead of self::TABLE_NAME
• json encode/decode removed from MemcachedSession write/fetch()
• FormValidator documentation edit
• Cron editor now throws an exception if you try to invoke it on a Windows machine
• PHPUNIT_RUNNING constant definition moved out of source code. It now simply checks if the constant is defined in the bootstrap file.
• The global functions getFingerprint(), getUniqid(), escape() moved to \Alo\Statics\Security. The escape() function has been renamed to un_xss() in the class.
• DIR_CONTROLLERS constant added

^TOC

External Libraries

AloFramework uses the following external libraries for its functionality:

• PHPMailer for email support
• Kint for debug output

^TOC