Discussion about the implementation

This document is meant to explore an alternative interface for specs in PHPSpec2.

Goals of the new interface

• Keep the focus of the developer on specifying the behaviour of his class
• Eliminate as much as possible unnecessary syntax
• Take into accounts the limitations and possibilities of PHP
• Keep the spec framework maintainable
• Allow for specs to be as readable as possible

The current scenario

Example with the existing code: https://gist.github.com/1540309

Problems with the existing implementation

• Too much noise from PHP syntax (class, extends, \PHPSpec\Context, function, ->, etc...)
• Not possible to have nested contexts/examples
• Need to use spec() interceptor to add expectations
• Examples names in camel case (not too readable)

Identified approaches to address these problems and fulfil the goals

• Keeping OO for specs and framework, but addressing problems
• Adding global functions, functional specs, keep PHP syntax noise
• Keeping OO for framework, functional specs, keep PHP syntax noise
• Keeping OO for framework, functional specs, eliminating PHP syntax noise

Keeping OO for specs and framework, addressing problems

Possible solution (Annotation)

• Using annotations for defining contexts, more than one @context annotation meaning nested contexts
• Using @let annotation to intercept a subject, instead of $this->spec
• Using @specdox annotation for defining the english version of example

Problems with this solution

• Only moving the noise from one place to another
• Although editors like text mate allow the method name be created automatically from specdox as you type, we would still have to see the camel case version, polluting the spec

Advantages of this solution

• Not much different than existing code. Easy to implement
• Still most would be familiar PHP code and syntax. Annotations are common now in PHP user land

Adding global functions, functional specs, keep PHP syntax noise

Possible solution

https://github.com/speciphy/speciphy https://github.com/noonat/pecs

Problems with this solution

• PHP namespace implementation won't let you use a namespace function in a different namespace. Developers won't be able to namespace their specs with their own chosen namespaces.
• Still a lot of noise from PHP syntax
• Difficult to maintain and extend, not Object Oriented

Advantages of this solution

• Easier to read example descriptions
• Possible to nest contexts

Keeping OO for framework, functional specs, keep PHP syntax noise

Possible solution

https://gist.github.com/12d67c3ca11b7bd546d7

Problems with this solution

• Still a lot of noise from PHP syntax

Advantages of this solution

• Easier to read example descriptions
• Possible to nest contexts
• Easier to maintain and extend

Keeping OO for framework, functional specs, eliminating PHP syntax noise

Possible solution 1 - Everzet

https://gist.github.com/4aaffb4a70b6e3c61ce3

Possible solution 2 - Marcello

https://gist.github.com/457c3ae2357d3a74d7fa

Problems with this solution

• Need a translator component
• IDEs will not recognise the syntax without plugins
• Developers need to learn the specific syntax

Advantages of this solution

• Completely eliminate language noise
• Easier to read example descriptions
• Possible to nest contexts
• Easier to maintain and extend