From 744def6b979232e183a1f0d5be3debfe47d46e52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Henry=20Stivens=20Adarme=20Mu=C3=B1oz?= Date: Sat, 16 Aug 2025 13:21:46 -0500 Subject: [PATCH] Add installation instructions for KumbiaPHP on Apache and Nginx in English --- en/installing-kumbiaphp-apache-nginx.md | 230 ++++++++++++++++++++++++ en/to-install.md | 209 ++++++++------------- 2 files changed, 306 insertions(+), 133 deletions(-) create mode 100644 en/installing-kumbiaphp-apache-nginx.md diff --git a/en/installing-kumbiaphp-apache-nginx.md b/en/installing-kumbiaphp-apache-nginx.md new file mode 100644 index 00000000..3923e80a --- /dev/null +++ b/en/installing-kumbiaphp-apache-nginx.md @@ -0,0 +1,230 @@ +# Installing KumbiaPHP on Web Servers (Apache and Nginx) for GNU/Linux (Debian, Ubuntu and derivatives) + +This section provides instructions for installing and configuring KumbiaPHP using **Apache** or **Nginx** as a web +server on Linux distributions such as Ubuntu and Debian. By the end, you will have a functional KumbiaPHP installation +ready for development. + +> ⚠️ **Warning** +> +> This installation is intended as a testing environment, designed for experimenting with KumbiaPHP on a local server. +> It is **not** recommended for developing applications that will be deployed to production. + +## Prerequisites + +* A **Web Server** (Apache HTTP or Nginx) installed and running. +* **PHP 8.0** (or later) with required extensions: `php-mbstring`, `php-xml`, `php-json`, etc. +* Basic knowledge of terminal commands (`sudo`, moving files, etc.). + +## Download and Extract KumbiaPHP + +1. Go to the directory where the project files will be stored, e.g. `/var/www`: + + ```bash + cd /var/www + ``` + +2. **Download** the latest `.tar.gz` file from the official repository: + + ```bash + wget https://github.com/KumbiaPHP/KumbiaPHP/archive/v1.2.1.tar.gz + ``` + +3. **Extract** the contents: + + ```bash + tar -xzvf v1.2.1.tar.gz + ``` + +4. (Optional) **Rename** the resulting folder: + + ```bash + mv KumbiaPHP-1.2.1 kumbiafw + ``` + +## Server-Specific Configuration + +### Apache + +1. Create a new configuration file in `/etc/apache2/sites-available/`, for example `kumbiafw.conf`: + +```apache + + ServerName kumbia.fw + DocumentRoot /var/www/kumbiafw/default/public + + + AllowOverride All + Require all granted + + + ErrorLog ${APACHE_LOG_DIR}/kumbiafw-error.log + CustomLog ${APACHE_LOG_DIR}/kumbiafw-access.log combined + +``` + +* Replace `kumbia.fw` with the local domain or hostname you want to use. +* Adjust the `DocumentRoot` path to match where you extracted KumbiaPHP. + +2. Enable the new site and the `rewrite` module: + +```bash +sudo a2ensite kumbiafw.conf +sudo a2enmod rewrite +sudo systemctl reload apache2 +``` + +#### Why is `mod_rewrite` important? + +`mod_rewrite` is an Apache module that allows rewriting user-friendly URLs. +KumbiaPHP leverages this feature to let you use clean, readable URLs, like those seen in modern applications (without +symbols such as `?`, `&`, or file extensions like `.php`, `.asp`, `.aspx`, etc.). + +Additionally, `mod_rewrite` enhances application security by restricting direct access to internal directories and +files. Only the contents of the `public/` directory are accessible, ensuring business logic and core classes remain +protected. + +It also improves search engine indexing, which benefits the visibility of your applications. + +### Nginx + +1. Create a new server block in `/etc/nginx/sites-available/kumbiafw`: + +**Using `$_SERVER['PATH_INFO']`:** + +```nginx +server { + listen 80; + server_name kumbia.fw; + root /var/www/kumbiafw/default/public; + index index.php index.html index.htm; + + location / { + try_files $uri $uri/ /index.php$uri?$args; + } + + location ~ \.php { + # Extract PATH_INFO after index.php + fastcgi_split_path_info ^(.+\.php)(/.*)$; + + fastcgi_pass 127.0.0.1:9000; + # fastcgi_pass unix:/run/php/php-fpm.sock; + + include fastcgi_params; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + fastcgi_param PATH_INFO $fastcgi_path_info; + } + + location ~ /\.ht { + deny all; + } +} +``` + +**Using `$_GET['_url']`:** + +```nginx +server { + listen 80; + server_name kumbia.fw; + root /var/www/kumbiafw/default/public; + index index.php index.html index.htm; + + location / { + try_files $uri $uri/ /index.php?_url=$uri&$args; + } + + location ~ \.php { + fastcgi_pass 127.0.0.1:9000; + # fastcgi_pass unix:/run/php/php-fpm.sock; + + include fastcgi_params; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + } + + location ~ /\.ht { + deny all; + } +} +``` + +* Update `server_name` and `root` as needed. +* Make sure the PHP-FPM socket corresponds to your PHP version. + +> ℹ️ **Important** +> If you are using another PHP version (e.g. 8.1), adjust the socket path in Nginx (`fastcgi_pass`) or the corresponding +> module in Apache. Some instructions may vary slightly depending on your Ubuntu or Debian version. + +2. Enable the new site: + +```bash +sudo ln -s /etc/nginx/sites-available/kumbiafw /etc/nginx/sites-enabled/ +sudo nginx -t +sudo systemctl reload nginx +``` + +## Set Permissions + +Ensure that the web server user (usually `www-data`) has access to the files: + +```bash +sudo chown -R www-data:www-data /var/www/kumbiafw +sudo find /var/www/kumbiafw -type d -exec chmod 755 {} \; +sudo find /var/www/kumbiafw -type f -exec chmod 644 {} \; +``` + +* Directories should have `755` permissions. +* Files should have `644` permissions. + +## Test the Installation + +1. Edit your `/etc/hosts` file to map the server name: + + ```bash + sudo nano /etc/hosts + ``` + + Add this line: + + ``` + 127.0.0.1 kumbia.fw + ``` + +2. Open your browser and visit `http://kumbia.fw`. You should see the KumbiaPHP welcome page. + +![Successful installation](../images/welcome-page.jpg) + +## Verification with a Controller and View + +1. Create a file `app/controllers/test_controller.php`: + +```php +date = date('Y-m-d H:i:s'); + } +} +``` + +2. And its corresponding view in `app/views/test/index.phtml`: + +```php +

