Enable Javascript

Downloads

PHPPE Core

Core (90k)
Minified production version.
github.com Inlined

Source (200k)
Developer friendly version. github.com Browse online

Developer (95k)
Tests and repository build tools.
Self Test View (24k) Download Source

Extensions

PHPPE Pack (96k)
Core extensions, most notably jQuery.
Download Source

CMS (28k)
Content editor.
Download Source

Extensions (24k)
Web-based extension manager.
Download Source

Bootstrap (149k)
Twitter's environment.
Download Source

Data Library (19k)
Utility to upload and organize attachments.
Download Source

Gallery (4k)
Picture manipulation and management tool.
Download Source

DBA (5k)
DataBase Administrator web interface.
Download Source

GPIO (4k)
GPIO Interface for Raspberry Pi.
Download Source

RPi (8k)
Web-based monitoring tool for Raspberry Pi.
Download Source

Welcome to PHPPE3!

PHP Portal Engine - single file framework

PHPPE is a minimalistic, yet feature-full micro-framework and CMS. The framework's core is a single file and only a few kilobytes in size, so small, that it fits on your clipboard! Unlike other existing OpenSource PHP frameworks, PHPPE was written with security, MVC, KISS principle and no dependency at all in mind. As being a micro-framework, it won't solve all of your web-development oriented tasks, but will definitely solve the most common ones and make your life easier. It's not bloated, and with simplicity cames stability and high performance.

As it contains 7 bit ASCII characters only it's safe to paste over terminals for easy installation. As a matter of fact this single html file you're reading is enough to set up a working PHPPE environment, internet connection is NOT required at all!

Features

This ~90k bytes of PHP code will give you:

