Add some documentation

This commit is contained in:
Benjamin Renard 2020-04-18 01:25:49 +02:00
parent 699b7c4d1f
commit 63bab08c48
6 changed files with 231 additions and 3 deletions

28
README.md Normal file
View file

@ -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.

51
docs/config.md Normal file
View file

@ -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

2
docs/eesyphp.cron Normal file
View file

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

6
docs/eesyphp.logrotate Normal file
View file

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

136
docs/install.md Normal file
View file

@ -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>
```

View file

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