README

A powerful Composer plugin that simplifies the installation of modules for the webtrees genealogy application by automatically placing them in the correct directory structure.

🚀 Seamless Integration

Automatically installs webtrees modules to the correct modules_v4 directory without manual file copying.

⚙️ Easy Configuration

Simple setup with minimal configuration required in your composer.json file.

🌟 Why Use This Plugin?

When developing or using modules for webtrees, managing the installation process can be cumbersome. This plugin solves that problem by:

Automatically detecting and installing modules with the webtrees-module type
Placing modules in the correct modules_v4 directory structure
Supporting both direct installation and installation via a separate composer.json
Eliminating the need for manual file copying or symlink creation

📋 Requirements

System Requirements

PHP 8.2 or higher (compatible up to PHP 8.4)
Composer 2.6 or higher

🔧 Installation

Add this plugin to the require or require-dev section of your composer.json file:

"require": {
    "magicsunday/webtrees-module-installer-plugin": "^1.6"
},

Or install it using Composer:

composer require magicsunday/webtrees-module-installer-plugin

Make sure to allow the plugin in your composer.json:

"config": {
    "allow-plugins": {
        "magicsunday/webtrees-module-installer-plugin": true
    }
}

📦 Usage

For Module Users

To install a webtrees module with composer, simply require the module in your composer.json:

composer require vendor-name/module-name

The plugin will automatically install the module to the modules_v4 directory.

For Module Developers

When creating a webtrees module, set the package type to webtrees-module in your module's composer.json:

{
    "name": "your-vendor-name/your-module-name",
    "description": "Your module description",
    "type": "webtrees-module",
    "require": {
        "php": ">=8.2.0"
    }
}

Pro Tip

The module name in the composer.json file will determine the directory name in the modules_v4 directory.

Installing from GitHub

If your module is not listed on Packagist, you can install it directly from GitHub:

composer config repositories.your-repo-name vcs https://github.com/your-vendor-name/your-module-name
composer require your-vendor-name/your-module-name[:optional-branch-name]

For example, to install the dev-master branch:

composer require your-vendor-name/your-module-name:dev-master

🧪 Testing

The plugin includes several testing tools to ensure code quality:

# Run all tests
composer ci:test

# Run specific tests
composer ci:test:php:phpstan  # Static analysis
composer ci:test:php:lint     # PHP linting
composer ci:test:php:rector   # Code quality checks
composer ci:test:php:cgl      # Coding guidelines

🔍 How It Works

The plugin works by:

Registering a custom installer with Composer's installation manager
Detecting packages with the webtrees-module type
Determining the correct installation path in the modules_v4 directory
Handling both direct installation and installation via a separate composer.json

The main components are:

ModuleInstallerPlugin: Implements Composer's PluginInterface
ModuleInstaller: Extends Composer's LibraryInstaller to handle module installation
Config: Manages configuration settings and path resolution

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please make sure your code follows the project's coding standards by running the tests before submitting.

📄 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🙏 Acknowledgements

webtrees - The open source web genealogy application
Composer - Dependency Manager for PHP

magicsunday / webtrees-module-installer-plugin

Maintainers

Details