• Single file deployment.
• Stand alone environment, optional dependencies only.
• PHP Composer compatibilty
• PHPUnit compatibility with 100% code coverage
• Bootstrap compatibilty
• Can be used as CGI (Apache and nginx), from CLI and also as a library just out-of-the-box
• Scalable cluster architecture to face huge loads
• Very low footprint, ideal on small computers such as Raspberry Pi
• Highly modular, easy to expand structure with Class autoloader
• Self consistency check and diagnostics (even fix!)
• Environment auto-detection (like base url, browser's language, timezone and screen size)
• Clever, regular expression capable and filterable, class::method routing mechanism
• Convient and easy to use ORM model interface
• PDO driven database layer with transparent on demand scheme installation
• Fast and safe templater system for views
• Powerful caching with integrated memcached, APC/APCu and compressed file support
• Automatic form data validation and security checks
• Access control lists
• Audit logging to files or syslog
• Monitoring support (nagios can get performance and status info easily from it's output)
• Thumbnail generation and image manipulation support (with libGD)
• Built-in Content Server for CMS support
• BiDi multilanguage support
• Uses View layer to detect Models (flexibility you've never seen)

Of course one single file is limited, so here's the PHPPE Pack (another ~90KiB) to save the day and give you an easy start with configuration registry, email services, user management, SQL Query Builder etc.

For full CMS capability you'll also need the Content Editor in PHPPE CMS (46KiB), because PHPPE Core on it's own only serves contents.

Requirements

• At least PHP 7.0
• SSH terminal access (use ssh or PuTTY)
• Apache or nginx with php-fpm on server side
• Any HTML5 compatible browser on client side
• No more than 768KiB free space if you install all basic plugins (Pack, CMS, Extensions and Developer)

Optional

• PHP POSIX extension and sudo (for automatic permission and file owner fixes in diagnostic mode)
• PHP Composer for extension management
• A cron implementation (crond, vixie-cron etc.) for background jobs

License

PHPPE Core, PHPPE Pack, PHPPE CMS, PHPPE Extensions as well as PHPPE Developer are free and OpenSource softwares, licensed under LGPL-3.0+. See LICENSE for details.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License as published
   by the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.

Although the framework is free, keep in mind that extensions may or may not use different licenses. PHPPE's licensing allows you to implement a closed source application on top of it.

Brief history

• PHPPE 1.0.0 - basic concepts were there, used a strange mixture of functional programming and MVC. Approx. 2000 - 2006.
• PHPPE 2.0.0 - refactored 1.0.0; self check, diagnostics and single file deployment appeared. Provided modularity via includes. Available in archive (32k). In 2011 - 2013.
• PHPPE 3.0.0 - complete rewrite of the same concept in OOP, and fixed features that previous versions lacked. Modularity by classes. In 2014 - 2016.
  

Quick and dirty 2 to 3 migration guide

Design Choices and Architectural Goals

Really small foot print

What I mean by that is a really-really-really small foot print, not in a CI (11MiB) or lumen (30MiB) sense, but measured in couple hundreds of kilobytes. I wanted to run this framework efficiently on micro-computers, later my choice fall on Raspberry Pi.

Single file deployment

Must work on it's own, but has to be able to detect and corrigate it's environment by building up directory structures if necessary without any kind of help.

Keep It Simple Stupid

Only optional dependencies. The main reason why other frameworks fail being small and fast lies in their huge amount of dependencies. There's no reason to include a bloated library if only one or two methods is used out of it. PHP has a reach, constantly expanding function set, there's always a better, simpler way with pure php functions. You can argue with that, but time has shown that I'm right.

Also there should be about a dozen, clear event hooks. Too few or too many hook-points reflects serious design flaw.

Modern MVC Framework

It has to be a Model/View/Controller framework, meaning you can build custom webapplications on top of it if you want easily. For that it must provide all key features of a modern PHP framework (ORM, class autoloading, templater, etc.)

Not just a framework, but a CMS as well

It was also important that if no webapplication found for an url, it must serve contents from a database or cache.

Performance

This is the main reason of low foot print and why caching is so sophisticated in PHPPE. Not to mention nginx compatibility and the built-in benchmarking feature.

Scalability

PHPPE was designed in a way that it can run on several load-balanced, dynamically started/stopped content provider servers, all feeded by a single content editor server.

Configurationless modularity

It's a very important design goal that installing an Extension should not require anything else than copying files under vendor/phppe/. If file access rights are correct, no need for running diagnostics mode.

Transparent datascheme installation

As a part of the previous goal, it has to be able to install new tables transparently, without of the need of loading sqldumps with third-party utilities.

Security

Security is not something that you can achieve by constantly patching your codebase. It has to be designed that way, making strict decisions, like:

• separating php libraries, webserver accessible php entry points and assets
• forbid the webserver to write php file once and for all.
• forget about php templater even it has a significant performance gain
• self consistency check

Stability

The Core must be stable and well-tested. No new features or interface changes within major php releases allowed there, that's what well-though hook points and Extensions are for.

Effectiveness

Eliminate the need of PHP coding as much as possible for webpage changes. This means that every aspect of the page should be stored as data, so that it can be changed from a web interface without coding. As for the Models, no field specific stuff should be hardcoded in controllers, so changing the database scheme won't lead to chaging the code, only Model class top.

By doing so makes the website changes easy, rapid and cheap as no development involved.

Usability

From an administrator's point of view, it must have a short learning-curve and intuitive interface. It's good if that also can be achieved at developer level, but not so important. An application is written once, but used many-many times, that should make the priority clear.

Directory Structure

PHPPE has a very comfortable build-up. The PHPPE Core, the application as well as all extensions share the same directory structure.

ProjectRoot

This is the working directory of PHPPE. When you specify any path within PHPPE, you'll have to use paths relative to this directory. This saves you a lot of typing in your code and ease the migration across servers.

Subdirectories of every PHPPE Extension

These directories are optional. If an extension does not provide let's say controllers, ctrl/ can be ommited.

Important files and directories

Symbolic links

It's very important that your working directory is ProjectRoot. Therefore all symlink paths should be relative in PHPPE.

Glossary

Access Control Entry (ACE)

Access Control List (ACL)

Add-On

Application

Client

Concept

• Views are generated from templates, so called layouts (eg.: "blogpost"). These have special tags marking variable places (like <!=title>, <!=createdate> etc.).
• The common homepage layout is described by a specific template, called "frame". This layout frames all the others. This is the place for the header, the menu, and the footer etc.
• Each page corresponds to an url, and it's an instance of a layout. Page parameters fill in variable places in templates (eg.: by replacing <!=createdate> with the blog post's actual creation date).
• Pages can be grouped in page lists. Each page can be member of several lists. There's one special page list, called "mainmenu" which always exists. Unlike other CMS alternatives, in PHPPE you don't have to put a page in the menu if you want to expose it's url to the user. In PHPPE you can access it by entering it's url directly regardless of menus. So if you want to disable a specific url, simply unpublish the corresponding page.
• Page lists can be used in <!foreach when generating view (eg.: "blogfrontpage", which lists pages of layout "blogpost", ordered by descending creation date).
• There's always a user object reflecting the actor on client side, if not authenticated then a restricted anonymous.
• Controllers are executed before view generated, so that action handlers can redirect the user or influence the output.
• A page with it's own controller and view (hence not using any content template or page parameter) is considered to be an application.

Core

Diagnostics mode

Dock

DocumentRoot

Extension

Frame

Maintenance mode

Menu

Model/View/Controller

Service

Object Relational Mapper

Pack

Panel

ProjectRoot

Runlevel

Template or Layout

Installation

All-in-one commands for people who are too lazy to read through:

composer create-project bztsrc/phppe3
mv phppe3 (yourproject) && cd (yourproject)
$EDITOR phppe/config.php

git clone --branch 3.0 https://github.com/bztsrc/phppe3.git
mv phppe3 (yourproject) && cd (yourproject)
sudo php public/index.php --diag
$EDITOR phppe/config.php

mkdir public
curl https://raw.githubusercontent.com/bztsrc/phppe3/master/public/index.php >public/index.php
sudo php public/index.php --diag
composer update
$EDITOR phppe/config.php

mkdir public
cat >public/index.php
         copy this, paste here and press ^D
sudo php public/index.php --diag
$EDITOR phppe/config.php

1. Get the single file framework

Open up a terminal, and ssh to your server (or use a windowed ssh client). Change working directory to your ProjectRoot, then type

$ mkdir public
$ cat >public/index.php

Copy the Core to your clipboard: click here, select all and copy. Switch back to Terminal, paste the code from clipboard then press Ctrl+D.

If your terminal is laggy and you cannot paste the code without mistakes, copy'n'paste this much shorter command that downloads the file from the server.

$ curl https://raw.githubusercontent.com/bztsrc/phppe3/master/public/index.php >public/index.php

If you take a look at your site in a browser, you'll see a greeting message:

2. Run diagnostics

Now framework is in place, it's time to run diagnostics to create directory structure and missing files. Without the "sudo", file ownerships and permissions may be left incorrect.

$ sudo php public/index.php --diag

If you failed to copy'n'paste the code correctly, you'll see this:

PHPPE-C: Corrupted index.php
LOG-C: unable to write data/log/phppe.log

Root privilege is only needed for setting up file permissions, if you run it as a normal user, chown and chgrp may fail. In this case you'll see a warning:

DIAG-W: not root or no php-posix, chown/chgrp may fail!

If your webserver's group cannot be autodetected, or you run your vhosts under different users with setuid and setgid, you can specify the desired group id like:

$ sudo php public/index.php --diag --gid=33

If everything went well, you should see this message:

DIAG-I: OK

3. Check it in a browser

Check your site in a browser. You should see something similar to this:

array (size=0)
  empty

array (size=0)
  empty

array (size=6)
  'f0' =>  '' (length=0)
  'f1' =>  '' (length=0)
  'f2' => null
  'f3' =>  '' (length=0)
  'f4' =>  false
  'f5' =>
    array (size=0)
      empty

The --self-update option will update the Core to the latest version and it will also install PHPPE Pack (see step 5) and PHPPE Extensions Manager (see step 6). It's useful if you don't have Composer or you prefer web interfaces and want to minimize your command line activity.

4. Configure your site

$ nano phppe/config.php
$ vim phppe/config.php

You can use the passwd utility to generate masterpassword hashes from command line.

$ php public/index.php passwd
Password? You won't see what you type here
$2y$12$VUzOd391c2oYiESz3FSi2eZz1Gk5B9A2Kz66rvuNkkR04xQ/6yp0G

5. Install PHPPE Pack (optional)

The diagnostics mode created missing files, among others composer.json. With that you can make PHP Composer to install vendor/phppe/Core from PHPPE Pack:

$ composer update

$ curl https://bztsrc.github.io/phppe3/phppe3_core.tgz | tar -xz -C vendor/phppe/Core && sudo php public/index.php --diag

6. Install PHPPE Extensions Manager (optional)

$ composer require phppe/Extensions

$ mkdir vendor/phppe/Extensions && curl https://bztsrc.github.io/phppe3/phppe3_extensions.tgz | tar -xz -C vendor/phppe/Extensions

7. Install PHPPE CMS (optional)

$ composer require phppe/CMS

$ mkdir vendor/phppe/CMS && curl https://bztsrc.github.io/phppe3/phppe3_cms.tgz | tar -xz -C vendor/phppe/CMS

This extension is not installed automatically as in a cluster you only need to install CMS on the management node(s).

Usage

PHPPE has a concept of an url-related application that has several actions, each operating on a specific item. An application houses one or more constroller classes, in which every action is mapped to a method, that will receive item as argument.

As a web CGI

If no URL Routing rules applies to the queried url, it will fallback to default routing, which parses the url as

https://my.domain/some/path/users/modify/joesmith

As a CLI script

php public/index.php users sendnotifymails
php public/index.php users delete joesmith
php public/index.php cron dailytasks
php public/index.php --version
php public/index.php --help
php public/index.php --diag

It's worth setting up an alias for PHPPE

alias phppe = 'php public/index.php'

As a library

1

include("public/index.php");

1
2

$phppe = include("public/index.php");
$phppe->run();

Configuration

PHPPE Core is configured in phppe/config.php, with an array. Available properties can be found on PHPPE\Core Class documentation, these are only the most commonly used ones.

Application configuration

Your application's configuration resides in app/config.php. Your application's init() method will receive it as it's only argument.

Extension configuration

Every extension has it's own configuration file, named vendor/phppe/*/config.php. When initializing, their init() method will get the configuration array.

Configuration files for Extensions (and for Application as well) required to return associative arrays:

1
2
3
4
5

<?php
return [
	"key" => "value",
	//...more properties
];

Security

Unlike any other OpenSource PHP framework, being secure is one of the main concerns of PHPPE. It uses different methods at several levels, which all together provide a decent security for your application.

Use AppArmour

Monitoring

Parsing output

<!-- MONITORING: ([A-Z]+), page ([0-9\.]+) sec, db ([0-9\.]+) sec, server ([0-9\.]+) sec, mem ([0-9\.]+) mb[, mc] --> </body>

Configuring syslog

(vhost name):PHPPE-(A|W|E|C|I|D)-(extension):(original message without line breaks)

1
2
3
4

//send all messages to syslog, don't write log files.
'syslog' => true,
//also log debug trace along with messages
'trace' = true,

Background Jobs

Running as webmaster

$ crontab -e
*    * * * * /usr/bin/php (your DocumentRoot)/index.php --diag
*    * * * * /usr/bin/php (your DocumentRoot)/index.php cron minute
*/15 * * * * /usr/bin/php (your DocumentRoot)/index.php cron quaterly
0    * * * * /usr/bin/php (your DocumentRoot)/index.php cron hourly
5    0 * * * /usr/bin/php (your DocumentRoot)/index.php cron daily
*/20 * * * * /usr/bin/php (your DocumentRoot)/index.php cron myjob1
*/21 * * * * /usr/bin/php (your DocumentRoot)/index.php cron myjob2

It's important that in this case the script will be running with owner's rights. Or, if you're a system administrator, you can use system wide configuration file and specify user

*    * * * * (vhost's user name) /usr/bin/php (vhost's DocumentRoot)/index.php cron minute
*/15 * * * * (vhost's user name) /usr/bin/php (vhost's DocumentRoot)/index.php cron quaterly
0    * * * * (vhost's user name) /usr/bin/php (vhost's DocumentRoot)/index.php cron hourly
5    0 * * * (vhost's user name) /usr/bin/php (vhost's DocumentRoot)/index.php cron daily

Example action handlers for these commands can be found in events section. For each job, you'll have to implement cron + ucfirst(jobname) ($arg), like cronMinute($arg) or cronMyjob1($arg).

Running as webserver

You can create background jobs programatically as well with Tools. With this interface the scripts will run with the webserver's rights.

1
2

//! call $myClass->myMethod('cleanup','me') every 5 secs.
\PHPPE\Tools::bg( "myClass", "myMethod", [ "cleanup", "me"  ], 5 /*secs*/ );

Webserver configuration

PHPPE is tested under Apache and nginx webservers. Apache is more common, while nginx has better performance. Both are capable of url rewriting which is a key feature to hide 'index.php' from the url. Here are two examples on how to do it.

<VirtualHost *:80>
    ServerName mysite.tld
    DocumentRoot "/var/www/mysite/public"
    <Directory "/var/www/mysite/public">
        Options -Indexes +SymLinksIfOwnerMatch +ExecCGI
        AllowOverride None
        Order allow,deny
        Allow from all
        RewriteEngine On
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteRule ^(.*)$ index.php/$1
    </Directory>
    CustomLog /var/log/apache2/mysite-access.log combined
    ErrorLog /var/log/apache2/mysite-error.log
    php_admin_flag register_globals off
    php_admin_flag allow_url_fopen off
    php_admin_flag allow_url_include off
    php_admin_value open_basedir /var/www/mysite
    php_admin_value upload_tmp_dir /var/www/mysite/.tmp
</VirtualHost>

user www-data;
server {
  listen 80 default_server;
  root /var/www/mysite/public;
  server_name mysite;

  location / {
    try_files $uri $uri/ =404;
    index index.php;
    if (!-e $request_filename){
      rewrite ^(.*)$ /index.php;
    }
  }
  location ~ \.php$ {
    fastcgi_index  index.php;
    fastcgi_param  SCRIPT_FILENAME    $document_root$fastcgi_script_name;
    fastcgi_param  SCRIPT_NAME        $fastcgi_script_name;
    fastcgi_param  QUERY_STRING       $query_string;
    fastcgi_param  REQUEST_METHOD     $request_method;
    fastcgi_param  REQUEST_URI        $request_uri;
    fastcgi_param  DOCUMENT_URI       $document_uri;
    fastcgi_param  DOCUMENT_ROOT      $document_root;
    fastcgi_param  SERVER_PROTOCOL    $server_protocol;
    fastcgi_param  HTTPS              $https if_not_empty;
    fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
    fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
    fastcgi_param  REMOTE_ADDR        $remote_addr;
    fastcgi_param  REMOTE_PORT        $remote_port;
    fastcgi_param  SERVER_ADDR        $server_addr;
    fastcgi_param  SERVER_PORT        $server_port;
    fastcgi_param  REDIRECT_STATUS    200;
    ## !!! important !!! use $host for catch-all
    fastcgi_param  SERVER_NAME        $host;

    fastcgi_pass unix:/var/run/php-fpm.sock;
  }
}

Running Overview

PHPPE\Core Constructor

The framework has two different running scheme. PHPPE\Core constructor controls which one of these should be called. The $islib boolean variable is set if the framework was included from another php file as a library.

      constructor
           ↓
       autoload
           ↓
(CLI and has "--diag"?)
      y ↙     ↘ n
bootdiag()   Init event
     ↓           ↓
Diag event    ($islib?)
                    ↘ n
                  run()

The following files will be processed in order:

Initialization event

Run Application

The URL routing mechanism chooses one controller class in an application to run. To do that, PHPPE\Core::run() consult the ClassMap to find the class.

Generating output

Finally templater will be called to generate output for the specified view. For CLI scripts templater is skipped unless you explicitly set a template in the action handler.

Because templater will try to find a view on it's own, it's possible to omit controller for a page entirely. This is very useful for pages like "About Us".

URL Routing

First of all, if PHPPE\Core::$core->maintenance is true, all routing will be bypassed and only maintenance view will be displayed (using maintenance.tpl template). Otherwise the routing decision is made in PHPPE\Core::run().

PHPPE has a concept of application that has several actions, each operating on a specific item(s). With other words, application is a controller class, action is a method in it, and item is it's argument (or more items separated by slash '/'). To explain URL routing, first we'll need an example application with actions. PHPPE gives you the freedom on how to organize your code. You can put all of your application's actions in a single file, or you can create separate files for each action. That's your choice.

1
2
3
4
5
6
7
8
9

namespace PHPPE\Ctrl;
class MyController extends MyApp {
    //this action will be called via url routing with specific arguments
    function myspecaction( $arg1, $arg2 = "" ) {}
    //without route() call, arguments will be splitted by directory separator
    function myaction( $item,  $item2 = "" ) {}
    //default action
    function action( $item ) {}
}

1
2
3
4
5

namespace PHPPE\Ctrl;
class MyAppMyAction extends MyApp {
    //if you use separate files, only one action handler defined in each.
    function action( $item ) {}
}

URL matcher routes

Routes are loaded with PHPPE\Http::route() in one of the extensions (or your applicaiton) initialization file, and they will be matched against the url. If url mask does not contain pharenthesis (no arguments), the remaining of the url will splitted at slashes and passed to the method as argument(s). If method is omited, default action route will choose the appropriate method.

Routes has to be placed in app/init.php or vendor/phppe/*/init.php as extension initialization code gets called before the routing decision is made. It's too late to call PHPPE\Core::route() in a controller's constructor.

You can pass any class that can be autoloaded by PHP Composer to PHPPE\Core::route(), meaning the controller can be anywhere under vendor/ directory.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

//plain arguments
PHPPE\Http::route( "myspecurl/([^/]+)/?(.*)", "MyApp", "myspecaction", "post,@admin" );

//json friendly format
PHPPE\Http::route( [
	"url" => "myspecurl/([^/]+)/?(.*)",
	"name" => "MyApp",
	"action" => "myspecaction",
	"filters" => [
		"post",
		"@admin"
	)
] );

//compact format for adding multiple routes at once
PHPPE\Http::route( [
	[ "myspecurl/([^/]+)/?(.*)", "MyApp", "myspecaction", ["post", "@admin"] ],
	[ "myspecurl2/([^/]+)/?(.*)", "MyApp", "myaction", ["loggedin"] ],
] );

//if you specify only the class, default action routing will apply
//the class can be loaded via composer's autoload as well
PHPPE\Http::route( "tests", "\PHPPE\Tests" );

As you may noticed in the examples above you can add filters to routes. If a filter fails, the URL will be automatically skipped. If all routes failed, and there was at least one that because of a filter, the url will be routed to 403 (access denied) page. When no routes matched at all, PHPPE\Core::run() will fall back to default route.

Default route

(base) / application [ / action [ / item ] ]

Default application

1. PHPPE\Ctrl\applicationAction
2. PHPPE\Ctrl\application
3. PHPPE\application
4. PHPPE\Content

First PHPPE will check whether the url is handled by an action specific controller. Next, it will check if it's handled by a controller or service class with several action methods. As a last resort fallbacks to PHPPE Content built-in action, which in turn will look for a content in database.

Default action

After executing controller class constructor, the caching instance will be consulted. If the page can be found in cache, action method won't be called. See caching for details. On the other hand, if it's not in cache, or page generation is forced by setting PHPPE\Core::$core->nocache in constructor, action method will be executed.

If you omit action parameter from URL rule, the action() and default action() methods will be looked up in the specified class.

Fallback action

If no application class found, run() will fallback to act as a Content Server, serving pages from database. Contents are generated on a dedicated server by the PHPPE CMS extension. If a page for the url found, it will populate the application's properties and sets the template to be used in view. In this case action method will provide a way to execute code from database, unless it's turned off by the PHPPE\Core::$core->noctrl flag.

Templater

After an action method returns (either called by matching, default or fallback) the templater takes control over, unlike other frameworks where controller has to call the templater.

Special URLs

URL Filters

You can add one or more filters to pages and fields on a form, not to mention the menu items. Most common case to apply as fourth argument to PHPPE\Http::route().

If a filter name starts with a '@', the user will be checked against the given ACE, otherwise \PHPPE\Filter\name::filter() will be called that returns a boolean value.

For an ACL list, use pipe to concatenate ACEs (like "@siteeditor|siteadmin"). If you would like to describe user has A and at least one of B or C, that would be "@A,@B|C".

PHPPE Core has four built-in filters:

• get - checks if the url was called with HTTP GET method
• post - checks if the url was called with HTTP POST method
• csrf - checks validity of a request when user tries to send a transaction, in other words save a form (Cross Site Request Forgery)
• loggedin - this filter redirects user to login page if not logged in

You can find filter examples in the API section.

Models

Model classes are inherited from PHPPE\Model. This way they will have three methods at least:

A typical example of a model is PHPPE\Users class.

Controllers

These classes are the glue that connects HTTP requests with models and a view.

An application (a PHPPE extension) can house several controllers, and each controller can hold code for several (but at least one) action handler.

Using PHPPE\Http::route() you can specify any controller and action to run for a specific url, or you can rely on default route to choose the controller and action method.

Controllers are located under the ctrl/ directory of every extension (and in your application as well). PHPPE gives you freedom on how you want to organize them, you can have one single controller class with more action handlers, or separate classes for each action. There's no inheritance involved, but controllers should reside in the PHPPE\Ctrl namespace.

1

\PHPPE\Http::route( "myurl", "MyController", "action" );

1
2
3
4
5

namespace PHPPE\Ctrl;
class MyController {
    //default action
    function action( $item ) {}
}

Views

Unlike other frameworks, in PHPPE the templater is not used to generate the entire output. Instead you've library calls to add links, meta tags, menus, stylesheets and javascripts to it. The templater is limited to the area between <body> and </body> only. This way PHPPE can manage asset aggregation and minification transparently.

Template used

The view is generated using the first template found in order:

1. PHPPE\Core::$core->template (unless application overwrites it, it defaults to application_action)
2. application_action
3. application
4. 404

If the application clears the template's name, the view layer will not be used at all, and therefore there'll be no 404 page either.

Template lookup

Each of the above list will be looked up in:

Using the templater

<!foreach array>
 ...
<!/foreach>

<!if expression>
 ...
[ <!else>
 ... ]
<!/if>

<!include view>

<!template>
 ... <% ... > ...
<!/template>

<!form objectname
  [ cssclass
    [ app/action
      [ onsubmitjs ] ] ]
>
 ...
</form>

<!date expression>

<!time expression>

<!difftime expression>
<!difftime tstamp1 tstamp2>

<!L textkey>

<!dump field>

<!app>

Expressions

//variable, expression or object field.
<!=expression>

No php allowed in expressions; you have to convert both property names ($obj->field) and associative arrays ($obj["field"]) to obj.field. Also note that there's no "greater than" operator, if you plan to use, swap sides of the expression and use "less than" operator. Besides of these it works like php, you can use number_format() and sprintf() functions as well (<!=sprintf("%12d",obj.numval*2+10)>, <!=myobject.mymethod(myobject.field3)>).

Inside <foreach> iteration blocks you can use a couple special variables as well:

• KEY = key of the array you're iteration on;
• VALUE = current array element if it's a scalar value without fields;
• IDX = iteration counter;
• ODD = true if IDX is odd (for nice easy readable, striped blocks)

Calling PHPPE Core library would require the prefix "core.", like

<!=(core.isinst("MyAddOn") && MyAddOn.mymethod())>
<!=core.getval("core.lib()")>

You can access the framework object's properties and methods with

Templater Add-Ons

Both field types and widgets are extended from PHPPE\AddOn class. The difference is how you refer to them in view templates.

//create an add-on instance for a form field.
<!field [ @acl ] [*]addon [ ( args ) ] objectname.fieldname [ attributes ]>
<!var [ @acl ] [*]addon [ ( args ) ] objectname.fieldname [ attributes ]>
<!widget [ @acl ] [*]addon [ ( args ) ] instancename [ attributes ]>
<!cms [ @acl ] [*]addon [ ( args ) ] app.propname [ attributes ]>

The reason for having four different kind of tags is to ease the creation for templates. For example with "var" you can display and edit a database record with a single template, so you won't have to create more templates for the same object. Similarly "widget" can be used to place an AddOn on the page regardless whether it's showing it's face or it's configuration. Both will use the same template.

The "field" tag will call the edit() method of the Add-On to render html content, regadless if there's a show() method or not. If you use "var" instead of "field", the show() hook will be called, edit() will be limited to edit mode only ($_SESSION['pe_e'] is true). If edit() hook is undefined, fallbacks to show(). If neither show() method found, "var" will output raw value, while "field" reports an error.

Widgets works just like "var", show() method should draw it's face, and edit() method displays a widget configuration form (optional, if $_SESSION['pe_c'] is true).
Technically "var" and "widget" are the same, the difference is limited to the meaning of what edit() renders, and when edit() gets called instead of show().

The "cms" tag will use edit() only if page opened in Content Editor. Normally it won't display anything unless it's marked mandatory (by an asterisk prefix in type), when it will use show(), just like "var". Also you can specify editor mode only templater blocks with "<!if cms>...<!/if>", see conditional block above. The "cms" tag is special in a way as it accepts extra dimension parameters to help intergation of the editor area into your layout more smoothly.

//autodetect editor position and size
<!cms
//place editor at icon in given size (pixels)
<!cms(width,height)
//display editor as a modal occupying given percentage of the screen
<!cms(0,0,percentage)

Comparision

It's easy to expand functionality with new Add-Ons, see tutorial for an example.

Cache Management

Caching is configured in phppe/config.php:

If memcached (or any other cache alternative) can be accessed, raw templates will be always cached, and there's no flag to turn that off.
Without nocache set, templater's output and assets will be also cached for 10 minutes.

Assets added by either PHPPE\View::css() or PHPPE\View::jslib() will be aggregated into two files in memory to save HTTP requests as well.

If you want to support changing content along with dynamic data, your application must be aware. You should look for new data in your app's constructor, and set PHPPE\Core::$core->nocache to avoid view's caching and force regenerating the output.

Example

1
2
3

'cache' => "127.0.0.1:11211",		//set up memcache connection
'nocache' => false,			//allow caching of generated output by default
'noaggr' => true,			//turn static content aggregation off

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

namespace PHPPE\Ctrl;
//your application's controller class
class MyAppController extends MyApp {
	public $data;

	//in constructor look for new data
	function __construct( ) {
		//if new data available, disable caching of output
		if( MyModel::getNumberOfNewItems() > 0 )
			PHPPE\Core::$core->nocache = true;
	}

	//WARNING: actions not called when output is cached!
	function action( $item ) {
		$this->data = MyModel::getItems();
		//when returning from this method, templater will
		//regenerate output using $data and raw templates
		//and will save the result into the cache
	}
}

Alternatives

You can use any other caching mechanism, if the extension is in PHPPE\Cache namespace, and has at least two methods:

1
2

function get( $key ) { }
function set( $key, $value, $compressed = true, $ttlinsec = 0 ) { }

Zero ttl means keep key in cache forever.
If the caching mechanism requires connection, it must be initialized in the constructor, using PHPPE\Core::$core->cache as argument.

* * * * * php public/index.php cron minute

Programming

There's a wrapper class to hide all the details of cache implementations, see PHPPE\Cache.

Clustering

On workers, install Pack and ClusterCli. On the management server, Pack, ClusterSrv and CMS.

Installation

Management nodes

$ composer require phppe/ClusterSrv

Setup

The cron minute will supervise if ClusterSrv is running. You can also trigger it from command line:

$ php public/index.php cluster server

Query status

That's simple as

$ php public/index.php cluster
This node is: 10.0.0.1 MASTER
Cluster nodes:
 Id              Type        Load  Last seen            Last viewed          Name
 --------------  ---------  -----  -------------------  -------------------  -----------------------------
*10.0.0.1        master         0  2016-09-28 02:06:20  2016-09-30 01:04:42  admin1.localdomain
 10.0.0.2        slave          0  2016-09-28 02:06:20  2016-09-30 01:04:42  admin2.localdomain
 10.0.0.3        lb             0  2016-09-28 02:06:20  2016-09-30 01:04:42  ns1.localdomain
 10.0.0.4        worker         0  2016-09-28 02:06:20  2016-09-30 01:04:42  worker4.localdomain
 10.0.0.5        worker         0  2016-09-28 02:06:20  2016-09-30 01:04:42  worker5.localdomain
 10.0.0.6        worker         0  2016-09-28 02:06:20  2016-09-30 01:04:42  worker6.localdomain

cluster help      - this help
cluster status    - prints the current status
cluster server    - checks management daemon (called from cron)
cluster takeover  - force this management server to became master
cluster flush     - flush worker cache
cluster deploy    - push code to workers
cluster client    - (!) checks worker daemon (called from cron)
cluster bindcfg   - (!) generate bind configuration on lb worker

Load balancer

$ composer require phppe/ClusterCli

Setup

The cron minute will supervise if ClusterCli is running. You can also trigger it from command line:

$ php public/index.php cluster client

Tell ClusterCli that you want it to work as a load balancer by setting the name(s) of the subdomain(s) in

1

  'loadbalancer' => [ 'www', 'cdn' ],

Create a shell script under vendor/bin/cluster_lb.sh. That will receive a bind configuration file on it's stdin, and has to save it and restart a bind server of your choosing. The format can be modified in vendor/phppe/ClusterCli/views/bind.tpl. If possible you should use layer 2 balancing (like RFC 5798) instead of a DNS balancer for smaller latency times.

Query status

$ php public/index.php cluster
This node is: 10.0.0.3 LOADBALANCER

$ php public/source.php cluster bindcfg
; GENERATED FILE, do not edit!
$TTL	1d ; 1 day ttl
$ORIGIN example.com.
@  1D  IN  SOA ns1.example.com. hostmaster.example.com. (
			      2016093003 ; serial (unique to every hour)
			      5m ; refresh
			      15 ; retry
			      5m ; expire
			      5m ; nxdomain ttl
			     )
        IN  NS     ns1.example.com. ; in the domain
        IN  NS     ns2.example.com. ; external to domain
        IN  MX  10 mail.another.com. ; external mail provider
; server host definitions
ns1     IN  A      127.0.0.3    ; dns load balancer
admin   IN  CNAME  admin2
admin2  IN  A      127.0.0.1    ; current master
admin3  IN  A      127.0.0.2    ; standby slave
www     IN  A      127.0.0.4    ; worker #4
www     IN  A      127.0.0.5    ; worker #5
www     IN  A      127.0.0.6    ; worker #6

Worker

$ composer require phppe/ClusterCli

Setup

The cron minute will supervise if ClusterCli is running. You can also trigger it from command line:

$ php public/index.php cluster client

Query status

$ php public/index.php cluster
This node is: 10.0.0.6 WORKER

Automatic scaling

ClusterSrv will monitor for worker loads and will tell them to stop down or start a new if required. For that to happen, we'll have to do things first:

On workers

Make sure sudo is allowed for the following commands: poweroff, restart.

Make sure (openbase_dir) script is allowed to open and read /proc/loadavg.

On management node

Create a shell script vendor/bin/cluster_worker.sh, that should communicate with your VPS provider's API to start a new worker vm instance.

High Availability

You can start more load balancers, but change the name in bind.tpl for each.

As for management, ClusterSrv implements fail-over. That means that you can start more instances, but only one can be master at any given time. There may be a need to change master manually, for that run this command on one of the slave servers:

$ php public/index.php cluster takeover

Content Distribution

Contents are stored in the quorum database server. Workers cache the resulting html for subsequent use. That cache can be cleared with:

$ php public/index.php cluster refresh

Code Distribution

You can keep a master copy of your worker's document root on the management server. If you change that, you'll have to send it to the workers with:

$ php public/index.php cluster deploy

DataBase Administrator^DBA

Provides a low level web interface to the database.

You can list tables, search and edit records with it. It's purpose is not to be a fully featured tool rather to be a swiss-army knife for S.O.S. fixes in the database.

You need siteadm ACE to use the DataBase Administator.

Services

Every extension can have an init.php that holds initilization code. If that file returns an object instance, that's called a Service.
Services provide library functions to PHPPE, or can extend functionality by implementing event hooks.

If classname is not obvious, other parts of the system can ask for a service by calling PHPPE\Core::lib(servicename) which will return the instance.

1
2

//! return a class defined under Extension's libs/ directory
return MyService();

Sitebuilds

The frame concept

There's a special template in PHPPE, that can have an <!app> tag. This tag separates the page header (logo, header image etc.) from the page footer (copyright notice, impressum link etc.). So minimal frame is this tag alone. If you omit this tag, your application's output will not be included in the final output.

This frame usually describes the basic layout of the website: where's the menu, where's the navigation bar, where are the ads etc.

For AJAX loaded applications and popup windows you can turn the panel and the frame off, leaving the entire space to the application (full screen mode if you like) with

1
2

PHPPE\Core::$core->nopanel = true;
PHPPE\Core::$core->noframe = true;

Layouts

In the views table of the database there are special records marked by a site build name. These are the layouts that can be used as frame, one at a time. All of them must contain an <!app> tag.

With PHPPE CMS you can manage views on a nice web interface, and you can select one sitebuild to be used as frame with a single click.

Assets

Along with code, usually come some static file. They can be CSS stylesheets, imagery or client side JavaScript libraries. You don't have to mess them up in a single directory under "public/", PHPPE Core is clever enough to locate these files and proxies their contents. For that, the following URLs are reserved:

• (base)/css
• (base)/fonts
• (base)/images
• (base)/js

Each of these has a corresponding directory within every PHPPE extension. Your application's assets are handled defferently, as they are symlinked under "public/". This means that the static contents of your application will be served by the webserver directly without PHP involved. Extension's assets (located under "vendor/" which is not accessible by the webserver) and dynamicaly generated assets have to be proxied through PHP.

Adding assets to output

For that there are two corresponding methods to add links to output's head section and libraries before the body tag:

• PHPPE\View::css() to add stylesheets
• PHPPE\View::jslib() to add JavaScript libraries
• Images are linked in the page everywhere, so they don't need a function. Simply start every reference with "images/"
• Fonts are like images, reference them with "fonts/"

These should be called in init() method of Add-Ons or action handler classes. Don't call them in service intitialization, as the referenced assets would be included in every output even if they're not needed at all.

One subdirectory is supported for grouping assets, but only one level for performance (to speed up directory lookups).

Dynamic Assets

It's possible to generate assets on-the-fly. For that you'll have to append ".php" extension to the filename. When you refer these, do that without that extension, PHPPE is clever enough to handle them on it's own.

This way the output looks the same for both static and generated assets.

You don't have to do anything special in these php files, when they are included, PHPPE is already bootsrapped for you, so you can focus on generating the output. If cache is configured, by default the generated asset will be cached and served like any other static asset. If you want to disable that behaviour (for example you're generating an image with a changing counter on it), set the PHPPE\Core::$core->nocache flag and your code will be called every time the asset queried.

Contents

Content Server

PHPPE Core can serve contents (generated by PHPPE CMS) on it's own, but it uses a database table for that. The scheme is supplied by PHPPE Pack (vendor/phppe/Core/sql/pages.sql).

PHPPE\Content will look for pages if routing was unable to choose a controller.

Content Editor^{PHPPE CMS}

To be able to create and modify contents on a Content Server site, you'll need to install PHPPE CMS extension by copy'n'pasting one of these commands into your Terminal:

composer require "phppe/CMS"

mkdir vendor/phppe/CMS && curl https://bztsrc.github.io/phppe3/phppe3_cms.tgz | tar -xz -C vendor/phppe/CMS

It can be installed on a different server, and one CMS can manage several Content Servers. This way you can build up a scalable architecture that can serve huge loads with ease.

visitors  webmaster  (Browser Clients)
     \     /
  websrv+dbsrv       (Content Server,
      \___/           Content Editor,
                      and database as well
                      on a single machine)

           visitors        webmaster   (Browser Clients)
              |                |
      DNS load balancer        |
        /     |     \          |
       /      |      \         |
websrv1  websrv2 ... websrvN   |       (Content Servers)
       \      |      /       cmssrv    (Content Editor)
        \__   _   __/         /
             (_)  ___________/
      dbsrv  |_|                       (database server)

In scalable set up the webmaster (who is responsible for the contents) uses the cmssrv with Content Editor installed to manage the webpage. This should be done through a secure https channel protected by a firewall, so that nobody else could modify the contents. The Content Editor stores the changes to the database that resides on dbsrv over a sql connection. In the cheapest scenario database server and Content Editor can be installed on the same machine (although not recommended due to security considerations. Database server should not be accessible from outside).

Visitors are accessing the site on http(s) protocol targeting a load balancer. The load balancer forwards the http(s) request to one of the websrv instances that run Apache or nginx. The cheapest and simpliest solution is to use DNS load balancing, where the domain name resolves to several A records, each pointing to one of the websrv ip's. More professional load balancers can terminate ssl and forward plain http to save resources, and may also monitor the current load on websrv instances to route to the least loaded one.

All the websrv instances have the same document root and run PHPPE Core to act as a Content Server that in turn loads the content from dbsrv via sql connection. To speed up things ever more, Content Servers can cache the contents as well.

EplosCMS

There's also an extension to support pages generated by third party software. EplosCMS generates pre-constructed pages in the "pages/" directory, this extension read files from there and creates routing entries as they are referenced. You can install this extension with:

composer require "phppe/EplosCMS"

mkdir vendor/phppe/EplosCMS && curl https://bztsrc.github.io/phppe3/phppe3_eploscms.tgz | tar -xz -C vendor/phppe/EplosCMS

Event hooks

In PHPPE you don't set handlers by calling a method. Instead, you simply name your method after the event in your registered class.

Overview

Service initialization event

1
2
3
4
5
6
7
8
9
10
11
12
13

/**
 * Service init event handler
 *
 * @param config associative array
 * @return boolean, was initialization successful?
 */
function init($config)
{
	// PHPPE\View::menu() to add menu items
	// PHPPE\View::jslib() to add JavaScript libraries
	// PHPPE\View::css() to add custom stylesheets
	return true;
}

Extension diagnose event

1
2
3
4
5
6
7
8

/**
 * Extension diagnose event handler
 *
 */
function diag()
{
	echo("Hi\n");
}

Routing filter event

1
2
3
4
5
6
7

namespace \PHPPE\Filter;
class myFilter extends \PHPPE\Filter {
    function filter()
    {
	  return true;
    }
}

Route event

1
2
3
4
5
6
7
8
9
10
11

/**
 * Route event handler
 *
 * @param application classname
 * @param action method name
 * @return array optionally altered input
 */
function route($app, $method)
{
	return [ $app, $method ];
}

Controller action event

1
2
3
4
5
6
7
8
9

/**
 * Controller event handler
 *
 * @param application classname
 * @param action method name
 */
function ctrl($app, $method)
{
}

View event

1
2
3
4
5
6
7
8
9
10

/**
 * View event handler
 *
 * @param string html
 * @return optionally altered html
 */
function view($html)
{
	return $html;
}

Stat event

1
2
3
4
5
6
7
8
9

/**
 * Stat event handler
 *
 * @return html
 */
function stat()
{
	return "<img src='images/icon_ok.png'>";
}

Cron events

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

class myExtension extends \PHPPE\Ctrl {

    function cronMinute( $item ) {
	//here you can use the usual PHPPE environment. Don't forget to output text, not html.
	echo( L("Called.") . "\n" );
    }

    function cronQuaterly( $item ) {
	//do something here
	echo ( $item . "\n" );
	//most scripts will exit without calling the templater.
    }

    function cronHourly( $item ) {
	//if you want templater to continue, set a template manually in CLI scripts
	PHPPE\Core::$core->template = "cron_ncursestmpl";
    }
}

Add-On initialization event

1
2
3
4
5
6
7
8
9
10

/**
 * Add-On init event handler
 *
 */
function init()
{
	// PHPPE\View::addon() to register Add-On
	// PHPPE\View::jslib() to add JavaScript libraries
	// PHPPE\View::css() to add custom stylesheets
}

Add-On input validation event

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

/**
 * Add-On validation event handler
 *
 * @param string field name
 * @param mixed value passed by reference
 * @param boolean required
 * @param array arguments
 * @param array attributes
 * @return array of boolean and string
 */
static function validate ( $name, &$value, $required, $arguments, $attributes )
{
	return [
		true, /*boolean, expression to determine whether the value is valid*/
		"success" /*error message if any*/
	];
}

Add-On display events

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/**
 * Add-On display event handlers
 *
 */
function show()
{
	// display value or widget face
	return htmlspecialchars($this->value);
}
function edit()
{
	// display user input field or widget configuration form
	return "<input type='hidden' name='".$this->fld."' value='".htmlspecialchars($this->value)."'>";
}

JavaScript init event

Extensions

Installing an Extension without Manager or Composer

Assuming you're in your ProjectRoot. If not, type "cd (your DocumentRoot without public)". Check current working directory with "pwd".

Type one of these into your SSH Terminal:

$ mkdir vendor/(extension name) && curl (repository)/(extension tarball).tgz | tar -xz -C vendor/(extension name)

Query list of installed Extensions without Manager or Composer

Type into your SSH Terminal:

find vendor/phppe -name composer.json -print -exec sh -c "cat {} | grep -e \\\"version[^_]" \;

PHPPE Extensions Manager^{PHPPE Extensions}

The PHPPE Extensions Manager is a tool to install extensions over a web interface. It does not provide the same functionality as PHP Composer, so it's not recommended in development environments. Instead it's a comfortable and secure way to deploy tarballs remotely via web UI.

You need install ACE to use the Extensions Manager.

To install, copy'n'paste one of these into your SSH Terminal:

composer require "phppe/Extensions"

mkdir vendor/phppe/Extensions && curl https://bztsrc.github.io/phppe3/phppe3_extensions.tgz | tar -xz -C vendor/phppe/Extensions

php public/index.php --self-update

Configuring Manager

User login and Remote Access

If you have PHPPE\Users class installed with PHPPE Pack, there's little left to do, just grant "install" ACE to your user, and add "remote" configuration as an array to user's preferences. On the other hand if you're running a single user page without Users class, you'll need this to allow admin user login:

1

'masterpasswd' => password_hash("changeme", PASSWORD_BCRYPT),

In lack of user preferences, you'll also need

1
2
3
4
5
6
7

return [
	"host" => "(your server name)",
	"port" => "(your ssh port, optional)",
	"user" => "(your username)",
	"path" => "(your ProjectRoot, DocumentRoot without 'public')",
	"identity" => "(your private key)"
];

For example:

1
2
3
4
5
6
7
8
9
10
11

return [
	"host" => "localhost",
	"port" => 22,
	"user" => "bzt",
	"path" => "/var/www/phppe3_test",
	"identity" => "-----BEGIN RSA PRIVATE KEY-----
MIIBdgIBABKBhQCdlCD+2At47+LwSk7w1rDISnj3n9QYjCKjzuj+UtI5S4vC0Dbx
     [...]
iCa3nxaMkW2qEmEPCd8=
-----END RSA PRIVATE KEY-----"
];

The path can be relative as well. Most common configurations are:

• public_html - if your user's home diretory has a link to the documentroot
• /var/www/your server name - absolute path to webserver directory
• /srv/www/your server name - alternative, also very popular webserver directory

This array will be loaded to PHPPE\Core::$user->data['remote'] and handled afterwards as if it would be a normal Users preference setting.

User private key

For security reasons, users are identified by keys. No password configured ever for remote access.

The identity field contains your private key, and you have to append it's public key pair to (user's home)/.ssh/authorized_keys. If you don't have a key yet, here's how to generate it:

$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/bzt/.ssh/id_rsa): Enter
Enter passphrase (empty for no passphrase): Enter
Enter same passphrase again: Enter
Your identification has been saved in /home/bzt/.ssh/id_rsa.
Your public key has been saved in /home/bzt/.ssh/id_rsa.pub.
The key fingerprint is:
6f:16:8a:27:54:cf:2e:6d:37:23:30:fc:4d:d7:a2:12 bzt@localhost

