Repository Publishing

Repository & Publishing

Razy uses GitHub repositories as module registries. You can publish packed modules to a repository, install modules from remote repositories, search for available packages, and sync distributor dependencies automatically.

Overview

The publishing and installation workflow:

1. Pack — Create .phar archives from modules (see Packaging).

2. Publish — Push packed modules to a GitHub repository with auto-generated index.json.

3. Install — Fetch and install modules from repositories into your project.

4. Sync — Automatically install all modules defined in a distributor's repository config.

repository.inc.php

The repository configuration file at the project root lists GitHub repositories to fetch modules from:

return [

    'https://github.com/owner/module-repo/' => 'main',

    'https://github.com/owner/another-repo/' => 'releases',

];

Each key is a GitHub repository URL, and the value is the branch name to fetch from. The framework reads index.json from the specified branch to discover available modules.

packages/ Directory

To host your own module repository, structure your packages/ directory as follows:

packages/

→?→ index.json           // Master module index

→?→ publish.inc.php      // Publishing credentials (DO NOT COMMIT)

→?→ vendor/

    →?→ module/

        →?→ 1.0.0.phar   // Packed module archives

The packages/ directory acts as your local repository. Packed modules are stored in vendor-namespaced subdirectories, and index.json provides the master index for discovery.

index.json Format

The index.json file is auto-generated by the publish command. It catalogs all available modules:

{

    "vendor/module": {

        "description": "Module description",

        "author": "Author",

        "latest": "1.0.0",

        "versions": ["1.0.0"]

    }

}

Each module entry includes its description, author, latest version, and a list of all available versions. This file is used by the CLI to resolve module dependencies during installation.

publish.inc.php

Credentials for pushing to a GitHub repository. Do not commit this file — add it to .gitignore:

return [

    'token' => 'ghp_xxx',    // GitHub Personal Access Token

    'repo' => 'owner/repo',  // Target repository

];

The token requires repo scope permissions to push files to the target repository.

Publishing Workflow

The full publishing workflow: pack your modules, then publish to a GitHub repository:

# Step 1: Pack the module

php Razy.phar pack vendor/module 1.0.0



# Step 2: Publish — scan, generate index, and push

php Razy.phar publish --scan --push

The publish command scans the packages/ directory, auto-generates index.json, and pushes everything to the configured GitHub repository.

| Option | Description |

| --- | --- |

| --push | Push to the GitHub repository after generating index |

| --branch=NAME | Target branch name (default: main) |

| --dist=CODE | Limit to modules from a specific distributor |

| --scan | Scan packages/ directory for new modules |

| --include-shared | Include shared modules in the scan |

| --cleanup | Remove orphaned entries from index |

| --dry-run | Preview changes without pushing |

| --force | Force overwrite existing versions |

| -v | Verbose output |

Installing from Repositories

Install modules from any configured or specified repository:

php Razy.phar install owner/repo[@version] [path] [options]

| Option | Description |

| --- | --- |

| --latest | Install the latest available version |

| --stable | Install the latest stable version |

| --version=VER | Install a specific version |

| --branch=NAME | Fetch from a specific branch |

| --from-repo | Use repository URL directly |

| --name=NAME | Rename the module on install |

| --dist=CODE | Install into a specific distributor |

| --token=TOKEN | GitHub token for private repositories |

| --yes | Auto-confirm prompts |

Searching Modules

Search for modules across all configured repositories:

php Razy.phar search <query> [--verbose] [--refresh]

| Option | Description |

| --- | --- |

| <query> | Search term to match against module names and descriptions |

| --verbose | Show full module details including all versions |

| --refresh | Force refresh the repository index cache |

Syncing Modules

Automatically install all modules defined in a distributor's repository.inc.php:

php Razy.phar sync <distributor> [--dry-run] [--yes] [-v]

The sync command reads the distributor's repository.inc.php and installs all defined modules. The distributor-level repository config uses an extended format:

return [

    'repositories' => [

        'https://github.com/owner/repo/' => 'main',

    ],

    'modules' => [

        'vendor/module-a' => ['version' => '1.0.0', 'is_shared' => false],

        'vendor/module-b' => 'latest',

    ],

];

| Key | Description |

| --- | --- |

| repositories | GitHub repositories to fetch from (URL — branch) |

| modules | Modules to install — either a version string or an array with version and is_shared |

The --dry-run flag previews which modules would be installed without making changes. Use --yes to skip confirmation prompts.

Complete Publishing & Installation Example

Here→s a full workflow from packing a module to installing it on another project:

# === On the publisher→s machine ===



# 1. Pack the module

php Razy.phar pack vendor/blog 1.2.0

# →packages/vendor/blog/1.2.0.phar



# 2. Configure publish credentials (packages/publish.inc.php)

# See publish.inc.php section above



# 3. Scan, generate index, and push to GitHub

php Razy.phar publish --scan --push --branch=main



# 4. Preview without pushing (dry run)

php Razy.phar publish --scan --dry-run -v

# === On the consumer→s machine ===



# 1. Install a specific module version

php Razy.phar install vendor/blog --version=1.2.0 --from-repo



# 2. Install latest version from a private repo

php Razy.phar install vendor/blog --latest --token=ghp_xxx



# 3. Sync all modules defined in distributor config

php Razy.phar sync mysite --yes



# 4. Search for available modules

php Razy.phar search blog --verbose --refresh

// Consumer→s repository.inc.php (project root)

return [

    'https://github.com/myorg/razy-modules/' => 'main',

];



// Consumer→s distributor-level repository.inc.php (sites/mysite/repository.inc.php)

return [

    'repositories' => [

        'https://github.com/myorg/razy-modules/' => 'main',

    ],

    'modules' => [

        'vendor/blog'     => ['version' => '>=1.0.0', 'is_shared' => false],

        'vendor/auth'     => 'latest',

        'vendor/database' => ['version' => '2.0.0', 'is_shared' => true],

    ],

];

← PreviousPackaging & Distribution

Next → Caddy Worker Mode