Differences

This shows you the differences between two versions of the page.

--- getting_started [2019/09/28 15:00] – sahl
+++ getting_started [2024/02/14 14:16] (current) – sahl
@@ Line 3: / Line 3: @@
 ===== Background =====
-Platform is a PHP framework developed by Michael Sahl. 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.
+Platform is a fullstack PHP framework designed for database-dependent applications, with a closely tie between PHP objects and objects in databases. The frontend part is based on JQuery, but can be skipped entirely or integrated with other more complex frameworks.
+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 easy to understand and adapt and does not introduce any complex topics on top of the programming languages already used.
+===== Software requirements =====
+Platform runs on PHP and requires a MySQL (or compatible) database. It is expected to run on Linux.
 ===== 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.
+Platform can either be configured as a single-application framework, which then only supports a single application, or it can be configured for running //instances//, which are unlimited copies of the same application, each with their own database and file structure.
+Programming something like Facebook would be considered a single application, since every user on the platform is using the same application and interact with each other. Programming something like Confluence, would be done with instances, since each organization should have their own instance of the software, where the data shouldn't be mixed with the data of any other organization.
 ===== Installing platform =====
-Copy the code into your website folder and edit config.php to fit your needs.
+Copy the code into your website folder and go to the website root. An interactive procedure will guide you through configuring the platform. You will need to have your database credentials ready, and decide where Platform is going to store files, and make these locations writeable by the web user.
-<code php>
+Platform4PHP will write a configuration file one level up from the web site root, so it need to be able to do so.
-$platform_configuration = array(
-    'global_database_server' => 'DATABASE SERVER NAME',
-    'global_database_username' => 'USERNAME FOR DATABASE',
-    'global_database_password' => 'PASSWORD FOR DATABASE',
-    'global_database_name' => 'NAME FOR GLOBAL DATABASE',
-    'instance_database_name' => 'NAME FOR INSTANCE DATABASES',
-    'dir_store' => 'PATH TO STORAGE FOLDER',
+If you are configuring for instances, then the local database user should have full permissions, including creating and dropping databases, as it is needed when creating instances.
-    'dir_temp' => 'PATH TO TEMP FOLDER',
-    'password_salt' => 'SALT TO USE FOR PASSWORDS'
-);
-</code>
-The database user should have full right including rights to create and drop databases as it is expected to do that when creating instances.
+Store folders should be writable for the web user, but doesn't have to reside in the web root.
-Folders should be writable by the web server user and the cron job user.
+Lastly you need to setup a PHP cron job, if you want to use the Platform Scheduler.
-When finished save the file and go to https://YOURSERVERNAME/install/index.php and Platform will create basic database structures.
-Now you are ready to start coding!
 ===== Demo example =====
@@ Line 43: / Line 35: @@
 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 ====
+===== Where to go next? =====
-We start in ''/demo/create/index.php'' which is the code that creates a new instance.
+You can start by navigating to the [[tutorial]] which explains in detail how the demo is constructed from scratch going through all the possibilities in Platform.
-<code php [enable_line_numbers="true"]>
-<?php
-include $_SERVER['DOCUMENT_ROOT'].'Platform/include.php';
-pagestart('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\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\Instance::initialize($values['instancetitle'], $values['username'], $values['password']);
-    if ($instance instanceof \Platform\Instance) {
-        // Instance was created. Login and continue.
-        $instance->activate();
-        $loginresult = \Platform\User::tryLogin($values['username'], $values['password']);
-        if ($loginresult) {
-            header('location: /demo/app/');
-            exit;
-        }
-        $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>';
-pageend();
-</code>
-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). If all of this is successful the instance is created and the user is logged in, so we redirect to the app.
-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 39.
-==== Logging into the instance ====
-In the ''/demo/login/index.php'' file we have the login functions.
-<code php [enable_line_numbers="true"]>
-<?php
-include $_SERVER['DOCUMENT_ROOT'].'Platform/include.php';
-pagestart('Log into instance');
-$loginform = new \Platform\Form('loginform', 'login.frm');
-$loginform->addValidationFunction(function($form) {
-    // First check if instance exists
-    $instance = \Platform\Instance::getByTitle($_POST['instancetitle']);
-    if (! $instance ) {
-        $form->getFieldByName('instancetitle')->triggerError('No such instance');
-        return false;
-    }
-    // Select the instance to check user credentials.
-    $instance->activate();
-    // Ensure database structures
-    $instance->initializeDatabase();
-    $isloggedin = \Platform\User::tryLogin($_POST['username'], $_POST['password']);
-    if (! $isloggedin) {
-        $instance->deactivate();
-        $form->getFieldByName('username')->triggerError('Invalid user name or password');
-        $form->getFieldByName('password')->triggerError('Invalid user name or password');
-        return false;
-    }
-    return true;
-});
-if ($loginform->isSubmitted() && $loginform->validate()) {
-    header('location: /demo/app/');
-    exit;
-}
-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>';
-pageend();
-</code>
-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 otherwise we call initializeDatabase to ensure that the instance database is updated and returns true to indicate that the form passed successfully and the user is logged in.
-In this way we can just pass the user into the application if the form validates (:32-33)
-==== 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.
-<code php [enable_line_numbers="true"]>
-<?php
-include $_SERVER['DOCUMENT_ROOT'].'Platform/include.php';
-Platform\Accesstoken::validateSession('/login/', true);
-if ($_GET['action'] == 'logout') {
-    Platform\Accesstoken::destroySession();
-    Platform\Instance::deactivate();
-    header('location: /demo/');
-    exit;
-}
-if ($_GET['action'] == 'destroy_instance') {
-    $instance = new \Platform\Instance();
-    $instance->loadForWrite(\Platform\Instance::getActiveInstanceID());
-    if ($instance->isInDatabase()) {
-        $instance->delete();
-    }
-    Platform\Instance::deactivate();
-    header('location: /demo/');
-    exit;
-}
-pagestart('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\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="?action=logout">Log out</button> ';
-echo '<button class="w3-button w3-black w3-hover-teal" data-destination="?action=destroy_instance">Destroy instance</button> ';
-echo '</div>';
-echo '</div>';
-echo '<div class="w3-container w3-gray" style="font-style: italic; font-size: 0.8em;">';
-echo 'Platform';
-echo '</div>';
-pageend();
-</code>
-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.
-===== 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 go to the [[classes]] hierarchy to browse the different platform components or start building your own application. The first step in building your own application is to create a subclass of the [[Instance class]] to contain your own objects and logic, which is implemented using the [[Datarecord class]]. For the frontend part of Platform start with the [[Component class]].
 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.