Now copy the content of /home/bzt/.ssh/id_dsa to configuration, and append /home/bzt/.ssh/id_rsa.pub to authorized_keys:

$ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

PHPPE Extensions Manager is capable of managing remote hosts as well, but in this case you'll have to append your key to the remote machine's authorized_keys file.

$ cat ~/.ssh/id_rsa.pub | ssh host -p port -l user 'cat >> ~/.ssh/authorized_keys'

Official repository

• https://bzt.github.io/phppe3/packages.json
• https://packagist.org/packages/bztsrc/phppe3

Adding third-party repositories

By default, PHPPE uses it's own repository, but you can add third-party extensions as well. You can configure repositories like

1
2
3
4

'repos' => [
	"http://my.repo.com/phppe3",
	"http://another.repo.com/stuff/phppe3"
];

To provide your own repository, see Repository HOW-TO.

Usage

Now log in to your PHPPE site. You'll see an "Extensions" menu on the PHPPE Panel. Here you can

• install and bootstrap PHPPE Core on remote servers with a single click on Diagnostics
• search for extensions
• see what's installed
• check for new versions in repositories
• install or remove extensions
• upgrade or re-install extensions
• configure extensions

Screenshot

Extensions Repository HOW-TO

You'll need a plain simple webserver for that. Place the tarballs and the packages.json in DocumentRoot, and you're done.

