README

Repo Gen is a small PHP library for bootstrapping new Git repositories for PHP libraries. It focuses on automating the initial repository setup using templates, GitLab integration and optional Packagist registration.

The core entry point is RepoGenFacadeInterface, which supports repository initialization, remote repository creation and member management, and Packagist package creation.

Features

Initialize a new Git repository from filesystem templates
Create a remote repository via GitLab API (through git-platform integration)
Initialize a local Git repository, commit generated files and push to the remote
Register the repository as a package on Packagist
Add users to remote repositories with configurable roles
Simple factory for wiring all dependencies (RepoGenFacadeFactory)
CLI helper script bin_dev/initialize_repository for quick manual usage

Installation

Install via Composer:

composer require adachsoft/repo-gen

Note: The package name above assumes the library is published as adachsoft/repo-gen. Adjust it if your fork uses a different vendor or package name.

Requirements

PHP 8.1 or higher (as configured in composer.json)
Git installed and available on the command line
Access to a GitLab instance (or git-platform compatible API) with a personal access token
Optional: Packagist account and API token for automatic package registration

Basic usage (Facade)

The main entry point is AdachSoft\\RepoGen\\RepoGenFacadeInterface. You can obtain an instance using the RepoGenFacadeFactory and a configuration DTO:

use AdachSoft\RepoGen\Config\RepoGenConfigDto;
use AdachSoft\RepoGen\Dto\CreatePackagistPackageDto;
use AdachSoft\RepoGen\Dto\InitRepositoryDto;
use AdachSoft\RepoGen\Factory\RepoGenFacadeFactory;

$config = new RepoGenConfigDto(
    basePath: '/var/www',
    gitLabBaseUrl: 'https://gitlab.com',
    gitLabAccessToken: getenv('GIT_LAB_KEY') ?: '',
    gitLabNamespace: 'your-namespace',
    packagistUsername: getenv('PACKAGIST_USERNAME') ?: '',
    packagistApiToken: getenv('PACKAGIST_API_TOKEN') ?: '',
    templateDirectory: __DIR__ . '/var/templates/php-library-default',
    defaultVisibility: 'public',
);

$facade = RepoGenFacadeFactory::createWithDependencies($config)->create();

// Initialize repository (local + remote)
$repositoryDto = $facade->initializeRepository(
    new InitRepositoryDto(
        name: 'my-library',
        description: 'My first library generated with Repo Gen',
        visibility: 'public',
    ),
);

// Optionally register on Packagist
$facade->createPackagistPackage(
    new CreatePackagistPackageDto(
        repositoryUrl: $repositoryDto->url ?? 'https://gitlab.com/your-namespace/my-library.git',
    ),
);

Creating only a remote repository

To create a remote repository without creating a local directory or running git init, commit, or push, use createRemoteRepository():

use AdachSoft\RepoGen\Dto\CreateRemoteRepositoryDto;
use AdachSoft\RepoGen\Factory\RepoGenFacadeFactory;

$facade = RepoGenFacadeFactory::createWithDependencies($config)->create();
$remoteRepository = $facade->createRemoteRepository(
    new CreateRemoteRepositoryDto(
        name: 'my-lib',
        visibility: 'public',
    ),
);

echo $remoteRepository->sshRemoteUrl;

This method creates only the remote repository. It does not create a local directory or a commit. The defaultBranch is null until the first push creates a branch on the hosting service.

Adding a member to a remote repository

Use addRemoteRepositoryMember() to add a Git hosting account to a remote repository:

use AdachSoft\RepoGen\Dto\AddRemoteRepositoryMemberDto;

$facade->addRemoteRepositoryMember(
    new AddRemoteRepositoryMemberDto(
        repositoryId: 'my-library',
        username: 'contributor',
        role: 'developer',
    ),
);

Supported roles are guest, reporter, developer, maintainer (the default), and owner. When repositoryId is a repository name without a path or numeric ID, Repo Gen prefixes the configured gitLabNamespace. Full repository paths and numeric IDs are used as provided. Invalid arguments, unsupported roles, and failures from the Git hosting provider throw RemoteRepositoryMemberException.

CLI helper

For quick manual usage there is a CLI helper script:

php bin_dev/initialize_repository \
    --base_path=/var/www \
    --name=my-library \
    --description="My awesome library" \
    --visibility=public

The script reads configuration from environment variables (optionally via .env):

GIT_LAB_KEY – GitLab personal access token
PACKAGIST_USERNAME – Packagist username (also used as GitLab namespace if non-empty)
PACKAGIST_API_TOKEN – Packagist API token

It then creates a RepoGenConfigDto, builds all dependencies through RepoGenFacadeFactory::createWithDependencies() and calls RepoGenFacadeInterface::initializeRepository().

Versioning

This project follows Semantic Versioning. The first tagged release is 0.1.0, which introduces the initial public API around RepoGenFacade and its supporting services.

adachsoft / repo-gen

Package info

Security

Statistics