Development Environment Setup

Prerequisites

Before setting up your development environment, ensure your system meets these requirements:

System Requirements

PHP

Version: 8.1 or higherCheck version: php -v

Database

MySQL 5.7+ or PostgreSQL 9.6+Choose one based on your preference

Web Server

Apache 2.4+ or Nginx 1.18+With PHP-FPM support

Composer

Latest stable versionFor dependency management

Required PHP Extensions

Verify these extensions are installed:

php -m | grep -E "curl|gd|intl|mbstring|pdo_mysql|xml|zip"

Required Extensions List

curl: HTTP client for API requests
gd: Image processing
intl: Internationalization
mbstring: Multibyte string handling
pdo_mysql or pdo_pgsql: Database connectivity
xml: XML parsing
zip: ZIP file handling for plugins

Installing Extensions (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install php8.1-cli php8.1-curl php8.1-gd php8.1-intl \
                     php8.1-mbstring php8.1-mysql php8.1-xml php8.1-zip

Installing Extensions (macOS with Homebrew)

brew install [email protected]
brew install composer

Installation

Step 1: Clone the Repository

Clone FacturaScripts from GitHub:

# Clone the repository
git clone https://github.com/NeoRazorX/facturascripts.git
cd facturascripts

# Checkout the stable branch (recommended for development)
git checkout stable

Use the stable branch for plugin development. The master branch contains the latest development code and may be unstable.

Step 2: Install Dependencies

Install PHP dependencies using Composer:

composer install

This will install:

Twig template engine
Symfony components
Testing frameworks
Other required libraries

Step 3: Configure the Web Server

Apache
Nginx
PHP Built-in Server

Create a virtual host configuration:

<VirtualHost *:80>
    ServerName facturascripts.local
    DocumentRoot /path/to/facturascripts
    
    <Directory /path/to/facturascripts>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/facturascripts-error.log
    CustomLog ${APACHE_LOG_DIR}/facturascripts-access.log combined
</VirtualHost>

Enable required modules and restart:

sudo a2enmod rewrite
sudo systemctl restart apache2

Add to /etc/hosts:

127.0.0.1 facturascripts.local

Create a server block:

server {
    listen 80;
    server_name facturascripts.local;
    root /path/to/facturascripts;
    index index.php index.html;
    
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
    
    location ~ /\.ht {
        deny all;
    }
}

Test configuration and restart:

sudo nginx -t
sudo systemctl restart nginx

Add to /etc/hosts:

127.0.0.1 facturascripts.local

For quick development (not for production):

php -S localhost:8000

Access at: http://localhost:8000

The built-in server is single-threaded and should only be used for development/testing.

Step 4: Set Directory Permissions

FacturaScripts needs write access to specific directories:

# Create necessary directories
mkdir -p MyFiles Dinamic Plugins

# Set permissions (adjust user/group for your system)
chmod -R 775 MyFiles Dinamic Plugins
chown -R www-data:www-data MyFiles Dinamic Plugins

# Or for development (less secure, but easier):
chmod -R 777 MyFiles Dinamic Plugins

Step 5: Create Database

Create a database for FacturaScripts:

MySQL
PostgreSQL

CREATE DATABASE facturascripts CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'fs_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON facturascripts.* TO 'fs_user'@'localhost';
FLUSH PRIVILEGES;

CREATE DATABASE facturascripts;
CREATE USER fs_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE facturascripts TO fs_user;

Step 6: Initial Setup

Visit your FacturaScripts installation in a browser:

http://facturascripts.local

You’ll see the installation wizard. Complete these steps:

Database Configuration

Database Type: MySQL or PostgreSQL
Host: localhost (or 127.0.0.1)
Port: 3306 (MySQL) or 5432 (PostgreSQL)
Database Name: facturascripts
Username: fs_user
Password: Your database password

Admin Account

Username: Choose an admin username
Email: Your email address
Password: Secure password

Development Tools Setup

Code Editor Configuration

VS Code
PHPStorm

Recommended extensions:

{
  "recommendations": [
    "bmewburn.vscode-intelephense-client",
    "xdebug.php-debug",
    "whatwedo.twig",
    "editorconfig.editorconfig",
    "recca0120.vscode-phpunit"
  ]
}

Create .vscode/settings.json:

{
  "php.suggest.basic": false,
  "intelephense.files.exclude": [
    "**/node_modules/**",
    "**/vendor/**",
    "**/Dinamic/**"
  ],
  "files.associations": {
    "*.twig": "twig"
  }
}

Open FacturaScripts directory as a project
Configure PHP interpreter:
- Settings → PHP → CLI Interpreter
- Add your PHP 8.1+ installation
Enable Composer:
- Settings → PHP → Composer
- Point to composer.json
Configure Xdebug:
- Settings → PHP → Debug
- Set port to 9003
Mark directories:
- Right-click Dinamic → Mark Directory as → Excluded
- Right-click vendor → Mark Directory as → Excluded

Xdebug Setup (Optional but Recommended)

Install Xdebug for debugging:

# Install Xdebug
sudo apt-get install php8.1-xdebug

# Or with PECL
sudo pecl install xdebug

Configure Xdebug in php.ini or create /etc/php/8.1/mods-available/xdebug.ini:

zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003
xdebug.client_host=localhost

Restart your web server:

sudo systemctl restart apache2
# or
sudo systemctl restart php8.1-fpm

Git Configuration

Set up Git for version control:

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Create .gitignore for your plugin
cat > .gitignore << EOF
/MyFiles/
/Dinamic/
/vendor/
/node_modules/
config.php
.env
*.log
EOF

Creating Your First Plugin

Step 1: Create Plugin Directory

# Create plugin structure
mkdir -p Plugins/MyFirstPlugin/{Controller,Model,View,Assets}
cd Plugins/MyFirstPlugin

Step 2: Create Plugin Metadata

Create facturascripts.ini:

name = "MyFirstPlugin"
version = 1.0
min_version = 2024.1
description = "My first FacturaScripts plugin"
author = "Your Name"

Step 3: Create Initialization File

Create Init.php:

<?php
namespace FacturaScripts\Plugins\MyFirstPlugin;

use FacturaScripts\Core\Base\InitClass;

class Init extends InitClass
{
    public function init(): void
    {
        // Plugin initialization code
    }
    
    public function update(): void
    {
        // Update logic when plugin version changes
    }
}

Step 4: Create a Simple Controller

Create Controller/HelloWorld.php:

<?php
namespace FacturaScripts\Plugins\MyFirstPlugin\Controller;

use FacturaScripts\Core\Base\Controller;

class HelloWorld extends Controller
{
    public function getPageData(): array
    {
        $data = parent::getPageData();
        $data['title'] = 'Hello World';
        $data['icon'] = 'fa-solid fa-hand-wave';
        $data['menu'] = 'admin';
        return $data;
    }
    
    public function privateCore(&$response, $user, $permissions): void
    {
        parent::privateCore($response, $user, $permissions);
        // Your controller logic here
    }
}

Step 5: Create a View Template

Create View/HelloWorld.html.twig:

{% extends "Master/MenuTemplate.html.twig" %}

{% block body %}
<div class="container-fluid">
    <div class="row">
        <div class="col-12">
            <h1>Hello World!</h1>
            <p>Welcome to your first FacturaScripts plugin.</p>
        </div>
    </div>
</div>
{% endblock %}

Step 6: Activate Your Plugin

Access Plugin Manager

Navigate to: Admin → Plugins (or /AdminPlugins)

Find Your Plugin

Your plugin “MyFirstPlugin” should appear in the list

Enable Plugin

Click the toggle or “Enable” button

Wait for Deployment

FacturaScripts will:

Merge your plugin code into Dinamic/
Rebuild routes
Update database schema

Access Your Controller

Visit: http://facturascripts.local/HelloWorld

After enabling your plugin, you’ll find the merged code in Dinamic/Controller/HelloWorld.php. This is the actual file that gets executed.

Development Workflow

Making Changes

When developing plugins:

Edit Source Files

Make changes in Plugins/YourPlugin/ directory

Redeploy

Go to Admin → Plugins and click “Deploy” or “Rebuild”

Test Changes

Changes are merged into Dinamic/ and immediately active

Debug Issues

Check logs in MyFiles/ directory

Using the Command Line

FacturaScripts provides CLI tools:

# Rebuild routes
php index.php rebuildRoutes

# Update database
php index.php updateDB

# Clear cache
php index.php clearCache

# Run cron tasks
php index.php cron

Debugging Tips

Enable Debug Mode

Edit config.php (create if it doesn’t exist):

<?php
define('FS_DEBUG', true);

This enables verbose error messages.

Check Logs

Logs are stored in:

Application logs: MyFiles/error.log
Web server logs: /var/log/apache2/ or /var/log/nginx/
PHP errors: Check php.ini for error_log location

Database Queries

Enable query logging in config.php:

define('FS_DB_LOG', true);

Queries are logged to MyFiles/database.log

Use var_dump()

For quick debugging:

var_dump($variable);
exit; // Stop execution

Or use FacturaScripts logger:

use FacturaScripts\Core\Tools;

Tools::log()->debug('Variable value: ' . print_r($variable, true));

Testing

PHPUnit Setup

FacturaScripts includes PHPUnit for testing:

# Run all tests
./vendor/bin/phpunit

# Run specific test
./vendor/bin/phpunit tests/Core/KernelTest.php

# Run plugin tests
./vendor/bin/phpunit -c phpunit-plugins.xml

Writing Tests

Create Test/ directory in your plugin:

<?php
namespace FacturaScripts\Test\Plugins\MyFirstPlugin;

use PHPUnit\Framework\TestCase;

class MyTest extends TestCase
{
    public function testExample(): void
    {
        $this->assertTrue(true);
    }
}

Troubleshooting

White Screen / 500 Error

Check PHP error logs
Verify file permissions (775 or 777 for development)
Ensure all required PHP extensions are installed
Check .htaccess file exists (copy from htaccess-sample)

Plugin Not Appearing

Verify facturascripts.ini exists and is valid
Check plugin directory name matches name in INI file
Ensure Plugins/ directory has correct permissions
Try refreshing the plugin list

Changes Not Visible

Click “Deploy” in Plugin Manager to rebuild Dinamic/
Clear browser cache (Ctrl+Shift+R)
Check if you’re editing the right file (not Dinamic/)
Verify plugin is enabled

Database Connection Failed

Verify database credentials in installer or config.php
Check database server is running
Test connection with mysql -u fs_user -p or psql -U fs_user
Ensure user has correct privileges

Next Steps

Now that your development environment is ready:

Creating Plugins

Learn to build complete plugins with models, controllers, and views.

Controllers

Master controller development and request handling.

Models & Database

Work with the ORM and database layer.

Best Practices

Follow coding standards and best practices.

Join the FacturaScripts community on GitHub for help, discussions, and to share your plugins!

Getting Started

Plugin Development

API Reference

Advanced

​Prerequisites

​System Requirements

PHP

Database

Web Server

Composer

​Required PHP Extensions

​Installation

​Step 1: Clone the Repository

​Step 2: Install Dependencies

​Step 3: Configure the Web Server

​Step 4: Set Directory Permissions

​Step 5: Create Database

​Step 6: Initial Setup

​Development Tools Setup

​Code Editor Configuration

​Xdebug Setup (Optional but Recommended)

​Git Configuration

​Creating Your First Plugin

​Step 1: Create Plugin Directory

​Step 2: Create Plugin Metadata

​Step 3: Create Initialization File

​Step 4: Create a Simple Controller

​Step 5: Create a View Template

​Step 6: Activate Your Plugin

​Development Workflow

​Making Changes

​Using the Command Line

​Debugging Tips

​Testing

​PHPUnit Setup

​Writing Tests

​Troubleshooting

​Next Steps

Creating Plugins

Controllers

Models & Database

Best Practices

Build docs developers (and LLMs) love

Prerequisites

System Requirements

Required PHP Extensions

Installation

Step 1: Clone the Repository

Step 2: Install Dependencies

Step 3: Configure the Web Server

Step 4: Set Directory Permissions

Step 5: Create Database

Step 6: Initial Setup

Development Tools Setup

Code Editor Configuration

Xdebug Setup (Optional but Recommended)

Git Configuration

Creating Your First Plugin

Step 1: Create Plugin Directory

Step 2: Create Plugin Metadata

Step 3: Create Initialization File

Step 4: Create a Simple Controller

Step 5: Create a View Template

Step 6: Activate Your Plugin

Development Workflow

Making Changes

Using the Command Line

Debugging Tips

Testing

PHPUnit Setup

Writing Tests

Troubleshooting

Next Steps