Add some documentation

README.md

@@ -0,0 +1,28 @@
+# EesyPHP
+
+EesyPHP is an easy and minimalist PHP framework for web application. It's currently
+provided with a minimalist demo application that permit to manage items stored in
+a database.
+
+## Installation / configuration
+
+Please see dedicated files in _docs_ directory.
+
+## Copyright
+
+Copyright (c) 2020 Benjamin Renard <brenard@zionetrix.net>
+
+## License
+
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License version 3
+as published by the Free Software Foundation.
+
+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 General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

docs/config.md

@@ -0,0 +1,51 @@
+# Configuration
+
+The main configuration file is *includes/config.inc.php*. You can overrides all variables that main configuration file contain in your own configuration file *includes/config.local.php*. This file will be automatically included if present.
+
+> **Note :** In the configuration files, to refer to the application root directory, you could use the variable `$root_dir_path` (that does not contain the trailing slash).
+
+**The first thing you have to configured is the public root URL of the API in `$public_root_url` variable.** This URL could be relative (default) or absolute.
+
+> **Note :** You also could adapt _$main_pagetitle_ and _$included_css_files_ to your situation.
+
+## Data/files directories :
+
+All application data are, by default, in _data_ sub-directory. You could configure it by using the following variables :
+  - `$data_dir` : Root DATA directory (Default : _data_)
+  - `$tmp_root_dir` : Root temporary files directory (Default : _$data_dir/tmp_)
+  - `$logs_dir_path` : Logs directory (Default : _$data_dir/logs_)
+  - `$upload_tmp_dir` : Temporary directory for PHP uploading files : when uploading files, PHP will stored files in this directory before application move it to their final destination (Default : _$data_dir/uploading_)
+  - `$smarty_templates_c_dir` : Templates cache directory (Default : _$tmp_root_dir/templates_c_)
+
+## Logs :
+
+Default log files path is *data/logs/app.log* (and *data/logs/cli.log* for CLI tool). This could be configured using `$log_file` configuration variable. You can also set the log level using `$log_level` variable *(default value = "INFO", see config.inc.php).*
+
+## Database configuration :
+
+The database is used to store demo items information. For this reason, a basic *Sqlite* database could be used and is the default database backend. However, you can use any database backend supported by the [PHP PDO abstraction system](http://php.net/pdo).
+
+The database connection is configured using the following variables :
+ - `$dn_dsn` : the *Data Source Name (DSN)* depending on your database backend.
+ - `$db_user` : the database username.
+ - `$db_pwd` : the database password.
+ - `$db_options` : the database connection options (see your PHP PDO Driver documentation). By default, this variable value is an empty array ("`array()`").
+ - `$db_date_format` : the date format as retreive from the database.
+ - `$db_datetime_format` : the date and time format as retreive from the database.
+
+> **Note :** You could find some configuration examples for _PostgreSQL_, _MariaDB / MySQL_ or _Sqlite_ in _config.inc.php_ file. Initial _SQL_ files could also be found in _data_ directory.
+
+## E-mail configuration :
+
+This application send some mail by using [PEAR Mail library](http://pear.php.net/package/Mail). The path of this library must be specify using `$php_mail_path`. The default value corresponding to the version provided by *php-mail* Debian package.
+
+This library support different methods to send mail and the default one is *SMTP*. This method require that the [PEAR Net_SMTP library](http://pear.php.net/package/Net_SMTP) is also installed on the system. You could configure another method sending method using the variable  `$mail_send_method` (see comment in *config.inc.php* file or [the PEAR Mail library documentation](http://pear.php.net/manual/en/package.mail.mail.factory.php)).
+
+Depending on the sending method choose, some options are available to configure their usage (see comment in *config.inc.php* file or [the PEAR Mail library documentation](http://pear.php.net/manual/en/package.mail.mail.factory.php)) and could be configured using `$mail_send_params` variable.
+
+To forge e-mail, this application use [PEAR Mail_Mime library](http://pear.php.net/package/Mail_Mime). The path of this library must be specify using `$php_mail_mime_path`. The default value corresponding to the version provided by *php-mail-mime* Debian package.
+
+Some other variables exist to manage the email sending by the application :
+ - `$mail_headers` : an PHP array of default headers add to mail sent by the application
+ - `$mail_sender` : the email address of the sender of all emails sent by the application
+ - `$mail_catch_all` : for debugging purpose, you can using this variable to specify an email address that will received all email sent by the application in place of the original recipient

docs/eesyphp.cron

@@ -0,0 +1,2 @@
+# Handle items expiration
+0 7 * * eesyphp /usr/local/bin/eesyphp -q cron

docs/eesyphp.logrotate

@@ -0,0 +1,6 @@
+/var/www/eesyphp/data/logs/*.log {
+	daily
+	missingok
+	rotate 7
+	sharedscripts
+}

docs/install.md

@@ -0,0 +1,136 @@
+# Installation
+
+## Dependencies :
+
+This Debian packages have to be installed :
+
+ - git *(only for deployment only)*
+ - composer (and unzip or zip)
+ - php-cli
+ - php-mail
+ - php-mail-mine
+ - php-net-smtp
+ - php-auth-sasl
+ - php-json
+ - php-mbstring
+ - php-pgsql *(for PostgreSQL DB backend)*
+ - php-sqlite3 *(for sqlite DB backend, sqlite3 tool (provided by the same name package) is also used to create the DB file)*
+ - smarty3
+
+## Deployment :
+
+To deploy this application, for instance in */var/www/eesyphp*, run this commands :
+
+    cd /var/www
+    adduser --home /var/www/eesyphp --no-create-home --disabled-password --gid 33 eesyphp
+    git clone https://gogs.example.org/example/eesyphp.git /var/www/eesyphp
+    chown eesyphp: /var/www/eesyphp
+    ln -s /var/www/eesyphp/bin/items.wrapper /usr/local/bin/eesyphp
+    ln -s /var/www/eesyphp/docs/eesyphp.cron /etc/cron.d/eesyphp
+    ln -s /var/www/eesyphp/docs/eesyphplogrotate /etc/logrotate.d/eesyphp
+
+## Install PHP dependencies :
+
+    su - eesyphp
+    composer install
+
+## Initialize database :
+
+### SQLite
+
+To initialize SQLite database, run this commands :
+
+    cd /var/www/eesyphp/data
+    sqlite3 db.sqlite3 < sqlite.init-db.sql
+
+### PostgreSQL
+
+To initialize PostgreSQL database, run this commands :
+
+    su - postgres
+    createuser -P items
+    createdb -O items items
+    psql items < /var/www/eesyphp/data/pgsql.init-db.sql
+
+### MariaDB / MySQL
+
+To initialize MariaDB / MySQL database, run this commands :
+
+    sudo mysql << EOF
+    CREATE DATABASE items;
+    GRANT ALL ON items.* TO items@localhost IDENTIFIED BY 'items';
+    EOF
+    sudo mysql items < /var/www/eesyphp/data/mariadb-mysql.init-db.sql
+
+
+## Configure PHP FPM pool :
+
+You could configure a dedicated *PHP FPM pool*.
+
+***Example :***
+
+```
+[eesyphp]
+user = eesyphp
+group = www-data
+listen = /run/php7.0-fpm_eesyphp.sock
+listen.owner = www-data
+listen.group = www-data
+pm = dynamic
+pm.max_children = 5
+pm.start_servers = 2
+pm.min_spare_servers = 1
+pm.max_spare_servers = 3
+chdir = /
+php_value[error_log] = /var/www/eesyphp/data/logs/php.log
+php_value[upload_max_filesize] = 10M
+php_value[post_max_size] = 10M
+php_value[memory_limit] = 10M
+php_value[default_charset] = 'UTF-8'
+php_value[date.timezone] = Europe/Paris
+```
+
+## Configure Apache VirtualHost :
+
+You could configure a dedicated *VirtualHost*.
+
+***Example :***
+
+```
+<VirtualHost *:80>
+        ServerName eesyphp.example.org
+        DocumentRoot /var/www/empty
+
+        RewriteEngine on
+        RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
+
+        ErrorLog  /var/log/apache2/eesyphp.example.org-error.log
+        CustomLog /var/log/apache2/eesyphp.example.org-access.log combined
+</VirtualHost>
+
+<VirtualHost *:443>
+        ServerName eesyphp.example.org
+        DocumentRoot /var/www/eesyphp/public_html
+
+        SSLEngine On
+        SSLCertificateFile /etc/letsencrypt/live/eesyphp.example.org/fullchain.pem
+        SSLCertificateKeyFile /etc/letsencrypt/live/eesyphp.example.org/privkey.pem
+
+        <FilesMatch \.php$>
+                SetHandler "proxy:unix:/run/php7.0-fpm_eesyphp.sock|fcgi:///"
+        </FilesMatch>
+
+        <Directory   /var/www/eesyphp/public_html>
+                # Acceptable overrides:
+                # - FileInfo (.htacces-based rewrite rules)
+                # - AuthConfig (.htaccess-based basic auth)
+                AllowOverride FileInfo AuthConfig
+        </Directory>
+
+        # Compress most static files
+        AddOutputFilterByType DEFLATE text/html text/xml text/css application/javascript
+
+        ErrorLog  /var/log/apache2/eesyphp.example.org-error.log
+        CustomLog /var/log/apache2/eesyphp.example.org-access.log combined
+</VirtualHost>
+```

includes/config.inc.php

@@ -3,13 +3,15 @@
 // Public root URL
 $public_root_url = "http://127.0.0.1/eesyphp";
 
-// Application root/data directory
+// Application root data directory
 $data_dir = $root_dir_path."/data";
 
-// Upload files
-$upload_tmp_dir = "$data_dir/tmp/uploading";
+// Temporary files root directory
 $tmp_root_dir = "$data_dir/tmp";
 
+// Temporary uploading files directory
+$upload_tmp_dir = "$tmp_root_dir/uploading";
+
 // Main pagetitle
 $main_pagetitle = "Eesyphp";
 
@@ -18,6 +20,9 @@ $included_css_files = array();
 
 // Log configuration
 
+// Logs directory path
+$logs_dir_path = "$data_dir/logs";
+
 // Log file path
 if (php_sapi_name() == "cli")
   $log_file = "$logs_dir_path/cli.log";