Extension tarballs

Create gzipped tarballs with ".tgz" file extension of your extensions and add-ons. Omit leading directory, tar files should contain files relative to vendor/phppe/(extension)/.

Extension meta info

The first file in the tarball *MUST* be composer.json. PHPPE Extensions Manager will check it and refuses to install tarballs without valid meta info. This file is a standard PHP Composer json file, with additional elements:

{
	"name" => name of your extension,
	"version" => human readable version of your extension,
	"version_normalized" => comparable version of your extension,
	"description" => description of your extension,
	"maintaner" => your name and email address,
	"license" => license you use for your extension, defaults to LGPL-3.0+,
	"type" => "library"
	"autoload" => autoload info
	"dist" =>
		"type" => "tar"
		"url" => link to the tarball
	"require" => dependencies

	"conf" => optional, configuration specification,
	"conf_X" => optional, translations for configuration keys,
	"price" => optional, integer price of your extension in EUR,
	"homepage" => optional, webshop's url where the user can buy your extension,
	"prio" => optional, priority when generating list in packages.json

}

The keys "name", "description" and "conf" can be translated by appending underscore and language code to them, like

{
	"name" => "phppe/something",
	"name_en" => "Some Extension",
	"name_hu" => "Valami Bővítmény",
	"description" => "English description, NOTE: NO _en suffix",
	"description_hu" => "Magyar nyelvű leírás",
	"conf_en" => "{ "host":"Host name", "port":"SSH Port" },
	"conf_hu" => "{ "host":"Szerver neve", "port":"SSH Port" },

}

Extension configuration

