Skip to content


Ciaran McNulty edited this page Jan 4, 2016 · 17 revisions
Clone this wiki locally

PhpSpec Dev Wiki

If you are looking for the user documentation for PhpSpec, this is online at

Contributing to PhpSpec

To make a change to PhpSpec, open a PR directly to the master branch. Contributions to PhpSpec are expected to:

  • Improve the tool in a way that encourages a BDD workflow
  • Have considered Backward Compatibility with extensions and provided compatibility layers to avoid breaks as much as possible
  • Have been driven by examples, so will be accompanied by relevant test coverage

If there is a release in the near future, pull requests may be assigned the milestone of a future release. In these cases they will be merged soon after that release.

Coding standards

  • We officially support PSR-2
  • New classes should, in most cases, be declared final (this has not been upheld in the past but is the policy going forwards)
  • Interfaces currently should be named *Interface for consistency but this may change in a future major release. To facilitate this, concrete classes should not be named the same as the interface they implement; try and find a more specific name for the concrete implementation.

Release process

A major release of PhpSpec will occur in the middle of each year (ostensibly June, but may vary). At this point the following will occur:

  • Backward Compatibility is not maintained - this means extensions will need to be updated and some user specs may need to be rewritten.
  • Minimum PHP version will be updated to reflect the current Actively Supported versions.
  • Minimum HHVM version will be updated to reflect the currently supported LTS releases
  • Minimum Symfony component versions will be updated to the latest versions that are in active Bug Fix mode.
  • Other dependencies may be bumped, depending on individual projects' policies.
  • The previous version will be branched in the repository and go into bugfix mode.
  • The version prior to the previous version will be at End of Life and no longer supported (git tags will be preserved indefinitely)

Bug fix policy

After a new major version is released, serious bugs in older versions will be addressed where possible. If a workaround is possible then documenting this workaround will be considered a fix

End of Life policy

After End of Life, the major version of PhpSpec will no longer be supported at all.

This does not mean existing test suites will stop running.


Version PHP HHVM Symfony Released Bug fix EOL
2.x 5.3.3+ 3.6 2.1+ mid 2014 mid 2016 mid 2017
3.x 5.6, 7.0 3.9, 3.12 2.7+, 3.0+ mid 2016 mid 2017 mid 2018
4.x 7.0+ ? 2.7+, 3.2+ mid 2017 mid 2018 mid 2019

Versioning policy

As of version 3.0, PhpSpec will use pure Semantic Versioning.

During the 2.x series there are areas of the internal codebase that may be refactored in non-Backwardly Compatible ways (see below).

Consequences for contributors

To introduce a change that will eventually lead to a Bc break you must:

  • Define new types rather than changing the contract of existing ones
  • Mark the old types as @deprecated
  • Provide a compatibility layer to support the usage of the older APIs

Only if this is considered impossible is a BC break allowed in 2.x.

When are internal API breaks allowed?

The following conditions have to be met for a Minor version to have internal API breaks

  1. The change must introduce a clear design improvement and clear benefits for maintainability in future
  2. A compatibility layer must have been considered but have introduced too much complexity to reasonably be implemented.
  3. Known extensions (specifically those linked in the PhpSpec documentation) must have been surveyed for usage.

Consequences for users using 2.x

When including PhpSpec in your projects you should be able to upgrade between minor versions with no incompatibility issues between your specs and newer versions of PhpSpec.

This translates to a composer versioning something like ~2.1.

You may find when a new version of PhpSpec is released that you cannot use it yet because one of your extensions has not been tested against it. In these instances you can help by notifying the extension maintainers, or even testing it yourself with the new version.

Consequences for extension authors using 2.x

Because changes inside minor patches are not planned to happen regularly, there is a very high chance extensions will continue working between minor releases.

However, because these breaks may happen you should only tag up to the next minor version.

This translates to a composer versioning something like '~2.1,<2.2'.

Once a new version of PhpSpec is released you can test your extension and update the dependencies.

Something went wrong with that request. Please try again.