Welcome to KumbiaPHP!

+Today's date and time is: +``` + +3. Visit `http://kumbia.fw/test` in your browser to see the welcome message. + +![Welcome message](../images/test-welcome-message.jpg) diff --git a/en/to-install.md b/en/to-install.md index 90e74bc2..4c1b112c 100644 --- a/en/to-install.md +++ b/en/to-install.md @@ -1,166 +1,109 @@ -# Install KumbiaPHP +# Installing KumbiaPHP -This section explains the steps to follow, to run the framework in our development environment. +This section explains the necessary steps to get the framework up and running in your development environment. -## Requirements - -As mentioned above KumbiaPHP is very easy, and in this sense the requirements to operate the framework are minimal, are listed below: - -- PHP version 5.4 or higher. -- Web server with support for URL rewriting (Apache, Cherokee, Nginx, Lighttpd, Internet Information Server (IIS)). -- Database supported by KumbiaPHP. - -To install KumbiaPHP Framework, you should download the archive from the download section http://www.kumbiaphp.com/blog/manuales-y-descargas/ for the framework most recent version. Once the file is downloaded, it is essential to make sure that it has the extension .tgz for users Linux and .zip for Windows users. - -Then unzip its contents in the directory root of the webserver (DocumentRoot). To ensure some consistency in the document, this chapter assumes that the framework kumbiaphp is unzipped in the dir kumbiaphp/. Having a structure like the following: - - -- KumbiaPHP-master - |-- core - |-- vendors - |-- default - |-- app - |-- public - |-- .htaccess - `-- index.php - +> ⚠️ **Warning** +> +> This installation is intended as a testing environment, designed for experimenting with KumbiaPHP on a local server. +> It is **not** recommended for developing applications that will be deployed to production. -## Configure Apache - -KumbiaPHP Framework uses a module to rewrite URLs, making them more understandable and easy to remember in our applications. This module must be configured and installed, in this sense must check that the module is enabled, the following sections explain how to do it. +## Requirements -### Enabling mod_rewrite of Apache on GNU/Linux (Debian, Ubuntu and derivatives) +As mentioned earlier, KumbiaPHP is very easy to use, and the requirements to run it are minimal. You only need a [**PHP +version 8.0**](https://www.php.net/) interpreter or higher. -We made sure to activate mod_rewrite in this way and as an administrator user from the console. +## Installation Steps -```bash - > a2enmod rewrite - Enabling module rewrite. - Run '/etc/init.d/apache2 restart' to activate new configuration! -``` +1. Download the KumbiaPHP compressed file from the downloads section at + [kumbiaphp.com](http://www.kumbiaphp.com/blog/manuales-y-descargas/) to get the latest version of the framework. -This indicates that is enabled Apache mod_rewrite, but there is still tell Apache to interpret the .htaccess files that are responsible for the rewrite use and in turn have the rules rewrite URLs. + Make sure the file has the `.tgz` extension if you are using Linux, or `.zip` if you are using Windows; otherwise, it + may not decompress properly. -As an administrator user edit the next file. - -```bash - > vi /etc/apache2/sites-enabled/000-default -``` +2. Once downloaded, extract its contents into your preferred directory. + To keep this manual consistent, we will assume the package has been extracted into a directory named `kumbiaphp/`, + with a structure similar to the following: -```apacheconf - - Options Indexes FollowSymLinks - AllowOverride None - Order allow,deny - Allow from all - -``` + ``` + kumbiaphp/ + ├── core/ + ├── vendor/ + └── default/ + ├── app/ + ├── public/ + │ ├── .htaccess + │ └── index.php + ├── .htaccess + └── index.php + ``` -So that the .htaccess have effects, must replace *AllowOverride None* by *AllowOverride All* this way Apache can interpret these files. +3. Open a terminal and navigate to the `default/app` directory: -That done, restart the apache service. + ```bash + cd kumbiaphp/default/app + ``` -```bash - >/etc/init.d/apache2 restart -``` +4. Run the included development server: -Next, test all settings made by the following URL. + ```bash + ./bin/phpserver + ``` -http://localhost/kumbiaphp/ + This command starts a local web server using PHP’s built-in server, allowing you to run the application immediately + without additional configuration. -If all has gone well, you should see a welcome page, so the quick installation can be finished. +5. Open your web browser and go to: -![](../images/image12.png) + ``` + http://0.0.0.0:8001/ + ``` -Figure 2.1: Successful installation of KumbiaPHP + or -This is an environment test which is intended to practice with KumbiaPHP on a local server, not to develop complex applications that end up being published on the web. + ``` + http://127.0.0.1:8001/ + ``` -## Configure Nginx + If everything went well, you should see a welcome page indicating that the installation was successful. -Using `$_SERVER['PATH_INFO']`: + ![Successful installation](../images/successful-installation.jpg) -```nginx -server { - listen 80; - server_name localhost.dev; - root /var/www/kumbiaphp; - index index.php index.html index.htm; +> ℹ️ **Information** +> +> **Alternative: Using Apache or Nginx** — If you prefer, you can use a traditional web server such as Apache or Nginx. +> For that, refer to the section +> [Installing KumbiaPHP on Web Servers (Apache and Nginx)](installing-kumbiaphp-apache-nginx.md), where you will find +> detailed instructions. - location / { - try_files $uri $uri/ /index.php; - } +## Application Modes - location ~ \.php { - #fastcgi_pass unix:/run/php-fpm/php-fpm.sock; - fastcgi_pass 127.0.0.1:9000; - fastcgi_index /index.php; +KumbiaPHP offers two execution modes for an application, defined in the +[default/public/index.php](https://github.com/KumbiaPHP/KumbiaPHP/blob/master/default/public/index.php) file: - include fastcgi_params; - fastcgi_split_path_info ^(.+\.php)(/.+)$; - fastcgi_param PATH_INFO $fastcgi_path_info; - fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info; - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - } +### Development Mode - location ~ /\. { - deny all; - } -} -``` +This is the default mode. The `PRODUCTION` constant is set to `false`: -Using `$_GET['_url']`: - -```nginx -server { - listen 80; - server_name localhost.dev; - root /var/www/kumbiaphp; - index index.php index.html index.htm; - - location / { - try_files $uri $uri/ /index.php?_url=$uri&$args; - } - - location ~ \.php { - #fastcgi_pass unix:/run/php-fpm/php-fpm.sock; - fastcgi_pass 127.0.0.1:9000; - fastcgi_index /index.php; - - include fastcgi_params; - fastcgi_split_path_info ^(.+\.php)(/.+)$; - fastcgi_param PATH_INFO $fastcgi_path_info; - fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info; - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - } - - location ~ /\. { - deny all; - } -} +```php +const PRODUCTION = false; ``` -### Why is important Mod-Rewrite? - -ReWrite is an apache module that allows you to rewrite urls that our users have used. KumbiaPHP Framework encapsulates this complexity by allowing to use beautiful URLs or clean like that you see in blogs or in places where they do not appear the?, the & or server extensions (.php, .asp, .aspx, etc). - -In addition, with mod-rewrite KumbiaPHP can protect our applications to the possibility that users can see the project directories and can access class files, models, logic, etc., unless they are authorized. - -With mod-rewrite the only directory that users can see is public directory (public) of the web server content, the rest remains hidden and only can be viewed when you have made a request to properly and is also correct according to our application logic. When you write addresses using this type of URLs, are also helping the search engines to better index your information. +In this mode, KumbiaPHP’s cache is disabled. Any changes made to database tables or fields, as well as to views, are +reflected immediately. -## Modos de una Aplicación +### Production Mode -KumbiaPHP ofrece dos modos de ejecución de una aplicación el cual es indicado en el archivo [default/public/index.php](https://github.com/KumbiaPHP/KumbiaPHP/blob/master/default/public/index.php), se describen a continuación: +To enable it, change the `PRODUCTION` constant to `true`: -### Desarrollo - -Es el modo por defecto, en este caso el valor de la constante PRODUCTION es false: `const PRODUCTION = false;`. En éste la cache de KumbiaPHP está desactivada y cualquier cambio que se haga en los campos y tablas de la base de datos (adición o eliminación de campos, etc), vistas de la aplicación que se cacheen, surtirán efecto inmediatamente. - -### Producción - -Se activa asignando en el archivo [default/public/index.php](https://github.com/KumbiaPHP/KumbiaPHP/blob/master/default/public/index.php) el valor true a la constante PRODUCTION, así: `const PRODUCTION = true;`, en este la cache de KumbiaPHP esta activada y se cachea información necesaria para agilizar la carga de la aplicación tal como la metadata de la base datos (información de tablas y campos), asimismo las vistas que el usuario desee cachear. - -### ¡¡¡ ADVERTENCIA !!! +```php +const PRODUCTION = true; +``` -Cuando se efectua el cambio de `PRODUCTION = false;` a `PRODUCTION = true;`, es necesario eliminar el contenido del directorio de cache de la aplicación [default/app/temp/cache/*](https://github.com/KumbiaPHP/KumbiaPHP/tree/master/default/app/temp/cache) para que se renueve la metadata y no haya problemas al guardar o mostrar la información. +In this mode, KumbiaPHP enables its caching system, storing key information such as database metadata (table names, +fields, etc.) and any views you choose to cache, improving performance. -no se deben confundir con la conexión a la base de datos que se va usar , \ No newline at end of file +> ⚠️ **Warning** +> +> When changing `PRODUCTION` from `false` to `true`, you must manually delete the contents of the cache directory +> located at `default/app/temp/cache/` to ensure that metadata is refreshed correctly. If you don’t, you may encounter +> errors when saving or displaying information.