The configuration prototype (keys of the array returned by it's config.php) can be described in "conf" field. Labels for them will be translated, see above.

For example:

	"conf":{
		"host": "string(localhost)",
		"port": "integer(1,65535,22)",
		"user": "string(username)",
		"identity": "string",
		"path": "sting(/var/www/localhost)"
	},
	"conf_en":{
		"host": "Hostname",
		"port": "SSH Port",
		"user": "Username",
		"identity": "Identity file",
		"path": "ProjectRoot"
	},

Extension preview

This should be a 96 x 96 png picture or an svg image. Try to keep it small, below 8k. Use color palette or grayscale instead of RGB. Always use png tools such as TinyPNG to compress.

Preview picture is optional, if not included, default extension picture will be shown.

Versioning

Versions should be threefold, each number represents specific version in order

1. main. You should be library compatible within main versions
2. feature. Indicates feature release within main version
3. patch. Indicates patch level

For example:

0.0.0 - first beta release
0.1.0 - second version of beta release
1.0.0 - first stable release, usable for production
1.0.1 - first stable release with a security patch applied
2.1.3 - second main version with a feature release and three security patches

Upcoming feature and main releases required to include former security patches.

Repository index

{
    "packages" =>
	(extension) =>
		(version_normalized) =>
				content of composer.json
				"time" => last modification time in "yyyy-mm-dd HH:MM:SS" format
				"size" => size of the tarball in bytes
				"sha1" => hash of the tarball
				"preview" => optional, base64 encoded png or svg icon, generated from preview file

	(extension) =>
		(version_normalized) =>
				content of composer.json

	... more extension info may follow

}

Commertial Extensions

PHPPE does not include a shop for Extensions to avoid legal issues and taxing regulations in different countries.
PHPPE Extensions Manager merely helps commertial extensions with a token in download url during installation, but that's all.

If you specify "price" in your composer.json, then "homepage" must point to a webshop. PHPPE Extensions Manager will handle extensions with price like:

• the user will be redirected to "homepage", where you can handle the payment details
• after a successful payment, you must show the user a unique product key (the token)
• When the user wants to install the Extension from Manager, he/she will be prompted for that key
• During installation, tarball will be downloaded as "(repo url)/(extension name).tgz?key=sha256(product key)"
• Now it's up to you to check whether the given key is valid and you serve the request or deny it with a HTTP 403.

Coding Standards

To be extremely small (90k is not a plenty of space for a PHP code you can take my word on that), the Core is compressed. With this only exception, all other PHP files must follow PSR-2 Coding Style.

Comments and logging

It is strongly advised to write plenty of descriptive comments in your source. It is also highly recommended to put a lot of debug level PHPPE\Core::log() call, so that you'll get a clue what is your code doing when it's running.

Definitions

This document uses these notations consistently:

Class names

Class names follow StudyCaps. To clearly distinguish Add-Ons from other classes, they're in camelCaps, like "myWidget". Don't ever use underscore in your class names.

Method names

Method names are in camelCase. Again, don't use underscores in your method names.

Functions

Along with classes and methods, PHPPE Core also provides two widely used functions outside of it's namespace (which by the way are only wrappers around PHPPE properties and method calls) for simplicity and to save you typing:

• L() - PHPPE\Core::$l
• url() - PHPPE\Http::url()

The last two are often called in view templates.

Application or Extension?

As the framework allows controllers in applications (app) as well as in extensions (vendor/phppe/*), you may ask which one to use for your project?
Short answer: application. If you later on plan to use your code on several sites, it's easy to convert it into an extension as they share the same directory structure. The only difference is that an extension must be inside PHPPE namespace, an application is not limited by that.

Benchmarks

PHPPE performance is a very important thing. Therefore you'll find a built-in benchmarker.

Accumulate data

Append "?benchmark" to the page's url you want to measure. Reload it several times, more samples are the merrier.

Displaying the results

PHPPE Developer extension ships a nice web interface to aggregate and display the collected data. If everything went well, you should see something similar to this:

Developer Templates^{PHPPE Developer}

Files

The templates can be found in vendor/phppe/Developer/templates/ directory. Each file has a JSON header and an optional payload.

    {
        "desc_(lang)": "Description in the given language",
        "args": [ array of variable names ],
        "dirs": [ array of directory names to create ],
        "package": [ "template":{variable overrides} ],
        "file": "file/to/write",
        "append": "file/to/append/to"
    }
    payload

Description is one line long. Arguments are inherited from the environment, and can be referenced as:

• @NAME@ upper case
• @name@ lower case
• @Name@ ucfirst

With "dirs", you can create additional empty directories. Note that directories to files are generated automaticaly.

To include other templates, use the "package" keyword. You can override variables passed to the template.

Finally, one of "file" or "append" may exists. Former creates a new file out of payload, the latter one appends the payload to an existing content.

The payload is parsed, and all variables will be subtituted. You also have a handful of build-in variables:

• @@LICENSE large file header, LGPL license block
• @@BRIEF short file header
• @@USERNAME the logged in user's name
• @@RFCDATE date and time in RFC format
• @@ISODATE date and time in ISO format
• @@DATETIME date and time in internet format
• @@TIMESTAMP seconds since Epoch

You're allowed to use variables in the JSON with all right side expressions as well.

Example

    {
        "desc_en": "Example template",
        "args": [ "extension", "class" ],
        "file": "vendor/phppe/@Extension@/libs/@Class@.php
    }
    // This is a payload for @EXTENSION@.
    // Author: @@USERNAME, @@RFCDATE
    class @CLASS@ {
    }

Developing in PHPPE^{PHPPE Developer}

You see, just like most of the developers, I'm a lazy one. I'd rather spend an hour developing a small utility for a simple task knowing it will be at hand next time needed, than repeating the same process over and over again. So one of the main goal was to make life easier and development effective. Simple, consistent directory structure, useful API, following the standards like PSR-2 etc. So even if you don't want to contribute to the framework, just using it or writing your own Extensions, it's worth installing the Developer package!

To install, copy'n'paste one of these into your SSH Terminal:

composer require "phppe/Developer"

mkdir vendor/phppe/Developer && curl https://bztsrc.github.io/phppe3/phppe3_developer.tgz | tar -xz -C vendor/phppe/Developer

Recommendation on environment

PHPPE suggests 3 layers:

1. Development: running locally on developer's machine
2. Staging: a separate test environment with latest master branch
3. Production: preplanned updates

Web based utilities

Tests

Provides a PHPUnit compatible test environment. This allows you to run tests from a browser, but nothing more: it's not as featureful as PHPUnit, for example it cannot generate code coverage reports.

The PHPUnit_Framework_TestCase compatibility class can be found in vendor/phppe/Developer/libs/phpunit.php, and thanks to autoloading, it will be used transparently if the real PHPUnit class not found.

The advantage over PHPUnit is that it scans all extensions for test cases, so you will see all of them in one place and can run all at once.

Benchmark

Developer ships a nice and pleasant reporting tool for visualizing benchmark data. It aggregates the accumulated samples and shows the result on human readable charts.

Command line utilities

Create utility

This is the one that probably you'll use the most. It's a small templater to generate different files for the PHPPE environment. The templates can be found in vendor/phppe/Developer/templates/ directory, and you can add new ones any time you want. The format is plain simple, just take a look into one. Templates can be listed if you don't provide template name:

$ php public/index.php create
Usage:
  php public/index.php create <template> [arg1 [arg2 [...]]]

Template can be one of:
  action              action template
  addon               creates a view addon (widget)
  composer            create composer.json package information
  config              configuration file
  controller          controller template
  extension           create an extension
  filter              url filter template
  init                extension initialization
  lang                configuration file
  lib                 library template
  model               model template
  phpunit.xml         creates xml configuration for PHPUnit
  route               adds a new route
  scheme              SQL table scheme
  test                test case for a class
  update              SQL update
  view                create a view

As you can see, there's a template for almost everything you'll need. For example if you want to create a new extension, just name it, and the rest will be taken care of for you.

$ php public/index.php create extension MyService
Writing vendor/phppe/MyService/composer.json
Writing vendor/phppe/MyService/config.php
Writing vendor/phppe/MyService/init.php
Writing vendor/phppe/MyService/sql/myservicemodel.sql
Writing vendor/phppe/MyService/lang/en.php
Writing vendor/phppe/MyService/libs/MyService.php
Writing vendor/phppe/MyService/libs/MyServiceModel.php
Writing vendor/phppe/MyService/ctrl/myservice.php
Writing vendor/phppe/MyService/view/myservice.tpl
Writing vendor/phppe/MyServiceDev/tests/MyServiceTest.php
Writing vendor/phppe/MyServiceDev/phpunit.xml

Tests

The testing framework also available from CLI.

$ php public/index.php tests
Test boundle        Avg.time #Tests   Last run             Result
------------------- -------- -------- -------------------- ----------
MultilingualTest    0.0002s    2 /  2 2016-06-01 00:46:38  OK
SystemTest          0.2199s   55 / 55 2016-06-01 00:46:38  OK
AddonTest           0.0028s   40 / 40 2016-06-01 00:46:38  OK
RoutingTest         0.0208s   22 / 22 2016-06-01 00:46:38  OK
CacheTest           1.3239s   18 / 18 2016-06-01 00:47:15  OK
HttpTest            1.0810s   16 / 16 2016-06-01 00:46:40  OK
ConvertTest         0.0035s   23 / 23 2016-06-01 00:46:40  OK
DataSourceTest      0.0152s   50 / 50 2016-06-01 00:46:40  OK
TemplaterTest       0.1184s   82 / 82 2016-06-01 00:46:40  OK
PictureTest         0.4101s   30 / 30 2016-06-01 00:46:41  OK
DBTest              0.0047s   28 / 28 2016-06-01 00:46:41  OK
EmailTest           2.0121s   13 / 13 2016-06-01 00:46:43  OK
RegistryTest        0.0055s    6 /  6 2016-06-01 00:46:43  OK
UsersTest           0.0001s    2 /  2 2016-06-01 00:46:43  OK

shows the latest results, and you can run one or all test with:

$ php public/index.php tests run testfile
$ php public/index.php tests run

Pretty format

You can use this utility to format all your PHP sources in an extension to PSR-2 Coding Style.

$ php public/index.php pretty extension

Lang utility

It is a useful helper that scans your extension directory looking for translation references.

$ php publix/index.php lang extension

It can also merge the result with an existing language dictionary, prefixing unnecessary items by //-.

$ php publix/index.php lang extension languagecode

If you want to save the results, it can be done as easy as

$ php publix/index.php lang extension languagecode --write

DataURI utility

This small tool will generate data URI for images or icons.

$ php publix/index.php datauri file

Mkrepo utility

This small tool is very useful if you create your own repository let's say for your company's applications. This will scan all extensions under vendor/phppe/ directory of your developer environment collecting information from composer.json files. If source changed, it re-generates tarballs and saves packages.json as described in Repository section of this document. Now all you have to do is copy the latter along with the tarballs onto a webserver, specify the url in your production server's configuration and your deployment system is good to go!

$ php public/index.php mkrepo
Scanning for packages: 20 found
  CMS:                tgz  OK
  ClusterCli:         tgz  OK
  ClusterSrv:         skip OK
  CookieAlert:        skip OK
  Core:               tgz  OK
  DBA:                skip OK
  DataLibrary:        skip OK
  Developer:          tgz  OK
  EplosCMS:           skip OK
  Extensions:         tgz  OK
  GPIO:               tgz  OK
  Gallery:            skip OK
  GeoLocation:        skip OK
  POS:                skip OK
  YouTube:            skip OK
  bootstrap:          skip OK
  bootstrapcdn:       skip OK
  og:                 skip OK
  spectrum:           skip OK
  wyswyg:             skip OK
Saving packages info: OK

Minify utility

It's job is to compress the human readable, commented public/source.php into public/index.php, a minified, production ready format and to update the documentation you're reading now. It's also fires a minify event to compress 3rd party files, although PHPPE Core ships with an on-the-fly js and css minifier.

$ php public/index.php minify
Compressing index.php: aa1c80932e73551a9816f7b84fabe43622c5adf4 80782 (0) OK
Updating documentation: OK

Classic Hello World! Tutorial

Simpliest

We'll only use view layer, no controller at all. If PHPPE does not find any application and controller, it will only serve the view. This behaviour is ideal for pages like About Us and Impressum. Default routes apply here.

<h1>Hello World!</h1>

Now open a browser tab and go to (your homepage)/helloworld url to see the result.

Bit more

A very minimal application, with only one controller. The view here refers to an application property.

<h1><!=hello></h1>

The application does not set any route, it uses the standard class naming convention for default routing. Also, action uses default action route.

1
2
3
4
5
6
7
8
9

namespace PHPPE\Ctrl;
class HelloWorld {
	public $hello;

	function action( $item )
	{
		$this->hello = "Hello " . ( $item ? $item : "World" ) . "!";
	}
}

As a PHPPE Extension

Assuming we want to serve the page in an arbitrary PHPPE Extension.

<h1>Hello World!</h1>

This time we'll set a routing rule for that, because the url does not align with file and class naming. It has to be done in the extension's initialization code.

1

PHPPE\Http::route("helloworld", "MyExtension", "myAction");

Here's the controller, that sets the template's name for the view. No default action route here, we've specified the action method with route.

1
2
3
4
5
6
7

namespace PHPPE\Ctrl;
class MyExtension {
	function myAction($item)
	{
		PHPPE\Core::$core->template = "myView";
	}
}

As a widget

Here we'll create a widget to display "Hello World". View refers to our widget without any specific controller.

<!widget helloworld>
   - or -
<!field helloworld obj.field>

This will be the template that refers to our widget. Without reference, our widget never get's loaded.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

namespace PHPPE\AddOn;
class helloworld extends \PHPPE\AddOn {
	function init()
	{
		//! register our add-on
		PHPPE\Core::addon( "helloworld", "Hello World! Tutorial" );
	}

	function show()
	{
		return "Hello " . ( $this->value ? $this->value : "World" ) . "!";
	}

	function edit()
	{
		return "Hello <input type='text' value='" . htmlspecialchars($this->value) . "'>!";
	}
}

Now we have a widget face to draw, and a configration "form" where we can set who to greet.

Routing Tutorial

Controllerless route

This is the simpliest, the view will be directly mapped to the url. For an example, see Hello World! tutorial.

Default application

If no route given, or neither of them applies, PHPPE will fallback to default route. This is not the scope of this tutorial either.

Specify application

Adding application to routes, but still relying on default action route. See PHPPE\Http::route() documentation on how to specify routes.

1

PHPPE\Http::route( "myurl", "MyApp" );

The corresponding controller:

1
2
3
4
5
6
7

namespace PHPPE\Ctrl;
class MyApp{
	function action($item, $item2="")
	{
		//! something
	}
}

This will be served when (base)/myurl called. If you enter (base)/myurl/myaction in the browser, PHPPE will look for the method myaction($item) in this class first, then fallbacks to action($item).

Specify action method too

1

PHPPE\Http::route( "myurl", "MyApp", "myAction" );

The corresponding controller now uses a custom method name for action:

1
2
3
4
5
6
7

namespace PHPPE\Ctrl;
class MyApp{
	function myAction($item)
	{
		//! something
	}
}

Using custom arguments

This time we'll use pharenthesis in url regexp. Each corresponds to an action method argument:

1

PHPPE\Http::route( "myurl([0-9]*)/([a-z]+)", "MyApp", "myAction" );

And the controller:

1
2
3
4
5
6
7

namespace PHPPE\Ctrl;
class MyApp{
	function myAction($someNumber, $someLetters)
	{
		//! something
	}
}

Without pharenthesis, the url will be splitted up by slashes '/', and each passed as an argument.

(base) / app / action / item:

1

function action($item)

1

function action($item1, $item2)

Specifying filters

You can add a filter list as fourth argument to PHPPE\Http::route(). As any other list in PHPPE, it can be a comma separated string list or an array.

Filters that starts with a '@' excpets the user to have an ACE, others refer to a boolean logic placed in PHPPE\Filter\name::filter().

1
2

PHPPE\Http::route( "myurl([0-9]*)/([a-z]+)", "MyApp", "myAction", "@loggedin,post" );
PHPPE\Http::route( "myurl([0-9]*)/([a-z]+)", "MyApp", "myAction", ["@loggedin", "post"] );

Normally you would use one action handler for each url, and check for csrf-valid form post in there with PHPPE\Core::isBtn(form name). But, because PHPPE gives you maximum flexibility, you can also have a separate method:

1
2

PHPPE\Http::route( "myurl([0-9]*)/([a-z]+)", "MyApp", "myGetAction", "get" );
PHPPE\Http::route( "myurl([0-9]*)/([a-z]+)", "MyApp", "myPostAction", "post" );

What's more, if there's only one form on your page, you can spare the formentioned isBtn() call as well:

1

PHPPE\Http::route( "myurl([0-9]*)/([a-z]+)", "MyApp", "myPostAction", "post,csrf" );

Application Tutorial

This tutorial will show you a typical application page. It will teach you how to create a form, tide it to an object so that their values get filled in automatically, and finaly how to retrive the user provided data with validation.

Let's assume we're using the url (base)/tutorialapp and (base)/tutorialapp/myaction. For details see routing. In this tutorial, it's enough to know we're relying on default routing.

Now, create the views for our urls with forms in them.

Tutorial default action's view
<!include errorbox> <!-- include a box to show error messages -->
<!form tutobj> <!-- assign form to an object -->
<!field text tutobj.field1>
<!field num tutobj.field2>
<!field update>
</form>

Tutotiral myaction view
<!form tutobj>
<!field text tutobj.field1>
<!field update>
</form>
<!form tutobj2>
<!field num tutobj2.field1>
<!field update Save>
<!field update Save_and_New>
</form>

And here comes the controller.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

namespace PHPPE\Ctrl;
class TutorialApp {
  public $tutobj = null;
  public $tutobj2;

  function action( $item ) {
    //! This flag is set on valid form submit once,
    //! making the transaction unrepeatable.
    if ( PHPPE\Core::isBtn() ) {
        //! Add an extra validation rule to some field
        PHPPE\Core::validate('tutobj.field2', 'myvalidator');
        //! Get the form fields and their values from user request.
        //! This will call field validators automatically.
        $this->tutobj = PHPPE\Core::req2obj('tutobj');
        //! Here you can force more complex validation or business logic if you like
        if ( $this->tutobj->field1=="" && $this->tutobj->field2==1 )
            PHPPE\Core::error( L("Validation failed."), "tutobj.field1" );

        //! If passed validation, we can save the data in database
        if ( !PHPPE\Core::isError() ) {
            //! Log what we're going to do
            PHPPE\Core::log('A', "Saving " . PHPPE\Core::obj2str($this->tutobj), "tutorialapp" );
            //! This should be in a Model, but this is a basic tutorial
            PHPPE\DS::exec( "INSERT INTO tutorialapp SET " . PHPPE\Core::obj2str( $this->tutobj ) . ";" );
            //! To avoid "Page expired" popups, you have to redirect user here
            PHPPE\Http::redirect();
        }
    }
    //! Here's the right place to load object from database.
    //! But only if the object is not full with user input that failed validation.
    if ( $this->tutobj === null && !empty($item) )
        //! This should be in a Model, but this is a basic tutorial
        $this->tutobj = PHPPE\DS::fetch( "*", "tutorialapp", "id=?", "", "", [ $item ] );
  }

  function myaction ($item) {
    //! only for the first form
    if ( PHPPE\Core::isBtn( "tutobj" ) ) {
        //! This is our own $tutobj, differs from action()'s.
        $this->tutobj = PHPPE\Core::req2obj( 'tutobj' );
    }
    //! only for the second form, and only if second button pressed
    if ( PHPPE\Core::isBtn("tutobj") == 2 ) {
        //! another form
        $this->tutobj2 = PHPPE\Core::req2arr( 'tutobj2' );
  }
}

Service Tutorial

Configuration

1
2
3
4

//Configuration
return [
    "dosomething" => true
];

Translations

1
2
3

return [
    "myservice_helloworld" => "Hello World: "
];

Initialization

The initialization file will be loaded for each extension. This is the place to set routes and return service instance:

1
2
3

<?php
PHPPE\Http::route("myservice/myaction/(0-9]+)/([a-z]+)", "MyService", "myMethod");
return myService;

Service Provider class

These class will be used by applications for services. It also acts a controller.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

<?php
class MyService {
    public $version = "1.0.0";
    private $dosomthingextra = false;

    //! some service your extension provides
    function exampleService( $a, $b, $c ) {
	return ( L("myservice_helloworld") . round( $a + $b - $c ) );
    }

    //! initialize our service. This method gets config.php as argument
    function init($cfg)
    {
	//! Register our service with dependency check
    //! this is not a must, it's enough to return an instance from init.php
	PHPPE\Core::lib(
		"MyService",		//! unix name
		$this,			//! service reference
		[ "DB", "Users" ],	//! dependencies
	);

	//! parse and validate your configuration here
	if ( !empty( $cfg["dosomething"] ) )
		$this->dosomethingextra = true;

	//! Do any extension specific tests here, use PHPPE\Core::log() to indicate errors
	if ( $this->dosomething ) {
	    //! Do feature specific tests here. If some test fails,
	    //! Use PHPPE\Core::log('E',...) for high level services,
	    //!	if your service called by applications directly (no other service depends on it)
	    //! Use PHPPE\Core::log('C',...) for low level services,
	    //!	if you expect other services dependenting on your service
	    ...
	    PHPPE\Core::log ( 'D', "Feature dosomething initialized." );
	} else
	    PHPPE\Core::log ( 'D', "Feature dosomething disabled." );

	//! register menu on PHPPE Panel
	PHPPE\View::menu( L( "MyService" ), "myservice/myaction" );
    }

    //! register a status icon on PHPPE panel
    function stat()
    {
	echo( "<img alt='That is me!" . ( $this->dosomething ? " ds" : "" ) . "'>" );
    }
}

In runtime you can access the service as simply as

1

PHPPE\Core::lib("MyService")->exampleService(1, 2, 3);

Widget Tutorial

See templater for details.

You can use this Add-On in view templates as:

<!widget tutorialwgt(1,2,3,4,5,6) instancename>

The "widget" tag calls show(), unless configuration mode ($_SESSION['pe_c']) is true in which case it renders configuration panel by calling edit() hook. The "var" tag calls show(), unless edit mode ($_SESSION['pe_e']) is true.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

namespace PHPPE\AddOn;
class tutorialwgt extends \PHPPE\AddOn {
    //! initialize - this is used by view template editor to get configuration for this widget
    //! also called right before the first "show" or "edit" method call once
    function init()
    {
	//! This code is instance independent, and called only once per page generation
	//! Include widget specific stylesheet
	PHPPE\View::css( "tutorialwgt.css" );
    }

    //! function to draw widget face
    function show( )
    {
	//! Include widget's JavaScript - has to be done here since it requires instance name
	PHPPE\View::jslib( "tutorialwgt.js", "pe.tutorialwgt.init('" . $this->name . "');" );
	//! $this->args = [ 1, 2, 3, 4, 5, 6 ];
	//! $this->attrs = [ $opts ];
	return "face";
    }

    //! function to create widget configuration form
    //! OPTIONAL, leave it empty if there's no configuration at all
    function edit( ) {
	return "<input type='text' onchange='tutorialwgt_saveconfig();' class='reqinput' ".
	    "name='" . $this->fld . "_cfgopt1' value=''><br>\n".
	    "<input type='check' onchange='tutorialwgt_saveconfig();' name='" . $this->fld . "_cfgopt2'> ".
	    L( "tutorialwgt_cfgopt2" );
    }

}

Setting up PHPPE on Raspberry Pi

Step 1: install raspbian

This is quite straightforward. Download image and use dd utility. You'll need at least stretch for PHP 7.0.

Step 2: install packages

You'll need these:

# apt-get install lightdm nginx php7.0-cli php7.0-fpm php7.0-opcache php7.0-apcu php7.0-gd php7.0-sqlite openbox chromium

Many of these may have already been installed on your Raspberry, and you can choose alternative db drivers like php7.0-pdo_mysql as well. For jessie PHP 7 backports, you'll find a lot of resouce on the internet, just google. Note that jessie may not include chromium, so you'll have to use this for RPi2:
https://launchpad.net/ubuntu/precise/armhf/chromium-browser
https://launchpad.net/ubuntu/precise/armhf/chromium-codecs-ffmpeg-extra

Step 3: configure nginx

You can find many tutorials on how to do this, but here's a brief configuration:

server {
	listen 80 default_server;
	root /var/www/localhost/public;
	server_name _;

	location / {
		try_files $uri $uri/ =404;
		index index.php;
		if (!-e $request_filename){
			rewrite ^(.*)$ /index.php;
		}
	}
	location ~ \.php$ {
		include snippets/fastcgi-php.conf;
		fastcgi_param  SERVER_NAME $host;
		fastcgi_pass unix:/var/run/php-fpm.sock;
	}
}

echo "<?php phpinfo();" >/var/www/localhost/public/index.php

systemctl enable nginx
systemctl start nginx

Step 4: grant access for GPIO

Add webserver's user to gpio group:

# addgroup www-data gpio

Also, you should add /sys/class/gpio and /proc/cpuinfo to open_basedir in your php.ini file as GPIO Extension uses the sys kernel interface and it detects the pin layout from the revision number.

Step 5: set up automatic login

autologin-user=pi
autologin-user-timeout=0

Step 6: set up full screen browser

export DISPLAY=":0"
xset s off
xset s noblank
xset -dpms
xdotool mousemove 8192 8192
openbox --sm-disable &
sudo bash -c "echo '[info] phppe: Starting fullscreen browser' >>/dev/console"
bash -c "while true; do (ps u|grep [c]hromium >/dev/null) || chromium -kiosk --incognito --start-maximized http://localhost; done"

<?xml version="1.0" encoding="UTF-8">
<openbox_config xmlns="http://openbox.org/3.4/rc" xmlns:xi="http://www.w3.org/2001/XInclude">
  <applications>
    <application class="*">
      <focus>yes</focus>
      <fullscreen>yes</fullscreen>
      <decor>no</decor>
    </application>
  </applications>
</openbox_config>

Step 7: install PHPPE

Step 8: configure PHPPE

'db' => "sqlite:data/sqlite.db",
'cache' => "apc",

Step 9: Reboot and enjoy!

You should see the PHPPE Self Test and Cheat Sheet page in fullscreen after reboot, served by your own Raspberry!

If you want to control your Raspberry Pi from your PHPPE Application (of course you do), you can use the GPIO Extension as simply as:

PHPPE\GPIO::mode(pin, 'in'/'out');
PHPPE\GPIO::get(pin);
PHPPE\GPIO::set(pin,true/false);

Setting up a cluster

For this tutorial, you'll need at least 5 virtual machines:

• one for a load balancer (ns1)
• one for the active management server (admin2)
• one for the standby management server (admin3)
• one for database (quorum4).
• one or more for application workers (worker5).

Step 1: install PHPPE

Install a webserver and PHPPE on all nodes, except database server.

php public/index.php --diag
$ curl https://bztsrc.github.io/phppe3/phppe3_core.tgz | tar -xz -C vendor/phppe/Core

On the management servers, also install Extension Manager, Content Editor and Cluster Server:

$ mkdir vendor/phppe/CMS && curl https://bztsrc.github.io/phppe3/phppe3_cms.tgz | tar -xz -C vendor/phppe/CMS
$ mkdir vendor/phppe/Extensions && curl https://bztsrc.github.io/phppe3/phppe3_extensions.tgz | tar -xz -C vendor/phppe/Extensions
$ mkdir vendor/phppe/MultiServer && curl https://bztsrc.github.io/phppe3/phppe3_multiserver.tgz | tar -xz -C vendor/phppe/MultiServer
$ mkdir vendor/phppe/ClusterSrv && curl https://bztsrc.github.io/phppe3/phppe3_clustersrv.tgz | tar -xz -C vendor/phppe/ClusterSrv

Finally, on the workers only Cluster Client:

$ mkdir vendor/phppe/ClusterCli && curl https://bztsrc.github.io/phppe3/phppe3_clustercli.tgz | tar -xz -C vendor/phppe/ClusterCli

Step 2: setup load balancing

On one of the workers modify the configuration and add subdomains you're want to load balance for:
vendor/phppe/ClusterCli/config.php:

1

  'loadbalancer' => [ 'www' ],

To allow PHPPE to refresh the DNS, create a shell script:
vendor/bin/cluster_lb.sh:

#!/bin/bash

exec >/var/lib/bind/myzone.conf
systemctl reload bind

Step 3: setup syslog

On all workers,
vendor/phppe/config.php

    'syslog' => true

Step 4: setup database connection

On all virtual machines,
vendor/phppe/config.php

    'db' => 'mysql:host=quorum4.myzone;dbname=phppe;charset=utf8@dbuser:dbpass'

On the database server, install and configure mysql or any other compatible database server (like mariadb). The best if your virtual machine provider has database service as well, like Amazon AWS. There you don't have to care about the database server.

Step 5: setup user session

On all workers, set up php.ini to store session data in database on quorum4.myzone.

Step 6: setup mailer

On all workers,
vendor/phppe/config.php

    'mailer' => 'db'

On the management servers, add
vendor/phppe/config.php

    'realmailer' => 'smtp:gmail-smtp-in.l.google.com'

Step 7: setup cluster supervisor

On all nodes, add to your crontab

*    * * * * /usr/bin/php /var/www/public/index.php cron minute

Step 8: testing high availability

On the standby management server, type

$ php public/index.php cluster takeover

Setting up a carousel

With the Gallery and CMS extensions it's pretty easy.

Loading the imagelist

First you'll have to load the names of the images. In order to do that, add a Local DDS to the page:

Name: carousel, SELECT: id,ordering, FROM: img_list, WHERE: list_id='@ID', ORDER BY: ordering

Displaying it

The Gallery ships a template, all you have to do is include it

    <!include carousel>

in your view where you want the carousel to appear. In CMS editor mode it will show a red icon, and if you click on it, you'll be able to select and rearrange pictures for the carousel.

PHPPE\Core

This is the main class of PHPPE. One singleton instance can be always accessed with PHPPE\Core::$core. Some properties are run-time generated, others can be configured.

Configurable properties

Generated properties

Methods

Session variables

To save values accross pages, the Core uses some SESSION variable.

PHPPE\ClassMap

This class takes care of autoloading. It's bullet-proof and PSR-0 / PSR-4 compatible. It stores the map in JSON format because in PHPPE webserver is not allowed to write PHP files. The map is automatically regenerated if an extension is installed or removed.

Files

.tmp/.classmap
.tmp/.acemap

Properties

Methods

PHPPE\Client

This class holds every information on client. It's populated consistently in CLI as well in web mode, so you don't have to bother yourself with different $_SERVER keys.

Properties

Methods

None.

PHPPE\Model

Object Relational Mapper prototype that correlates each record in database to a Model instance. Should not be used directly, instead inherited.

Properties

Methods

PHPPE\Ctrl

This is not a class, but a namespace for controllers. Each class in this namespace can have the following properties:

Properties

Methods

PHPPE\Http

HTTP protocol helpers.

Properties

None.

Methods

PHPPE\DS

DataSource services.

Properties

Methods

PHPPE\Cache

Wrapper around cache implementations.

Properties

Methods

PHPPE\Assets

This extension proxies assets under vendor directory. It also make use of cache if possible.

Properties

None.

Methods

PHPPE\View

The PHPPE templater.

Properties

None.

Methods

PHPPE\Tools

Set of useful file manipulation tools.

Properties

None.

Methods

PHPPE\Filter

Classes in PHPPE\Filter namespace that are inherited from the PHPPE\Filter class can be used as URL filters. For that it has only one argumentless method that returns a boolean success flag. You can apply filters to route calls as 4th argument, and they will be executed when the routing decision is made.

Properties

None.

Methods

Examples

1
2
3
4
5
6
7

class \PHPPE\Filter\get extends \PHPPE\Filter
{
  public static function filter()
  {
    return @$_SERVER[ 'REQUEST_METHOD' ] == "GET" ? true : false;
  }
}

1
2
3
4
5
6
7

class \PHPPE\Filter\post extends \PHPPE\Filter
{
  public static function filter()
  {
    return @$_SERVER[ 'REQUEST_METHOD' ] == "POST" ? true : false;
  }
}

1
2
3
4
5
6
7

class \PHPPE\Filter\csrf extends \PHPPE\Filter
{
  public static function filter()
  {
    return \PHPPE\Core::isBtn();
  }
}

1
2
3
4
5
6
7
8
9
10

class \PHPPE\Filter\loggedin extends \PHPPE\Filter
{
  public static function filter()
  {
    if (\PHPPE\Core::$user->id)
      return true;
    /* save request uri for returning after successful login */
    PHPPE\Http::redirect("login", true);
  }
}

