1	<?php
2	/**
3	* Versioning plugin interface.
4	*
5	* @package automattic/jetpack-changelogger
6	*/
7
8	namespace Automattic\Jetpack\Changelogger;
9
10	use Automattic\Jetpack\Changelog\ChangeEntry;
11	use InvalidArgumentException;
12	use Symfony\Component\Console\Input\InputInterface;
13	use Symfony\Component\Console\Input\InputOption;
14	use Symfony\Component\Console\Output\OutputInterface;
15
16	/**
17	* Versioning plugin interface.
18	*
19	* PluginTrait may be used to handle the boilerplate for `instantiate()`, `getOptions()` and `setIO()`.
20	*/
21	interface VersioningPlugin {
22
23	/**
24	* The plugin is created via this factory method.
25	*
26	* @param array $config Configuration information from composer.json.
27	*/
28	public static function instantiate( array $config );
29
30	/**
31	* Define any command line options the versioning plugin wants to accept.
32	*
33	* @return InputOption[]
34	*/
35	public function getOptions();
36
37	/**
38	* Set Symfony Console input and output interfaces.
39	*
40	* @param InputInterface  $input InputInterface.
41	* @param OutputInterface $output OutputInterface.
42	*/
43	public function setIO( InputInterface $input, OutputInterface $output );
44
45	/**
46	* Parse a version number.
47	*
48	* @param string $version Version.
49	* @return array Associative array with at minimum the following keys. Additional keys may be returned depending on the subclass.
50	*  - version: (string) Version number, without any prerelease or buildinfo.
51	*  - prerelease: (string|null) Prerelease version, e.g. "dev", "alpha", or "beta", if any.
52	*  - buildinfo: (string|null) Build info, if any.
53	* @throws InvalidArgumentException If the version number is not in a recognized format or extra is invalid.
54	*/
55	public function parseVersion( $version );
56
57	/**
58	* Check and normalize a version number.
59	*
60	* @param string $version Version.
61	* @param array  $extra Extra components for the version, replacing any in `$version`.
62	* @return string Normalized version.
63	* @throws InvalidArgumentException If the version number is not in a recognized format.
64	*/
65	public function normalizeVersion( $version, $extra = array() );
66
67	/**
68	* Determine the next version given a current version and a set of changes.
69	*
70	* @param string        $version Current version.
71	* @param ChangeEntry[] $changes Changes.
72	* @param array         $extra Extra components for the version.
73	*  - prerelease: (string|null) Prerelease version, e.g. "dev", "alpha", or "beta", if any. See subclass docs for exact values accepted.
74	*  - buildinfo: (string|null) Build info, if any. See subclass docs for exact values accepted.
75	* @return string
76	* @throws InvalidArgumentException If the version number is not in a recognized format, or other arguments are invalid.
77	*/
78	public function nextVersion( $version, array $changes, array $extra = array() );
79
80	/**
81	* Compare two version numbers.
82	*
83	* @param string $a First version.
84	* @param string $b Second version.
85	* @return int Less than, equal to, or greater than 0 depending on whether `$a` is less than, equal to, or greater than `$b`.
86	* @throws InvalidArgumentException If the version numbers are not in a recognized format.
87	*/
88	public function compareVersions( $a, $b );
89
90	/**
91	* Return a valid "first" version number.
92	*
93	* @param array $extra Extra components for the version, as for `nextVersion()`.
94	* @return string
95	*/
96	public function firstVersion( array $extra = array() );
97	}