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