PHPPE\AddOn

These are the building blocks of the view layer. They implement user input boxes, widgets and basicly everything that has to display formated values in a view.

To include an AddOn in a template, you use

    <!tag addon(arguments) name attributes>

Properties

Methods

PHPPE\User, PHPPE\Users^{PHPPE Pack}

This class is a bit tricky as PHPPE Core provides PHPPE\User (note singular) that can handle only one adminstrator user, whom password hash is set in configuration file. As soon as PHPPE Pack is installed under vendor/phppe/Core, that class will be transparently substituted with PHPPE\Users (note the prular) which can handle more users.

This class is a classic Model, it's inherited from PHPPE\Model therefore you can use the find() method to list users.

Properties

Methods

PHPPE\Registry^{PHPPE Pack}

In most cases configuration file is enough for extensions. But sometimes extensions need to store a value as well, e.g.: timestamp of the lust run. Because PHPPE does not allow the webserver's user to write php files, it cannot change config.php, so it would need a different mechanism, and that's what Registry is for. Without a datasource, it will use local files to store changable configuration variables, uses 'registry' table otherwise.

Properties

None.

Methods

PHPPE\DB^{PHPPE Pack}

SQL Query Builder, built on top of datasource.

Properties

None.

Methods

Exceptions

Throws DBException.

