gwaz/php-hg

Mercurial Command Server API

v0.9.1 2017-06-29 16:21 UTC

Requires

• php: >=5.6
• symfony/console: ^3.3
• symfony/process: ^3.3
• symfony/yaml: ^3.3

Requires (Dev)

• mockery/mockery: ^0.9.9
• phpunit/phpunit: ^5.7
• sebastian/phpcpd: ^3.0
• symfony/dom-crawler: ^3.3

bsd-3-clause

• Matt Zuba

• mercurial
• version control
• vcs

README

php-hg is a VCS library used for communicating with the Mercurial Command Server rather than placing exec calls all over your code to call upon the hg binary. For some tips on utilizing the command server, view Mozilla's Tips.

This library supports all commands found in the hg(1) manpage including extensions listed as well.

Installation

The optimal way to install this library is via composer:

composer require gwaz/php-hg

Usage

The recommended way to start using the library is to use the RepositoryFactory class.

$factory  = new \PhpHg\RepositoryFactory;
$repo = $factory->make('/path/to/repo');

var_dump($repo->summary()->execute());

The first method call on a repo object should be the command you with to run. It will return a PhpHg\Command object to which you can add parameters and arguments.

Customize the Factory

The Repository Factory accepts one or two optional constructor arguments. The first is the command loader. The default loader loads commands from the yaml files using Symfony's Yaml parser. You can optionally create your own command loader that implements the PhpHg\Contracts\CommandLoader interface.

$loader = new MyCustomLoader;
$factory  = new RepositoryFactory($loader);

The PhpHg\Client class uses Symfony's process builder to launch the Mercurial command server. If you'd like to use a custom ProcessBuilder instance, you can create one and pass it in as well.

$builder = (new ProcessBuilder)
    ->setPrefix('/custom/hg/path')
    ->addEnvironmentVariables(['SOME_ENV' => 'SOME_VALUE']);
$factory = new RepositoryFactory(null, $builder);

If you'd like to add custom commands or options to be added to the repo (for example, if you have a custom extension enabled), you can put them into a Yaml file with the same format as the commands.yaml file in the src directory and add them to the factory.

$factory = new RepositoryFactory;
$factory->addCommandDescriptor('/path/to/custom-commands.yaml');

Customize the Repository Commands

You can also add custom commands on a per-repository basis.

$repo->addCommands([
  'globalOptions' => [
    'foo' => \PhpHg\Command::OPTION_BOOLEAN
  ],
  'commands' => [
    'bar' => [
      'options' => [/** Some options here **/]
      'arguments' => [/** Some arguments here, if any **/]
    ]
  ]
]);

Specify location of hg binary

If your hg executable is not on your PATH, you can create a custom builder as shown above, OR you can specify a HG_BIN environment variable that points to the executable and this will be used instead.

Running Commands

The first method call on any repository object will return a command class for that command that you can then add arguments and options to before executing the command. Options and arguments added via method calls on the command object. The name of the method call matches the name of the argument or option. Here's an example for pulling changes down and updating a local repository. Note that each command must be called with execute() once the command has been setup as desired to actually run it against the command server.

$repo->pull()->branch('default')->update()->execute();

Options

Options that would contain a dash in them on the command line should be called in camel-case form: --foo-bar would be called like ->fooBar(). Flag type options should be called with NO arguments to set them, or FALSE to unset them. Options that can only be specified once take a single string as an argument to set them, or NULL to unset them. Options that can be specified multiple times (like --config) can have n number of arguments.

$repo->pull()->update(); // --update is a flag argument
$repo->pull()->ssh('/usr/bin/ssh'); // --ssh can only be specified once
$repo->pull()->branch('default', 'new-feature'); // --branch can be specified multiple times

Calling an option method again will overwrite the first method call.

$repo->pull()->branch('default', 'new-feature')->branch('stable'); // only the 'stable' branch would be pulled

Arguments

Arguments should be called just like options via methods. If an argument can be repeated, it can be specified just like repeating options.

$repo->clone()->source('http://myrepo.com/repo')->dest('/tmp/repo')->execute()

If an argument is required and it is not specified, an exception will be thrown.

Shortcut Options

Many commands support or offer the --template option and one of the experimental formats that this option can output is JSON or XML. You can call the json() or xml() method on any command that supports templates to get the data returned in that format.

$repo->status()->json()->execute();

Extending

You can easily add custom global options or custom commands via YAML files that follow the same convention as the base src/commands.yaml file. Because Symfony's YAML parser is used, we can leverage it's ability to include constants in the YAML as well.

The basic format of the YAML file should follow this format:

globalOptions:
  option-name: !php/const:PhpHg\Command::OPTION_STRING
commands:
  add:
    options:
      include: !php/const:PhpHg\Command::OPTION_ARRAY
    arguments:
      file: !php/const:PhpHg\Command::ARGUMENT_OPTIONAL_ARRAY

The constants you can use for options are

• PhpHg\Command::OPTION_BOOLEAN - used for flag type options
• PhpHg\Command::OPTION_STRING - used for options that can only be used once
• PhpHg\Command::OPTION_ARRAY - used for options that can be specified multiple times

The constants you can use for arguments are

• PhpHg\Command::ARGUMENT_OPTIONAL - used for arguments that are optional
• PhpHg\Command::ARGUMENT_OPTIONAL_ARRAY - used for arguments that are optional but can be specified multiple times
• PhpHg\Command::ARGUMENT_REQUIRED - used for arguments that are required
• PhpHg\Command::ARGUMENT_REQUIRED_ARRAY - used for arguments that are required and can be specified multiple times

Contributing

If you encounter a bug or determine the need for a feature, we'd love to hear about it and accept a fix. Please open a pull request for us to review. If you have not signed our CLA, you will be asked to do so before we can accept your pull request. All contributors must provide a signed CLA, even for minor bug fixes.

If providing a pull request, please be sure your change includes unit tests and that the entire test suite passes. You can run the test suite using composer via composer run-script test on the command line.