Skip to Content
ModulesModule Dependencies

Module Dependencies

The module.json file is the central configuration file for the module. It defines metadata, providers, and module dependencies.

module.json Structure

Basic Example

{
    "name": "Blog",
    "version": "1.0.0",
    "description": "Blog module for publishing articles",
    "authors": ["Developer"],
    "providers": [
        "Flute\\Modules\\Blog\\Providers\\BlogProvider"
    ],
    "dependencies": {
        "php": ">=8.2",
        "flute": ">=1.0.0"
    }
}

Full Example with All Dependencies

{
    "name": "Shop",
    "version": "1.2.0",
    "description": "Online Store Module",
    "authors": ["Development Team"],
    "url": "https://github.com/example/shop",
    "providers": [
        "Flute\\Modules\\Shop\\Providers\\ShopProvider",
        "Flute\\Modules\\Shop\\Providers\\ShopAdminProvider"
    ],
    "dependencies": {
        "php": ">=8.2",
        "flute": ">=1.0.0",
        "modules": {
            "Payments": ">=1.0.0",
            "Notifications": ">=1.0.0"
        },
        "extensions": ["gd", "mbstring", "curl"],
        "composer": {
            "intervention/image": "^2.7",
            "guzzlehttp/guzzle": "^7.0"
        },
        "theme": {
            "standard": ">=1.0.0"
        }
    }
}

Configuration Parameters

ParameterTypeRequiredDescription
namestring✅Unique module name
versionstring✅Version in semver format
descriptionstring❌Module description
authorsarray❌List of authors
urlstring❌Project URL
providersarray✅Provider classes
dependenciesobject❌Module dependencies

Providers

Single Provider

Most modules have one provider:

{
    "providers": [
        "Flute\\Modules\\Blog\\Providers\\BlogProvider"
    ]
}

Multiple Providers

For complex modules, logic can be split into multiple providers:

{
    "providers": [
        "Flute\\Modules\\Shop\\Providers\\ShopProvider",
        "Flute\\Modules\\Shop\\Providers\\ShopAdminProvider",
        "Flute\\Modules\\Shop\\Providers\\ShopApiProvider"
    ]
}

Provider Priority

Load order can be set via an object with order:

{
    "providers": [
        { "class": "Flute\\Modules\\Core\\Providers\\CoreProvider", "order": 10 },
        { "class": "Flute\\Modules\\Core\\Providers\\PluginsProvider", "order": 20 }
    ]
}

Providers are sorted by order regardless of their position in the array. Lower value — earlier load.

Types of Dependencies

PHP Version

{
    "dependencies": {
        "php": ">=8.2"
    }
}

Supported operators:

  • >= — greater than or equal
  • > — strictly greater than
  • <= — less than or equal
  • < — strictly less than
  • == — equal
  • != — not equal

Flute CMS Version

{
    "dependencies": {
        "flute": ">=1.0.0"
    }
}

Dependencies on Other Modules

If your module requires other modules to work:

{
    "dependencies": {
        "modules": {
            "Payments": ">=1.0.0",
            "Notifications": ">=1.0.0",
            "Users": ">=2.0.0"
        }
    }
}

If a dependent module is missing or has an incorrect version, your module will be automatically disabled.

PHP Extensions

{
    "dependencies": {
        "extensions": [
            "gd",
            "mbstring",
            "curl",
            "zip",
            "intl"
        ]
    }
}

Composer Packages

{
    "dependencies": {
        "composer": {
            "intervention/image": "^2.7",
            "laravel/socialite": "^5.5",
            "guzzlehttp/guzzle": "^7.0"
        }
    }
}

Composer packages are checked via InstalledVersions. Automatic installation is not performed — packages must be added to the main project composer.json.

Theme Dependencies

{
    "dependencies": {
        "theme": {
            "standard": ">=1.0.0"
        }
    }
}

How the Dependency System Works

Initialization

At startup, ModuleManager checks the dependencies of each active module. State hash is cached for one hour.

Check