PHPPE\Email^{PHPPE Pack}

Email builder and sender. Supports multipart messages and can speak SMTP directly (no dependency to third lib classes).

The backend is configured in phppe/config.php.

Backends

Properties

None.

Methods

Exceptions

Throws EmailException.

PHPPE\GPIO^{PHPPE GPIO}

Allows manipulation of Raspberry Pi GPIO ports from PHP, and also queries some useful property of the board.

Setup

In order to get GPIO working, you'll have to add the webserver's user to the gpio group:

# addgroup www-data gpio

Also, you should add /sys/class/gpio and /proc/cpuinfo to open_basedir in your php.ini file.

Properties

Methods

Exceptions

Throws GPIOException.

JavaScript Plugins^{PHPPE Pack}

Adds functionality to PHPPE JavaScript libraries.

Namespaceless functions

Temporary client side storage

pe.cookie

Permanent client side storage (localStorage)

pe.store

Drag and Drop

pe.dnd

You can also use the data attribute version, add data-drag="id,icon,size,endhook" to draggable elements, and data-drop="callback[,context]" to drop areas.

Popup menu

pe.popup

Or use data-popup="popupid" on the trigger elements.

Responsive tables

pe.resptable

To make your table responsive, add "resptable" class to it.

Set Selection

pe.setsel

An intuitive multiple selection widget.

User Profile

pe.user

Cookie Alert

pe.cookiealert

What You See is What You Get HTML editor

pe.wyswyg

Alternatively add "wyswyg" class to your textarea element.

(PHPPE\Core)->run()

Synopsis

public run( string $app, string $action );

Execute a PHPPE Application.

Parameters

Return value

None.

Examples

1
2

$phppe = include("public/index.php");
$phppe->run();

PHPPE\Core::lib()

Synopsis

public static lib( );
public static lib( string $name );
public static lib( string $name, string/object $service, string/array $dependencies );

This method is for dealing with libraries (services). Calling without argument or with exactly one argument is a query, applying more arguments define a new service.

Normally you'll never ever need to register a service. You should instead return an instance from your extension's init.php.

Parameters

Return value

Examples

1
2
3
4
5
6
7
8

//! query installed services
$all = Core::lib();
//! query a service instance
$gpio = Core::lib("GPIO");
//! add a new service with static class. Normally you don't need to do that
Core::lib("myService", "\PHPPE\myService");
//! add a new service with instance and dependency check. Normally you don't need to do that
Core::lib("myService", $myService, "Users,Email");

PHPPE\Core::isInst()

Synopsis

public static isInst( string $name );

Installation check, returns true if service or AddOn exists.

Parameters

Return value

Examples

1
2

//! check if a service is installed
$hasGpio = Core::isInst("GPIO");

PHPPE\Core::lang()

Synopsis

public static lang( string $name );

Loads a language dictionary into memory for a class (extension).

Parameters

Return value

None.

Examples

1
2

//! load a language dictionary
Core::lang("GPIO");

L()

Synopsis

L( string $phrase, ... );

Translate a text to user's language. This function is available almost everywhere: in PHP, in JavaScript and in view templates as well.

The dictionary has to be loaded with Core::lang().

You can pass arguments to the function if the translated text contains %s or %d. Note that JS version just substitutes strings, it does not format them.

Parameters

Return value

Examples

1
2
3
4
5
6

//! translate a keyword
L("myextension_mylabel");
//! translate direct text
L("Thank You!");
//! translate with arguments
L("%s logged in", $username);

PHPPE\Core::log()

Synopsis

public static log( string $weight, string $message, string $facility );

Logger. Don't forget that your messages most probably will be parsed by scripts, so use English messages if possible without translation.

When configured to log to syslog, no files will be written, and the message will be sent as:

(vhost name):PHPPE-(A|W|E|C|I|D)-(facility):(original message without line breaks)

It's easy to grep. If you also turn on trace, then the caller's filename and line will be logged as well.

Files

data/log

Parameters

Return value

None.

Examples

1

Core::log("D", "I'm running!", "myService");

See also

• PHPPE\View::e()

PHPPE\Core::isBtn()

Synopsis

public static isBtn( string $name );

Checks if the user is trying to save a form by pressing a button. This includes CSRF check as well.

Parameters

Return value

Examples

1
2
3
4
5
6
7

//! typical in action handlers
if (Core::isBtn("myform")) {
    $myform = Core::req2obj("myform");
    ...
}
//! save which button was pressed
$btnNo = Core::isBtn("userform");

See also

• PHPPE\Filter
• PHPPE\Core::error()
• PHPPE\Core::isError()
• PHPPE\Core::validate()
• PHPPE\Core::req2obj()

PHPPE\Core::error()

Synopsis

public static error( );
public static error( string $message, string $field );

When called without arguments, returns error messages, otherwise adds a new error to the page or to a field.

Parameters

Return value

Examples

1
2
3
4
5
6

//! query error messages
$errors = Core::error();
//! set an error message
Core::error("Something went wrong!");
//! set an error for a field
Core::error("Please fill out this field.", "myform.username");

See also

• PHPPE\Core::isBtn()
• PHPPE\Core::isError()
• PHPPE\Core::validate()
• PHPPE\Core::req2arr()

PHPPE\Core::isError()

Synopsis

public static isError( string $field );

Check if there was an error.

Parameters

Return value

Examples

1
2
3
4

//! is there any error message?
$wasError = Core::isError();
//! is there a problem with a field?
$badInput = Core::isError("myform.username");

See also

• PHPPE\Core::isBtn()
• PHPPE\Core::error()
• PHPPE\Core::validate()
• PHPPE\Core::req2arr()

PHPPE\Core::event()

Synopsis

public static event( string $type, array $context );

Triggers an event, and executes all event hook for it. You don't have to use this method, as events are triggered by Core.

Parameters

Return value

Examples

1
2

//! trigger event
list($app, $action) = Core::event("route", [$app, $action]);

See also

• Event hooks

PHPPE\Core::validate()

Synopsis

public static validate( string $name, string $validator, boolean $required, array $arguments, array $attributes );

Adds extra validation rule to a field. Note that type of the field automaticaly adds validation.

Validator will be prefixed by "PHPPE\AddOn" and the resulting class' validate() method will be used.

Parameters

Return value

None.

Examples

1
2

//! add extra validation to a field
Core::validate("myform.email", "filtermx");

See also

• Validation event
• PHPPE\Core::isBtn()
• PHPPE\Core::error()
• PHPPE\Core::isError()
• PHPPE\Core::req2arr()

PHPPE\Core::req2arr(), PHPPE\Core::req2obj()

Synopsis

public static req2arr( string $form, array $rules );
public static req2obj( string $form, array $rules );

Get user input from dragon land with validation and return it in an associative array (or stdClass). Usually you don't have to worry about validation rules as PHPPE\View::template() will build the appropriate $rules array according to the fields used in the view.

Parameters

Return value

Examples

1
2
3
4
5

//! typical in action handlers
if (Core::isBtn("myform")) {
    $myform = Core::req2arr("myform");
    ...
}

See also

• Validation event
• PHPPE\Core::isBtn()
• PHPPE\Core::error()
• PHPPE\Core::isError()
• PHPPE\Core::validate()

PHPPE\Core::arr2str(), PHPPE\Core::obj2str()

Synopsis

public static arr2str( array $subject, string/array $exclude, string $separator );
public static obj2str( object $subject, string/array $exclude, string $separator );

Convert an associative array or object into a properly escaped string, appropriate for XML attributes or SQL queries.

Parameters

Return value

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13

/* $obj => stdClass Object
   (
    [Id] => 123
    [Name] => Something
    [AnotherField] => good
    [Flag] => 1
   ) */

//! for SQL
Core::obj2str( $obj ) => "Id='123',Name='Something',AnotherField='good',Flag='1'"
Core::arr2str( $obj, "Id,Flag" ) => "Name='Something',AnotherField='good'"
//! for XML attributes
Core::obj2str( $obj, "", " ") => "Id='123' Name='Something' AnotherField='good' Flag='1'"

See also

• PHPPE\Core::req2arr()
• PHPPE\Core::val2arr()
• PHPPE\Core::tre2arr()

PHPPE\Core::val2arr()

Synopsis

public static val2arr( string $expression, string $separator );

Get the value of a templater expression and convert it into an array.

Parameters

Return value

Examples

1
2
3
4
5

//! $obj->field = [ "a", "b", "c" ]
$arr = Core::val2arr( "obj.field" );
//! $obj['field'] = "a;b;c"
$arr = Core::val2arr( "obj.field", ";" );
//! $arr = [ "a", "b", "c" ] in both cases

See also

• PHPPE\Core::req2arr()
• PHPPE\Core::arr2str()
• PHPPE\Core::tre2arr()

PHPPE\Core::tre2arr()

Synopsis

public static tre2arr( array $subject, string $prefix );
public static tre2arr( array $subject, string $prefix, string $suffix );

Flat a tree stored in an array into a one-level array. It has two operation modes:
  1. without suffix it generates arrays for SELECT boxes.
  2. with suffix given, it generates arrays for XML trees.
See examples below.

Parameters

Return value

Examples

1
2
3
4
5

//! option lists for select boxes
$arr1 = Core::tre2arr( $tree, "  " );
//! XML mode, for AJAX loaded category trees
$arr2 = Core::tre2arr( $tree, "<div data-level=%d>", "</div>" );
//! note the differences in the 'name' item below:

Array
(
[0] => stdClass Object
  (
    [id] => 1
    [name] => item1
  )

[1] => stdClass Object
  (
    [id] => 2
    [name] => item2
    [_] => Array
      (
        [0] => stdClass Object
          (
            [id] => 21
            [name] => item2.1
            [_] => Array
              (
                [0] => stdClass Object
                  (
                    [id] => 211
                    [name] => item2.1.1
                  )
              )
          )

        [1] => stdClass Object
          (
            [id] => 22
            [name] => item2.2
          )

        [2] => stdClass Object
          (
            [id] => 23
            [name] => item2.3
          )
       )
    )

[2] => stdClass Object
  (
    [id] => 3
    [name] => item2
  )
)

Array
(
    [0] => stdClass Object
        (
            [id] => 1
            [name] => item1
        )

    [1] => stdClass Object
        (
            [id] => 2
            [name] => item2
        )

    [2] => stdClass Object
        (
            [id] => 21
            [name] =>   item2.1
        )

    [3] => stdClass Object
        (
            [id] => 211
            [name] =>     item2.1.1
        )

    [4] => stdClass Object
        (
            [id] => 22
            [name] =>   item2.2
        )

    [5] => stdClass Object
        (
            [id] => 23
            [name] =>   item2.3
        )

    [6] => stdClass Object
        (
            [id] => 3
            [name] => item2
        )
)

