Forge Engine

Overview

Package manager for Forge modules with registry support and dependency management.

Key Benefits

Integrity verification with SHA-256 hashes

Multiple registry support

Version management and constraints

Lock file for reproducible installations

Cached downloads for performance

Seamless Forge integration

Features

Multi-Registry Support

Connect to multiple registries including official Forge registry and custom private registries.

• Official Forge registry
• Private GitHub repositories
• Custom registry endpoints

Integrity Verification

Every module download is verified using SHA-256 integrity hashes to ensure security.

• SHA-256 hash verification
• Tamper detection
• Secure downloads

Version Management

Sophisticated version resolution with support for semantic versioning and constraints.

• Semantic versioning
• Version constraints
• Latest version detection

Lock File Support

Generate and use lock files for reproducible module installations across environments.

• Reproducible installations
• Environment consistency
• Team collaboration

Installation

Pre-installed with Forge Engine. Manual installation options available.

# Install ForgePackageManager module
php forge.php install:module ForgePackageManager

# Install specific version
php forge.php install:module ForgePackageManager@1.0.0

# Verify installation
php forge.php list:modules | grep ForgePackageManager

Pre-installed: ForgePackageManager is included by default in new Forge installations.

Configuration

Configure through config/forge_package_manager.php file.

Basic Configuration

 [
        // Official Forge registry (included by default)
        [
            'name' => 'forge-engine-modules',
            'url' => 'https://github.com/forge-engine/modules',
            'branch' => 'main',
            'private' => false,
        ],
        // Custom private registry example
        [
            'name' => 'my-company-modules',
            'url' => 'https://github.com/mycompany/private-modules',
            'branch' => 'main',
            'private' => true,
            'personal_token' => env('GITHUB_TOKEN', 'your-secret-token'),
        ],
    ],
    'cache_ttl' => 3600, // Cache time-to-live in seconds
];

Environment Variables

Use environment variables for sensitive configuration:

# .env file
GITHUB_TOKEN=ghp_your_github_personal_access_token
PRIVATE_REGISTRY_TOKEN=your_private_registry_token
CACHE_TTL=7200

Usage

Installing Modules

# Install latest version of a module
php forge.php install:module ForgeAuth

# Install specific version
php forge.php install:module ForgeAuth@1.2.0

# Force refresh cache during installation
php forge.php install:module ForgeAuth force

# Install from specific registry
php forge.php install:module --registry=my-company-modules CustomModule

Removing Modules

# Remove a module
php forge.php remove:module ForgeAuth

# Remove with confirmation
php forge.php remove:module ForgeAuth --confirm

Listing Modules

# List all available modules
php forge.php list:modules

# List installed modules
php forge.php list:modules --installed

# List modules from specific registry
php forge.php list:modules --registry=forge-engine-modules

Custom Registries

ForgePackageManager supports custom registries for private modules and enterprise deployments.

Adding a Custom Registry

// config/forge_package_manager.php
return [
    'registry' => [
        // Private GitHub repository
        [
            'name' => 'acidlake-modules',
            'url' => 'https://github.com/acidlake/acidlake-modules',
            'branch' => 'main',
            'private' => true,
            'personal_token' => env('GITHUB_TOKEN', 'your-secret-token'),
        ],
        
        // Private GitLab repository
        [
            'name' => 'company-gitlab-modules',
            'url' => 'https://gitlab.company.com/forge-modules',
            'branch' => 'main',
            'private' => true,
            'personal_token' => env('GITLAB_TOKEN'),
        ],
        
        // Public custom registry
        [
            'name' => 'community-modules',
            'url' => 'https://github.com/forge-community/modules',
            'branch' => 'main',
            'private' => false,
        ],
    ],
    'cache_ttl' => 3600
];

Registry Structure

Your custom registry should follow the Forge module registry structure:

your-registry-repo/
├── modules/
│   ├── YourModule1/
│   │   ├── forge.json
│   │   └── src/
│   ├── YourModule2/
│   │   ├── forge.json
│   │   └── src/
│   └── modules.json
└── README.md

Advanced Registry Examples

Here are more examples of different registry configurations you can add:

// config/forge_package_manager.php
return [
    'registry' => [
        // Enterprise GitHub with organization
        [
            'name' => 'company-enterprise-modules',
            'url' => 'https://github.company.com/org/forge-modules',
            'branch' => 'main',
            'private' => true,
            'personal_token' => env('GITHUB_ENTERPRISE_TOKEN'),
        ],
        
        // GitLab with specific group
        [
            'name' => 'gitlab-group-modules',
            'url' => 'https://gitlab.com/my-group/forge-modules',
            'branch' => 'develop',
            'private' => true,
            'personal_token' => env('GITLAB_ACCESS_TOKEN'),
        ],
        
        // Bitbucket private repository
        [
            'name' => 'bitbucket-modules',
            'url' => 'https://bitbucket.org/team/forge-modules',
            'branch' => 'master',
            'private' => true,
            'personal_token' => env('BITBUCKET_APP_PASSWORD'),
        ],
        
        // Azure DevOps repository
        [
            'name' => 'azure-devops-modules',
            'url' => 'https://dev.azure.com/organization/project/_git/forge-modules',
            'branch' => 'main',
            'private' => true,
            'personal_token' => env('AZURE_DEVOPS_TOKEN'),
        ],
        
        // Self-hosted Git server
        [
            'name' => 'self-hosted-modules',
            'url' => 'https://git.company.com/forge/modules',
            'branch' => 'stable',
            'private' => true,
            'personal_token' => env('SELF_HOSTED_TOKEN'),
        ],
        
        // Public community registry (no token needed)
        [
            'name' => 'community-contrib',
            'url' => 'https://github.com/forge-community/contrib-modules',
            'branch' => 'main',
            'private' => false,
        ],
    ],
    'cache_ttl' => 3600
];

Pro Tip: Use environment variables for tokens to keep sensitive information out of your codebase. Add them to your .env file.

Private Registries: Ensure your personal access tokens have appropriate permissions for repository access.

CLI Commands

`install:module`

Install a module from the configured registries.

php forge.php install:module [module-name] [version] [force]

Examples:

• php forge.php install:module ForgeAuth
• php forge.php install:module ForgeAuth@1.2.0
• php forge.php install:module ForgeAuth force

`remove:module`

Remove an installed module from your application.

php forge.php remove:module [module-name] [--confirm]

`list:modules`

List available or installed modules.

php forge.php list:modules [--installed] [--registry=name]

Lock File (forge-lock.json)

The lock file ensures reproducible installations by locking module versions and integrity hashes.

Lock File Structure

{
  "modules": {
    "ForgeAuth": {
      "version": "1.2.0",
      "url": "https://github.com/forge-engine/modules/archive/main/modules/ForgeAuth.zip",
      "integrity": "sha256-abc123def456...",
      "registry": "forge-engine-modules"
    },
    "ForgeUI": {
      "version": "2.1.0",
      "url": "https://github.com/forge-engine/modules/archive/main/modules/ForgeUI.zip",
      "integrity": "sha256-def456ghi789...",
      "registry": "forge-engine-modules"
    },
    "CustomModule": {
      "version": "1.0.0",
      "url": "https://github.com/mycompany/modules/archive/main/modules/CustomModule.zip",
      "integrity": "sha256-ghi789jkl012...",
      "registry": "my-company-modules"
    }
  },
  "registries": {
    "forge-engine-modules": {
      "url": "https://github.com/forge-engine/modules",
      "branch": "main"
    },
    "my-company-modules": {
      "url": "https://github.com/mycompany/modules",
      "branch": "main"
    }
  }
}

Generating Lock File

# Generate lock file from current installations
php forge.php modules:lock

# Install from existing lock file
php forge.php install:from-lock

Best Practice: Commit your forge-lock.json file to version control for consistent deployments across environments.

Best Practices

Do

• Use semantic versioning for your modules
• Commit forge-lock.json to version control
• Use environment variables for tokens
• Test module installations in CI/CD
• Keep registries organized and documented
• Use descriptive module names

Don't

• Hardcode tokens in configuration files
• Ignore integrity verification warnings
• Mix production and development modules
• Skip testing module updates
• Use unstable versions in production
• Forget to document dependencies

Security Considerations

• Always verify module integrity hashes
• Use private registries for sensitive modules
• Rotate personal access tokens regularly
• Audit module permissions and access
• Monitor registry access logs