Skip to main content
Plugins are the primary way to extend FacturaScripts functionality. This guide will walk you through creating your first plugin.

​
Overview

A FacturaScripts plugin is a self-contained package that can add new features, modify existing functionality, or integrate external services. Plugins are stored in the Plugins/ directory and are managed through the admin interface.

​
Plugin Requirements

  • FacturaScripts 2025 or higher
  • PHP 8.0 or higher (configurable per plugin)
  • A unique plugin name (alphanumeric, no spaces)
  • A valid facturascripts.ini file

​
Creating Your First Plugin

​
Step 1: Create the Plugin Directory

Create a new directory in Plugins/ with your plugin name: 
mkdir Plugins/MyPlugin
cd Plugins/MyPlugin
Plugin names must be alphanumeric and should follow PascalCase convention (e.g., MyPlugin, SalesReport, CustomInvoice).

​
Step 2: Create facturascripts.ini

Every plugin must have a facturascripts.ini file in its root directory: 
name = "MyPlugin"
description = "My first FacturaScripts plugin"
version = 1.0
min_version = 2025.0
min_php = 8.0
require = ""
require_php = ""
Configuration fields:
  • name: Exact plugin name (must match directory name)
  • description: Brief description of the plugin
  • version: Plugin version number
  • min_version: Minimum FacturaScripts version required
  • min_php: Minimum PHP version required (default: 8.0)
  • require: Comma-separated list of required plugins
  • require_php: Comma-separated list of required PHP extensions

​
Step 3: Create the Init Class (Optional)

The Init.php class handles plugin lifecycle events: 
<?php
namespace FacturaScripts\Plugins\MyPlugin;

use FacturaScripts\Core\Base\InitClass;

class Init extends InitClass
{
    /**
     * Called when the plugin is first enabled or updated
     */
    public function update()
    {
        // Run migrations, create database tables, etc.
    }

    /**
     * Called on every request when plugin is enabled
     */
    public function init()
    {
        // Register event listeners, modify core behavior, etc.
    }

    /**
     * Called when the plugin is disabled
     */
    public function uninstall()
    {
        // Clean up data, remove database tables, etc.
    }
}
The uninstall() method should only remove plugin-specific data, not user data unless explicitly requested.

​
Step 4: Define Your Plugin Structure

A typical plugin structure: 
Plugins/MyPlugin/
├── facturascripts.ini    # Plugin metadata (required)
├── Init.php              # Lifecycle hooks (optional)
├── Controller/           # Custom controllers
│   └── MyController.php
├── Model/                # Data models
│   └── MyModel.php
├── Table/                # Database table definitions
│   └── mymodel.xml
├── XMLView/              # View definitions
│   └── EditMyModel.xml
├── Assets/               # Static assets (CSS, JS, images)
│   ├── CSS/
│   └── JS/
├── Translation/          # Language files
│   ├── en_EN.json
│   └── es_ES.json
└── Extension/            # Extensions to core classes
    └── Controller/

​
Installing Your Plugin

​
Method 1: Direct Installation

  1. Copy your plugin folder to Plugins/
  2. Navigate to Admin > Plugins in FacturaScripts
  3. Find your plugin in the list
  4. Click Enable

​
Method 2: ZIP Installation

  1. Create a ZIP file with your plugin folder inside: 
    zip -r MyPlugin.zip MyPlugin/
  2. The ZIP structure must be: 
    MyPlugin.zip
└── MyPlugin/
    ├── facturascripts.ini
    └── ...
  3. Upload via Admin > Plugins > Upload Plugin
The facturascripts.ini file must be in a single root directory within the ZIP. Multi-directory ZIPs will be rejected.

​
Plugin Lifecycle

​
Enable Process

  1. FacturaScripts checks plugin compatibility (min_version, min_php)
  2. Verifies all dependencies are installed
  3. Marks plugin as enabled in MyFiles/plugins.json
  4. Calls Init::update() method
  5. Deploys plugin assets and routes
  6. Calls Init::init() on subsequent requests

​
Disable Process

  1. Marks plugin as disabled
  2. Calls Init::uninstall() method
  3. Redeploys system without plugin assets
  4. Removes plugin routes

​
Update Process

  1. Extracts new version over existing plugin
  2. Marks post_enable = true if plugin was already enabled
  3. Calls Init::update() to run migrations
  4. Redeploys assets and routes

​
Plugin Dependencies

Specify required plugins in facturascripts.ini: 
require = "OtherPlugin,AnotherPlugin"
FacturaScripts will:
  • Prevent enabling your plugin if dependencies are not installed
  • Show a warning about missing dependencies
  • Ensure dependency plugins load before yours
Specify required PHP extensions: 
require_php = "curl,gd,zip"

​
Best Practices

Namespace Convention

Always use FacturaScripts\Plugins\YourPlugin as the base namespace

Avoid Core Modifications

Never modify core files. Use extensions and events instead

Version Control

Keep your plugin in Git and increment version numbers on changes

Test Thoroughly

Test enabling, disabling, and updating your plugin

​
Testing Your Plugin

  1. Fresh Installation: Test enabling the plugin on a clean FacturaScripts installation
  2. With Data: Test with existing data to ensure compatibility
  3. Update Path: Test updating from a previous version
  4. Dependencies: Test with and without required plugins
  5. Disable/Enable: Test disabling and re-enabling the plugin

​
Next Steps

Plugin Structure

Learn about directory structure and configuration

Controllers

Create custom controllers for your plugin

Models

Define data models and database tables

Views

Create user interfaces with XMLViews

​
Common Issues

  • Ensure facturascripts.ini exists in the plugin root
  • Check that the plugin name in the INI matches the folder name
  • Verify file permissions (must be readable by web server)
  • Check min_version is not higher than your FacturaScripts version
  • Verify all required plugins are installed and enabled
  • Check PHP version meets min_php requirement
  • Review error logs for specific compatibility issues
  • Check namespace declarations match plugin name
  • Verify class names follow FacturaScripts conventions
  • Run Deploy from admin panel to refresh routes
  • Check error logs for PHP errors

Build docs developers (and LLMs) love

Get started for freeTalk to us