All types of dependencies are checked: PHP, Flute, modules, extensions, Composer, theme.

Auto-Disable

Upon dependency error, the module is automatically switched to disabled status, and cache is rebuilt.

Manual Dependency Check

Additional checks can be added in the module provider:

<?php
namespace Flute\Modules\Blog\Providers;
 
use Flute\Core\Support\ModuleServiceProvider;
 
class BlogProvider extends ModuleServiceProvider
{
    public function boot(\DI\Container $container): void
    {
        $this->checkDependencies();
        $this->bootstrapModule();
    }
 
    protected function checkDependencies(): void
    {
        // Check module presence
        if (!modules()->issetModule('Payments')) {
            logs('blog')->warning('Module Payments not found. Some functions disabled.');
        }
 
        // Check module version
        $module = modules()->getModule('Payments');
        if ($module && version_compare($module->version, '1.0.0', '<')) {
            logs('blog')->error('Payments version >= 1.0.0 required');
        }
 
        // Check PHP extension
        if (!extension_loaded('gd')) {
            logs('blog')->warning('GD extension not loaded. Image processing disabled.');
        }
    }
}

Versioning

Semantic Versioning (SemVer)

MAJOR.MINOR.PATCH

Examples:
1.0.0 — stable release
1.1.0 — new functionality (backward compatible)
1.0.1 — bug fixes
2.0.0 — incompatible API changes
1.0.0-beta — beta version
1.0.0-rc.1 — release candidate

Rules:

  • MAJOR — for incompatible API changes
  • MINOR — for adding functionality while maintaining compatibility
  • PATCH — for bug fixes

Practical Examples

Simple Module without Dependencies

{
    "name": "Blog",
    "version": "1.0.0",
    "description": "Simple blog module",
    "authors": ["Developer"],
    "providers": [
        "Flute\\Modules\\Blog\\Providers\\BlogProvider"
    ],
    "dependencies": {
        "php": ">=8.2",
        "flute": ">=1.0.0"
    }
}

Module with Dependency on Another Module

{
    "name": "Shop",
    "version": "1.2.1",
    "description": "Online store module",
    "authors": ["Team"],
    "providers": [
        "Flute\\Modules\\Shop\\Providers\\ShopProvider"
    ],
    "dependencies": {
        "php": ">=8.2",
        "flute": ">=1.0.0",
        "modules": {
            "GiveCore": ">=1.0.0"
        }
    }
}

Module with Composer Dependencies

{
    "name": "ImageGallery",
    "version": "1.0.0",
    "description": "Image Gallery",
    "providers": [
        "Flute\\Modules\\ImageGallery\\Providers\\GalleryProvider"
    ],
    "dependencies": {
        "php": ">=8.2",
        "flute": ">=1.0.0",
        "extensions": ["gd"],
        "composer": {
            "intervention/image": "^2.7"
        }
    }
}

Troubleshooting

Typical Errors and Solutions

Module "Blog" dependency check failed - Module "Payments" version 1.0.0 or higher is required

Solution: Install or update the required Payments module.

Programmatic Diagnostics

<?php
use Flute\Core\ModulesManager\ModuleManager;
 
$moduleManager = app(ModuleManager::class);
 
// Get module information
$module = $moduleManager->getModule('Blog');
echo "Status: " . $module->status;
echo "Version: " . $module->version;
 
// Check existence
if ($moduleManager->issetModule('Payments')) {
    echo "Module Payments is installed";
}
 
// Get active modules
$activeModules = $moduleManager->getActive();
foreach ($activeModules as $name => $info) {
    echo "{$name}: {$info->version}";
}

Best Practices

Minimize Dependencies

Specify only truly necessary modules and packages.

Use Version Ranges

>=1.0.0 instead of exact version 1.0.0 for better compatibility.

Document Dependencies

In the module README, describe why certain dependencies are needed.

Test Compatibility

Check module operation with different versions of dependencies.

Follow SemVer

Use semantic versioning for your modules.

Database & ORMPayments & Widgets