Overview

Picoforms's front-end to the database presenting an HTML & CSS interface to every form, field and input.

Demonstration

You can find a live demo form at https://forms.lch361.net/form/00000000-0000-0000-0000-000000000000.

Installation

This project uses PHP 8.4¹ with extensions: PostgreSQL PDO, session, bcmath, mbstring, pecl-uuid. It can be served with any PHP-capable HTTP server, for example, Nginx with PHP-FPM.

1. Install all programs and dependencies mentioned above.

   Concrete example for Alpine Linux and Nginx:

   apk add php84-fpm php84-pdo_pgsql php84-session php84-mbstring php84-bcmath php84-pecl-uuid nginx
   

2. Clone source code repository via Git into current directory.

   sourcedir="picoforms-web-ui"
   git clone https://codeberg.org/picoforms/web-ui "$sourcedir" && cd "$sourcedir"
   

3. Create a folder for web root.

   webroot="/var/www/picoforms"
   mkdir -p "$webroot"
   

4. Copy picoforms.php into web root.

   cp picoforms.php "$webroot"
   

5. Select a theme from themes folder. Copy chosen folder into a theme folder under web root.

   theme=lch361.net
   cp -r "themes/$theme" "$webroot/theme"
   

6. Create a configuration file: config.json at web root. Make it only readable by a PHP process on your server² .

   php_user=??? # Find out which user runs PHP on your system
   touch "$webroot/config.json"
   chmod 400 "$webroot/config.json"
   chown "$php_user" "$webroot/config.json"
   

7. Enter your database connection credentials into config.json at web root. These credentials must be provided by your local system administrator or, if that's you, by creating a new user as described in documentation.

   cat <<EOF > "$webroot/config.json"
   {
    "sql": {
    "user": $PGUSER,
    "password": $PGPASSWORD,
    "host": $PGHOST,
    "port": $PGPORT,
    "database": "picoforms"
    }
   }
   EOF
   

8. Configure your web/HTTP server, so that:

   • any URL matching file name under web root will be served statically;
   • any other URL will be served via PHP by a file picoforms.php.

   Concrete example for Nginx and PHP-FPM:

   cat > /etc/nginx/http.d/picoforms.conf <<EOF
   server {
    listen 80;
    listen [::]:80;
    root $webroot;
    try_files \$uri @picoforms;
    location @picoforms {
    include /etc/nginx/fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $webroot/picoforms.php;
    fastcgi_param PATH_INFO \$uri;
    }
   }
   EOF
   

9. Start web server and PHP.

   Concrete example for Alpine Linux, Nginx and PHP-FPM:

   rc-service nginx start
   rc-service php-fpm84 start
   

10. Access configured website from other host. Not only you'll make sure everything works, it will also autoconfigure URL prefix in a database.

Configuration

File config.defaults.json contains a config sample with every option set to its builtin default value and comments describing some options and sections. If you omit some option at $webroot/config.json, that option will use a builtin default value as in config.defaults.json.

Development

Creating a custom theme

Every theme is a folder under the www-form/themes/ path. A theme should always contain picoforms.css file — the only stylesheet that will be directly loaded by HTML code. Theme can also contain additional assets, e.g. images and fonts.