This is an old revision of the document!
Table of Contents
Getting started with Platform
Background
Platform is a PHP framework. The framework is intended to make development of PHP applications very fast, and making it easy to implement new ideas. At the same time the framework is intended to be very basic and easy to understand, in opposition to most modern PHP frameworks which is abstract and have a considerable learning curve.
Architecture of platform apps
Platform application consist of one or more instances which are self-contained instances of the application, each having their own database and file structure. A simple application targeted at single users, could be a single instance, while a complex app targeted at companies and their employees could implement an instance for each company.
Installing platform
Copy the code into your website folder and go to the website root. An interactive procedure will guide you through configuring the platform.
Platform4PHP will try to write its configuration file one directory up from the web site root, so it need to be able to do so.
The local database user should have full right including rights to create and drop databases as it is expected to do that when creating instances.
Folders should be writable by the web server user and the cron job user.
Demo example
Navigate to https://YOURSERVERNAME/demo/ to see a quick demo of Platform and get a feeling of the instance feature. Select “Create instance” and fill the form and click “Create instance” again.
A new instance have now been created with a test user. Observe that a new database is created. You can log out of this instance and into it again. You can also create further instances if you want to, or destroy the instances you have already created.
Creating an instance
We start in /demo/create/index.php
which is the code that creates a new instance.
<?php include $_SERVER['DOCUMENT_ROOT'].'Platform/include.php'; \Platform\Page::renderPagestart('Create new instance'); $new_instance_form = new \Platform\Form('new_instance_form', 'new_instance.frm'); $new_instance_form->addValidationFunction(function($new_instance_form) { // Check if instance if taken if (\Platform\Server\Instance::getByTitle($_POST['instancetitle'])) { $new_instance_form->getFieldByName('instancetitle')->triggerError('Instance name already in use'); return false; } return true; }); if ($new_instance_form->isSubmitted() && $new_instance_form->validate()) { $values = $new_instance_form->getValues(); $instance = \Platform\Server\Instance::initialize($values['instancetitle'], $values['username'], $values['password']); if ($instance instanceof \Platform\Server\Instance) { // Instance was created. Login and continue. $instance->activate(); $instance->loginAndContinue($values['username'], $values['password'], '/demo/app/'); $new_instance_form->getFieldByName('instancetitle')->triggerError('Instance was created, but a login couldn\'t be performed.'); } else { $new_instance_form->getFieldByName('instancetitle')->triggerError('A new instance couldn\'t be initialized!'); } } echo '<div class="w3-container w3-teal">'; echo '<h1>Create instance</h1>'; echo '</div>'; echo '<div class="w3-container">'; $new_instance_form->render(); echo '</div>'; echo '<div class="w3-container w3-gray" style="font-style: italic; font-size: 0.8em;">'; echo 'Platform'; echo '</div>'; \Platform\Page::renderPageend();
Line 4 outputs the start of the page including the starting html-tag, the head-section and the starting body tag. See Design class for more info.
In line 6 we create a form to create the instance, which is easily accomplished using the special form file format. In line 8 we add an additional validation function to the form, which check that the name of the instance isn't already used, and triggers an error on the appropriate form field, if this is the case.
In line 17 we check for a form submission and validates the form. If the form is submitted and is valid, we initializes a new instance in line 19, activate it (22) and performs a login (23). The login will redirect if successful, so we throw an error if this doesn't happen.
See more in the Form class and the Instance class.
The rest of the page is just layout, with the form being outputted in line 35.
Logging into the instance
In the /demo/login/index.php
file we have the login functions.
<?php include $_SERVER['DOCUMENT_ROOT'].'Platform/include.php'; \Platform\Page::renderPagestart('Log into instance'); $loginform = new \Platform\Form('loginform', 'login.frm'); $loginform->addValidationFunction(function($form) { // First check if instance exists $instance = \Platform\Server\Instance::getByTitle($_POST['instancetitle']); if (! $instance ) { $form->getFieldByName('instancetitle')->triggerError('No such instance'); return false; } // Select the instance to check user credentials. $instance->activate(); $instance->loginAndContinue($_POST['username'], $_POST['password'], '/demo/app/'); $form->getFieldByName('username')->triggerError('Login failed'); return false; }); if ($loginform->isSubmitted()) { $loginform->validate(); } echo '<div class="w3-container w3-teal">'; echo '<h1>Log into instance</h1>'; echo '</div>'; echo '<div class="w3-container">'; $loginform->render(); echo '</div>'; echo '<div class="w3-container w3-gray" style="font-style: italic; font-size: 0.8em;">'; echo 'Platform'; echo '</div>'; \Platform\Page::renderPageend();
Again we use the Form class to create a login form and we add a custom validation function.
We start by checking if the specified instance exists (:10) and if it doesn't we trigger an error. Otherwise we activate the instance (:16) and try to log the user in (:18).
If we cannot login we trigger an error.
Inside the instance
Our application is implemented in /demo/app/index.php
and is just a page showing the current user id and two buttons.
<?php include $_SERVER['DOCUMENT_ROOT'].'Platform/include.php'; Platform\Security\Accesstoken::validateSession('/demo/login/', true); if ($_GET['event'] == 'logout') { Platform\Security\Accesstoken::destroySession(); Platform\Server\Instance::deactivate(); exit; } if ($_GET['event'] == 'destroy_instance') { $instance = new \Platform\Server\Instance(); $instance->loadForWrite(\Platform\Server\Instance::getActiveInstanceID()); if ($instance->isInDatabase()) { $instance->delete(); } Platform\Server\Instance::deactivate(); exit; } \Platform\Page::renderPagestart('You are logged into your instance'); echo '<div class="w3-container w3-teal">'; echo '<h1>Logged in.</h1>'; echo '</div>'; echo '<div class="w3-container w3-padding-16 w3-text-gray">'; echo 'You are logged into the system. Your user ID is: '.\Platform\Security\Accesstoken::getCurrentUserID(); echo '</div>'; echo '<div class="w3-container w3-center w3-padding-16">'; echo '<div class="w3-bar">'; echo '<button class="w3-button w3-black w3-hover-teal" data-destination="?event=logout">Log out</button> '; echo '<button class="w3-button w3-black w3-hover-teal" data-destination="?event=destroy_instance">Destroy instance</button> '; echo '</div>'; echo '</div>'; \Platform\User::renderEditComplex(); echo '<div class="w3-container w3-gray" style="font-style: italic; font-size: 0.8em;">'; echo 'Platform'; echo '</div>'; \Platform\Page::renderPageend();
The first thing to do when inside the application, is to ensure that the user is actually allowed here. This is done in line 4 where we validate the session. We instruct Platform to redirect the user to the login page if not logged in. See Accesstoken class for more info about security and access tokens.
After that we check the querystring for two keywords. Logout which will log out of the application and destroy_instance which will destroy the entire instance and remove it from the database.
A logout is performed in line 7-8 by first destroying the session contained in the Accesstoken and then deactivating the current instance. After that we redirect back to the front page of the demo.
Destroying the instance is performed in line 14-19. First we create a new Instance object, and then we load the active instance from the database in write mode.
We check if the instance was actually stored in the database, and if so: We delete the instance object, which will both remove it from the instance table and drop the entire database containing this instance. This is ofcourse a very dramatic thing to do in a real application and should be accompanied by proper user prompts and warnings.
After the instance is deleted we deactivate it, to removes traces from it in the session variables and then we redirect back to the start page.
To show the power and ease of Platform4PHP, we spawn an interface for administering users which is just a single line (42) of code.
Where to go next?
The first step in building your own application is to create a subclass of the Instance class to contain your own objects and logic. The center of Platform is the Datarecord class so you should also familiarize yourself with that one.
Otherwise it is just to explore the other classes in Platform and start coding away. The aim of Platform is to be easy and highly productive, keeping focus on your own ideas while handling all basic things such as database objects, forms, tables and other things as easy and with as little code as possible.