Array
(
    [0] => stdClass Object
        (
            [id] => 1
            [name] => item1
        )

    [1] => stdClass Object
        (
            [id] => 2
            [name] => item2
<div data-level=1>
        )

    [2] => stdClass Object
        (
            [id] => 21
            [name] => item2.1
<div data-level=2>
        )

    [3] => stdClass Object
        (
            [id] => 211
            [name] => item2.1.1
</div>
        )

    [4] => stdClass Object
        (
            [id] => 22
            [name] => item2.2
        )

    [5] => stdClass Object
        (
            [id] => 23
            [name] => item2.3
</div>
        )

    [6] => stdClass Object
        (
            [id] => 3
            [name] => item2
        )
)

See also

• PHPPE\Core::req2arr()
• PHPPE\Core::arr2str()
• PHPPE\Core::tre2arr()

PHPPE\Core::bm()

Synopsis

public static bm( string $name );

Sets a benchmark point in code. Every point is measured relative to it's accessor point.

Parameters

Return value

None.

Examples

1
2
3

// ...do time consuming calculation here...
//! mark a spot in code
Core::bm("calculation");

See also

• Benchmark
• Developer

PHPPE\ClassMap::has()

Synopsis

public static has( string $class, string $method );

Checks if a class can be autoloaded or if it has a method.

Parameters

Return value

Examples

1
2
3
4

//! check if there's a class
ClassMap::has("Extension");
//! check if there's a class and also it has a given method
ClassMap::has("Extension", "init");

See also

• \PHPPE\ClassMap::map()
• \PHPPE\ClassMap::ace()

PHPPE\ClassMap::ace()

Synopsis

public static ace( );

Return valid Access Control Entries.

Parameters

None.

Return value

Examples

1

$ace = ClassMap::ace();

See also

• \PHPPE\ClassMap::has()
• \PHPPE\ClassMap::map()

PHPPE\ClassMap::map()

Synopsis

public static map( );

Return classes along with the files they were defined in.

Parameters

None.

Return value

Examples

1

$map = ClassMap::map();

See also

• \PHPPE\ClassMap::has()
• \PHPPE\ClassMap::ace()

(PHPPE\Model)->__construct()

Synopsis

new Model( int/string $id );
new Model( mixed $properties );

Loads object properties from the argument (if it's an array or object) or from database (if argument is an id).

Parameters

Return value

Examples

1
2
3
4

//! load a model instance by id
$user= new Users(1);
//! load by arguments
$user= new Users(["email"=>"some@where.tld"]);

See also

• (PHPPE\Model)->load()
• (PHPPE\Model)->save()
• PHPPE\Model::find()

(PHPPE\Model)->load()

Synopsis

public load( int $id );
public load( string $searchphrase, string $where, string $order );

Loads object properties from the first database record found.

Parameters

Return value

Examples

1
2
3
4

//! load a model instance by id
$user->load(1);
//! load by searching for a record
$user->load("me@localhost", "email=?", "created DESC");

See also

• PHPPE\Model::find()
• (PHPPE\Model)->save()

(PHPPE\Model)->save()

Synopsis

public save( boolean $new );

Saves a Model object into database. If the model has no identifier, it will be INSERTed, otherwise UPDATEd. With flag given it will INSERT the object with the given id.

Parameters

Return value

Examples

1
2
3
4
5

//! save a model, INSERT or UPDATE depending on whether it has id
$user->save();
//! save as a new object with INSERT, despite it has an id and should be an UPDATE
$user->id = 1;
$user->save(true);

See also

• PHPPE\Model::find()
• (PHPPE\Model)->load()

PHPPE\Model::find()

Synopsis

public find( string $searchphrase, string $where, string $order, string $fields );

Finds instances of a model in database.

Parameters

Return value

Examples

1
2
3
4

//! get all users with all fields
$users = Users::find();
//! get email address for all users named Joe
$users = Users::find( DS::like("Joe"), "name like ?", "created DESC", "name,email");

See also

• (PHPPE\Model)->load()
• (PHPPE\Model)->save()

PHPPE\Http::url(), url()

Synopsis

public static url( string $app, string $action );

Generate a permanent url for the current (or other) application and it's action. It will use Core properties to do that, namely $core->sec and $core->base.

Parameters

Return value

Examples

1
2

url(); // => "http://localhost/myapp/myaction"
url("users", "add");  // => "http://localhost/users/add"

See also

• PHPPE\Http::redirect()
• PHPPE\Http::get()

PHPPE\Http::redirect()

Synopsis

public static redirect( string $url, boolean $save );

Redirects user. Without argument, to the current page or to the saved URL.

Parameters

Return value

None.

Examples

1
2
3
4
5
6
7
8
9
10

//! these two are identical when there's no saved URL
Http::redirect();
Http::redirect(Core::$core->app."/".Core::$core->action);
//! redirect to the home page
Http::redirect("/");
//! if user is not logged in, save the current URL and redirect to login page
if (!Core::$user->id)
  Http::redirect("login", true);
//! redirect to another site
Http::redirect("https://netbank.com/payment?return=".urlencode(url())."&shopid=1234");

See also

• PHPPE\Http::url()
• PHPPE\Http::get()

PHPPE\Http::get()

Synopsis

public static get( string $url, array $post, int $timeout );

Get content by making a HTTP request. This is better than file_get_contents() and CURL, because it handles redirections and keep track of cookie changes as well. Also it automatically passes the user's preferred language.

Parameters

Return value

Examples

1
2
3
4

//! make a GET request
$page = Http::get("https://webservice.org/api");
//! make a POST request
$page = Http::get("https://webservice.org/api", ["apikey"=>"1234", "func"=>"list"]);

See also

• PHPPE\Http::url()
• PHPPE\Http::redirect()

PHPPE\Http::route()

Synopsis

public static route( string $urlmask, string $class, string $method, string/array $filters);
public static route( stdClass( url => $urlmask, name => $class, action => $method, filters => $filters ) );
public static route( [ "url" => $urlmask, "name" => $class, "action" => $method, "filters" => $filters ] );
public static route( [ $urlmask => [ $class, $method, $filters ] ] );
public static route( [ $urlmask => [ $class, $method, $filters ], ... ] );

Add new URL route to the routing table. Call it from init.php or from extension init() method.

Parameters

Return value

None.

Examples

See URL routing.

See also

• PHPPE\Http::urlMatch()
• Routing tutorial
• Controllers
• Filters
• Routing filter event
• PHPPE\Users::has()
• PHPPE\Filter

PHPPE\Http::urlMatch()

Synopsis

public static urlMatch( string $app, string $action, string $url );

Returns controller and action handler name for current (or given) URL.

Parameters

Return value

Examples

1

list($app, $action, $args = Http::urlMatch("Content", "action", "url/to/match");

See also

• PHPPE\Http::route()
• Routing tutorial
• Controllers
• Filters

PHPPE\DS::db()

Synopsis

public static db( );
public static db( string $pdodsn, object $instance );

When called without arguments, returns the current PDO instance. Otherwise connects a new database as datasource.

Parameters

Return value

Examples

1
2
3
4
5
6
7

//! query current PDO instance
$pdo = DS::db();
//! connect new PDO instances
$selector = DS::db("sqlite:data/db.sqlite");
$selector = DS::db("mysql:host=localhost;dbname=db;charset=utf8@user:pass");
//! connect an arbitrary, but PDO compatible class
$selector = DS::db("salesforce:", $salesforce);

See also

• PHPPE\DS::ds()
• PHPPE\DS::exec()
• PHPPE\DS::query()
• PHPPE\DS::fetch()
• PHPPE\DS::field()
• PHPPE\DS::tree()

PHPPE\DS::ds()

Synopsis

public static ds( );
public static ds( int $selector );

When called without arguments, returns the current datasource selector. With argument given selects a new datasource.

Parameters

Return value

Examples

1
2
3
4

//! query current data source
$selector = DS::ds();
//! select a new data source
$selector = DS::ds(2);

See also

• PHPPE\DS::db()
• PHPPE\DS::exec()
• PHPPE\DS::query()
• PHPPE\DS::fetch()
• PHPPE\DS::field()
• PHPPE\DS::tree()

PHPPE\DS::like(), PHPPE\DB::like()

Synopsis

public static like( string $str );

Converts a user provided string into an sql-safe, search ready like phrase.

Parameters

Return value

Examples

1
2

DS::like("search this"); // => "%search%this%"
DB::like("search this"); // => "%search%this%"

See also

• PHPPE\DS
• PHPPE\DB
• PHPPE\Model::find()

PHPPE\DS::exec()

Synopsis

public static exec( string $sql, array $args );

Executes an sql query on current datasource.

Parameters

Return value

Examples

1
2
3

$results = DS::exec("SELECT * FROM users");
$rowno = DS::exec("DELETE FROM users WHERE name like ?", [ "Joe" ]);
$rowno = DS::exec("INSERT INTO users SET ".Core::obj2str(Core::$user));

See also

• PHPPE\DS::ds()
• PHPPE\DS::query()
• PHPPE\DS::fetch()
• PHPPE\DS::field()
• PHPPE\DS::tree()
• PHPPE\Core::obj2str()

PHPPE\DS::query()

Synopsis

public static query(string/array $fields, string $table, string $where, string $groupBy, string $orderBy, int $offset, int $limit, array $args );

Executes an sql SELECT query on current datasource. This is a low level method, you should use PHPPE\DB instead.

Parameters

Return value

Examples

1
2
3
4
5
6
7
8
9
10

$results = DS::query(
    "a.*,b.topic",
    "forum_post a LEFT JOIN forum_topic b ON a.topicId=b.id",
    "a.userId=?",
    "b.id",
    "a.userId DESC",
    0,
    100,
    [ Core::$user ]
);

See also

• PHPPE\DS::ds()
• PHPPE\DS::exec()
• PHPPE\DS::fetch()
• PHPPE\DS::field()
• PHPPE\DS::tree()

PHPPE\DS::fetch()

Synopsis

public static fetch(string/array $fields, string $table, string $where, string $groupBy, string $orderBy, array $args );

Executes an sql SELECT query on current datasource and returns the first record. This is a low level method, you should use PHPPE\DB instead.

Parameters

Return value

Examples

1
2
3
4
5
6
7
8

$record = (array)DS::fetch(
    "a.*,b.topic",
    "forum_post a LEFT JOIN forum_topic b ON a.topicId=b.id",
    "a.userId=?",
    "b.id",
    "a.userId DESC",
    [ Core::$user ]
);

See also

• PHPPE\DS::ds()
• PHPPE\DS::exec()
• PHPPE\DS::query()
• PHPPE\DS::field()
• PHPPE\DS::tree()

PHPPE\DS::field()

Synopsis

public static field(string/array $fields, string $table, string $where, string $groupBy, string $orderBy, array $args );

Executes an sql SELECT query on current datasource and returns the first column of the first record. This is a low level method, you should use PHPPE\DB instead.

Parameters

Return value

Examples

1

$time = DS::field("CURRENT_TIMESTAMP");

See also

• PHPPE\DS::ds()
• PHPPE\DS::exec()
• PHPPE\DS::query()
• PHPPE\DS::fetch()
• PHPPE\DS::tree()

PHPPE\DS::tree()

Synopsis

public static tree( string $sql, int $parentId );

Executes several sql queries on current datasource to return a tree (or sub-tree). You can use Core::tre2arr() to convert the result into an option list or XML tree.

Parameters

Return value

Examples

1

$subTree = DS::tree("SELECT id,parentId,name FROM category WHERE id!=parentId AND parentId=?", 2);

See also

• PHPPE\DS::ds()
• PHPPE\DS::exec()
• PHPPE\DS::query()
• PHPPE\DS::fetch()
• PHPPE\DS::field()
• PHPPE\Core::tre2arr()

PHPPE\DS::bill()

Synopsis

public static bill( );

Returns the time consumed by database queries in second with microsec precision.

Parameters

None.

Return value

Examples

1
2
3
4

$start = DS::bill();
//! do some database stuff here
DS::exec("DELETE FROM users");
$benchmark = DS::bill() - $start;

See also

• PHPPE\DS::exec()

PHPPE\Cache::set()

Synopsis

public static set(string $key, mixed $value, int $ttl, boolean $force );

Saves a value to cache for key.

Parameters

Return value

Examples

1

Cache::set("rssnews", $rssNews, 60);

See also

• PHPPE\Cache::get()
• Cache Management

PHPPE\Cache::get()

Synopsis

public static get(string $key, boolean $force );

Retrive a value from cache for key.

Parameters

Return value

Examples

1

$rssNews = Cache::set("rssnews");

See also

• PHPPE\Cache::set()
• Cache Management

PHPPE\Assets::minify()

Synopsis

public static minify( string $subject, string $type );

Compress code by removing whitespace characters. If installed, it will use CSSMin and JSMin. Minifying can be turned off by setting Core::$core->nominify in configuration.

Parameters

Return value

Examples

1
2
3
4

$compressed = Assets::minify("
.mystyle1 {
    font-size: 16px;
}", "css");

PHPPE\View::assign()

Synopsis

public static assign( string $name, mixed $value );

Assign variable to templater.

Parameters

Return value

None.

Examples

1
2
3

View::assign("myModel", $myModel);
//! then reference in templates as:
//! <!=myModel.name>

See also

• PHPPE\View::template()
• PHPPE\View::getval()

PHPPE\View::css()

Synopsis

public static css( );
public static css( string $file );

When called without parameters, returns assigned stylesheets, add a new css to templater otherwise.

Parameters

Return value

Examples