Magiiic.org

Project Category: OpenSimulator Library

  • OpenSimulator REST PHP library and command-line client

    Version 1.0.6 Stable 1.0.6 Requires PHP 7.4 License AGPLv3

    This library allows to communicate with Robust or OpenSimulator instance with rest console enabled.

    It can be used inside a PHP project, or as a command-line client for OpenSimulator grids.

    Available commands can be found here: http://opensimulator.org/wiki/Server_Commands

    Prerequisites

    Remote connection must be enabled in your Robust .ini file.

    Do not leave default values!. You should never need to type username and password manually, so you can safely generate long random strings.

    You must choose a specific port, not already used by another service. It is good practice to limit access to this port to authorized IP addresses only in your firewall settings.

    [Network]
  ConsoleUser = arandomgeneratedstring
  ConsolePass = anotherrandomgeneratedstring
  ConsolePort = 8009
  ; choose a port not already used by another service

    Command-line client

    Download the executable from this repository, make sure opensim-rest-cli is executable and move it to /usr/local/bin/.

    chmod +x /path/to/opensim-rest-cli
sudo mv /path/to/opensim-rest-cli /usr/local/bin/opensim-rest-cli

    You can run commands like

    opensim-rest-cli /path/to/Robust.ini show info
opensim-rest-cli /path/to/Robust.ini show regions

    If you save the credentials in ~/.opensim-rest-cli.ini, you can skip the Robust.ini argument.

    opensim-rest-cli show info
opensim-rest-cli show regions

    PHP class

    Method 1: Install with composer (recommended for standalone projects)

    composer require magicoli/opensim-rest-php

    Then in your PHP code:

    
require_once 'vendor/autoload.php';

    $session = opensim_rest_session( array( ‘uri’ => "yourgrid.org:8009", ‘ConsoleUser’ => ‘yourConsoleUsername’, ‘ConsolePass’ => ‘yourConsolePassword’, ) );

    if ( is_opensim_rest_error($session) ) { error_log( "OpenSim_Rest error: " . $session->getMessage() ); } else { $responseLines = $session->sendCommand($command); }

    Return value: an array containing the line(s) of response or a PHP Error

    Method 2: Git Submodule + sparse (recommended for integrated projects)

    Setting sparse config is critical to avoid executables being accessible on public website.

    From your project directory:

    
git submodule add https://github.com/magicoli/opensim-rest-php.git opensim-rest
cd opensim-rest
git config core.sparseCheckout true

    echo ‘‘ > $(git rev-parse –git-dir)/info/sparse-checkout echo ‘!bin/‘ >> $(git rev-parse –git-dir)/info/sparse-checkout echo ‘!dev/*’ >> $(git rev-parse –git-dir)/info/sparse-checkout echo ‘!opensim-rest-cli.php’ >> $(git rev-parse –git-dir)/info/sparse-checkout echo ‘!composer.lock’ >> $(git rev-parse –git-dir)/info/sparse-checkout

    git read-tree -m -u HEAD

    This will give you only the files you need:

    opensim-rest/
├── class-rest.php
├── composer.json
├── LICENSE
└── README.md

    Then in your PHP code:

    require_once dirname(__FILE__) . '/opensim-rest/class-rest.php';
// Same usage as above

    Method 3: Manual download (not recommended)

    You won’t get updates…

    Download class-rest.php file in your project or

  • OpenSimulator Engine

    Version 3.0.0-dev Stable none Requires PHP 7.4 License AGPLv3

    Framework-agnostic PHP library for OpenSimulator grid management

    ⚠️ Important Notice

    This is a pure PHP library – it does nothing by itself!

    The OpenSimulator Engine provides core functionality for managing OpenSim grids, but requires a parent application to function. It handles database operations, configuration management, and OpenSim protocol communication, but provides no user interface or web endpoints.

    📜 Project History

    This library consolidates over a decade of OpenSimulator integration work that was previously scattered across multiple projects. While the dedicated engine repository is recent, the functionality has evolved through years of real-world usage in production OpenSim grids.

    The code has been battle-tested across different implementations before being organized into this reusable, framework-agnostic library.

    🎯 What This Library Does

    • ✅ Database Operations – Robust/OpenSim database management
    • ✅ OpenSim Protocol – REST API communication with grids
    • ✅ Configuration Management – Grid and region settings management and storage
    • ✅ Security Functions – Input validation and output escaping
    • ✅ Form Generation – Dynamic configuration forms
    • ✅ Installation – Process setup automation (initiated by parent)

    🚫 What This Library Does NOT Do

    • ❌ No web interface or HTML pages
    • ❌ No user HTTP request handling
    • ❌ No user authentication
    • ❌ No WordPress or other CMS/framework dependencies
    • ❌ No standalone application functionality

    For Developers:

    • Use this engine to build your own OpenSim management applications
    • Integrate OpenSim functionality into existing PHP projects
    • Create custom grid administration tools

    🚀 Quick Start for End Users

    Don’t install this directly! Instead, choose a complete solution:

    • W4OS WordPress Plugin – Complete WordPress integration for OpenSim grids. Best for: Complete integration in a WordPress website.
    • OpenSim Helpers – Provides mainly helpers/ required by OpenSim grids to function properly, as well as minimal webui features. Best for: Separate helpers management, with minimal integration with the website.

    🛠️ Developer Installation

    As Composer Package

    composer require magicoli/opensim-engine

    As Git Submodule

    git submodule add https://github.com/magicoli/opensim-engine.git engine

    Usage in Code

    
// Bootstrap the engine
require_once 'engine/bootstrap.php';
// or require_once 'vendor/magicoli/opensim-engine/bootstrap.php' if installed via composer

    // Engine provides the core classes and functions // See parent projects (W4OS, Helpers) for implementation examples

    📚 Documentation

    • Developer Guide – Architecture rules and patterns
    • API Reference – (planned after migration completion)
    • Examples – (planned after migration completion)

    🤝 Contributing

    This library follows strict architectural principles:

    • Framework-agnostic (no WordPress, no Laravel, etc.)
    • Pure data processing (no HTTP input/output)
    • Explicit data passing (no global variables)

    See DEVELOPERS.md for complete guidelines.

    Note: The library is undergoing architectural migration. API documentation and examples will be added once the refactoring is complete and the API is stable.

    📄 License

    AGPLv3 – See LICENSE file for details.

    🆘 Support