Configuration

The PHPSemVer Tool checks if your recent changes will break the application or are a new feature compared to previous versions. You do not need to follow the famous semver.org but can write your own rules.

Naked config

A very basic XML looks like this:

  <?xml version="1.0"?>
  <phpsemver
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/sourcerer-mike/phpsemver/support/3.x.x/etc/phpsemver.xsd"
          title="My semantics">
          
  </phpsemver>

This is empty except a schema which will give you auto-complete and other hints in your IDE. In that way it is pretty easy to write new configurations.

Simple rule sets

Let phpsemver work for you an fill it with your mindset. Imagine which rules are the one that you like to follow. Let's look at WordPress if you like or not, because this configuration is different to the regular one and the first thing that comes to my mind.

The usual Version Number in WordPress is

4.3.2

which means that there are three segments / rule sets to follow:

• The first number is just an overflow of the second - it has no meaning.
• The second is increased with new features that may include bug fixes.
• The last one shall only be for bugfixes.

As the first one doesn't matter it only comes down to two new rule sets for our configuration:

<?xml version="1.0"?>
<phpsemver
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/sourcerer-mike/phpsemver/support/3.x.x/etc/phpsemver.xsd"
        title="WordPress version semantics">

    <RuleSet name="feature">
        <Description>Increase second number with each new feature and reset the third.</Description>
    </RuleSet>
    
    <RuleSet name="fix">
        <Description>Increase third number with each new fix.</Description>
    </RuleSet>

</phpsemver>

You can document them using XML-Comments or the "Description"-Section which will be used in later versions.

Insert your mindset by using Trigger

Now that the borders are set-up you can tell each of the rule sets how they work. There are a lot of Trigger you can use so feel free to play around with the auto-complete if your IDE or take a look at the Trigger-Classes. A fast way to get this done is by looking at each trigger and write down where they shall be used:

<?xml version="1.0"?>
<phpsemver
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/sourcerer-mike/phpsemver/support/3.x.x/etc/phpsemver.xsd"
        title="WordPress version semantics">

    <RuleSet name="feature">
        <Description>Increase second number with each new feature and reset the third.</Description>
        <Trigger>
            <Classes>
                <IsAdded />
                <Methods>
                    <IsAdded />
                    <BodyChanged />
                </Methods>
            </Classes>
            <Functions>
                <IsAdded />
            </Functions>
        </Trigger>
    </RuleSet>
    
    <RuleSet name="fix">
        <Description>Increase third number with each new fix.</Description>
        <Trigger>
            <Classes>
                <Methods>
                    <BodyChanged />
                </Methods>
            </Classes>
            <Functions>
                <BodyChanged />
            </Functions>
        </Trigger>
    </RuleSet>

</phpsemver>

You see that this can grow really fast due to the details. Also it is no problem to have duplicate triggers (like "BodyChanged") which will just cause PHPSemVer to print two messages in case of changed bodies.

Self-describing trigger

A closer look at this part will help explain what it wants to tell you:

<Methods>
    <IsAdded />
    <BodyChanged />
</Methods>

Any methods (not functions) within a class are checked here even the private, protected or abstract ones. If you add a new method or change the body of some, then PHPSemVer will give you this output:

./bin/phpsemver compare HEAD .

+---------+---------------------------------------------+
| Level   | Message                                     |
+---------+---------------------------------------------+
| feature | Some_Class::a_method() added.               |
| feature | Another_Class::another_func() body changed. |
| fix     | Another_Class::another_func() body changed. |
+---------+---------------------------------------------+

Total time: 0.42

The information about the changed body occurs twice because the upper config wants it for the "feature" and "fix" rule sets.

Semantic Versions 2.0 (aka semver2)

The famous semver2 is already integrated and will be used by default. You can look up the configurations:

https://github.com/sourcerer-mike/phpsemver/tree/support/3.x.x/lib/PHPSemVer/Rules

How to use the own configuration

The option --ruleSet or -R must be used to switch to another configuration. It might be replaced by --config or -c some day.

./bin/phpsemver compare --ruleSet myown.xml HEAD .

+---------+---------------------------------------------+
| Level   | Message                                     |
+---------+---------------------------------------------+
| feature | Some_Class::a_method() added.               |
| feature | Another_Class::another_func() body changed. |
| ...     | ...                                         |
| ...     | ...                                         |
| ...     | ...                                         |
| fix     | Another_Class::another_func() body changed. |
+---------+---------------------------------------------+

Total time: 0.69

This output shows suggestions based on your rules. Again, this is just a hint that reminds you of those changes and it is up to you changing the version in an adequate way.

Have fun keeping your versions clean! :)