Exactly three weeks today, editorially.com will shut its doors for good.

The announcement was made back in March, and was greeted with both surprise and disappointment by the community. The reason given was that Editorially had over-extended itself, hiring too many staff and failing to reach the number of users necessary to run as a viable business.

It’s a stark lesson for those that dream of making it big in the dot com world: building the perfect product does not guarantee billionaire status, or even a profit.

In the weeks that followed the announcement Editorially’s loyal fanbase waited expectantly to see which Internet giant would arrive with a seven figure check and snap up the obviously brilliant application. As time passed, the prospect of a rescue looked less and less likely, and writers, editors and marketers are now waking up to the probability that in 21 days, a key part of our workflow will be gone forever.

We’ve been using Editorially to handle all content on WebdesignerDepot for more than six months, and in that time it’s become a go-to tool helping us improve editing, work more efficiently with authors, and deliver better content; there are several areas in which Editorially excels that we’re looking for in a replacement:

1. firstly, Editorially allowed you to write quickly by fully embracing markdown;
2. secondly, it provided a simple versioning system;
3. thirdly, it provided a simple to use highlight-comment-collaborate system;
4. finally, its export to HTML and export to WordPress features were reliable.

As a personal preference, its UI was also pleasantly minimal, compared to desktop solutions like Word or Pages that feature dozens of formatting options, the focus on content made for better writing.

The good news is that there are alternatives to Editorially; the bad news is that none of them fill the niche quite as elegantly.

Draft (free)

Draft is an browser-based app that takes a similar UI approach to Editorially by presenting text with little extraneous functionality. Where Draft varies is its approach to version control; Draft displays edited versions alongside the original and then prompts the document owner to accept or reject the suggestions by collaborators.

Draft supports markdown and its export options are at least as good as Editorially’s if not better.

Where Draft loses points is its UX; it carries out its tasks with none of the sleekness of Editorially. For example, markdown syntax isn’t styled as it’s typed. Speaking as someone who edits a lot of technical text that requires extensive formatting, this is a definite pain point.

Penflip (free–$22/month)

Penflip is another browser-based app. It aims to be the GitHub for writers and its UI is not too far removed from Editorially’s, although not as minimal it does a great job of allowing the writer to focus on writing.

Penflip also highlights markdown syntax so that content is prioritized. It’s a small detail, but it’s small details like this that make a difference when you’re working with an application for extended periods of time.

The obvious downside to Penflip is the pricing structure; free for public projects, if you want to keep your writing private until it’s ready for consumption (which all writers do) then you need to pay $8/month for 50 projects or $22/month for 150 projects. It’s not actually the cost that is a concern but the maximum number of projects. 150 projects is simply far too few; if they introduce an unlimited project option then my interest will definitely be piqued.

Trialling Penflip it feels more collaborative than some alternatives. It’s very good, but the GitHub style branch merging feels like it’s geared towards teams of writers rather than writers and their editors.

Typewrite (free)

Typewrite is the new kid on the block, just a few months old, but already looking very promising.

The UI is minimal, and the markdown formatting is also there. The developer is passionate about creating a tool for collaborative writing and it’s always encouraging to see someone innovate towards a goal rather than towards a fast buck.

The catch with Typewrite is that it’s unfinished: the DropBox syncing that’s advertized as a feature is still being tested, and even the export to HTML option isn’t complete yet. It’s all coming, but will it be ready in under three weeks? I doubt it. To make matters worse, Typewrite is designed and built not by a fully funded team, but by a single individual. Hats off to him, it’s a great product so far, but it will inevitably take some time for him to build, test and deploy everything he plans.

It disappoints me to say it, because Typewrite has the best writing experience, but it’s not ready. If you’re looking for a solution in 2015, check out Typewrite, it’s probably awesome.

Google Drive (free)

Google Drive is the grandaddy of all collaborative writing in the cloud. There is real-time collaboration, plenty of storage and it’s part of Google’s ecosystem—if they go under we’re all in trouble.

The big flaw with Google Drive is its lack of markdown. Google Drive is effectively a word processor; it’s Word but online. The collaboration is in place, but the myriad of options means that you’re likely to spend all your time selecting a nice typeface for your footnotes instead of focusing on content.

I’ve used Google Drive many times for sharing documents, and whilst it’s excellent for simple lists and spreadsheets, for anything creative it is woefully ill-equipped.

And the rest…

There are plenty of other options for simply writing: StackEdit appears to be excellent if you don’t need collaboration options; Jetpack Markdown is a great WordPress plugin for anyone who just wants to write in markdown; onword is great for anyone who just wants to write.

As for collaboration, there are a few companies seeking to develop the field: Quip allows general documents and notes to be stored together; Hackpad offers tons of features with the reliability of Dropbox (who have just acquired them).

Conclusion

Ultimately, no one has managed to combine writing and collaboration as elegantly as Editorially. The decision as to where to move our writing and editing has been tough and we’ll probably still be debating the problem in 2 weeks and 6 days. In all likelihood we’ll fall back on a number of different solutions.

It’s rare that a single app receives such unanimous praise, but Editorially seems to be universally popular. Its functionality was (and is, for the next three weeks) simple and reliable. It excells at improving the number one element of the Web: content.

Whilst we’ll have to accept that Editorially has gone the way of the dinosaurs, let’s hope that there’s an investor somewhere with an eye for an auspicious opportunity who can pour resources into one of the alternatives and fill the sizeable hole in the market that Editorially leaves behind.

Featured image/thumbnail, writing image via Shutterstock.

17 HTML5 Responsive Galleries & Components Bundle – only $37!

•     Faculty will share new concepts, detailed examples, and materials useful for developing engaging new course content
•     Collaboration and connection opportunities with colleagues and faculty
•     Innovative course components that inspire critical thinking in students and address pressing environmental issues

In this short, yet comprehensive, tutorial, we'll have a look at behavior driven development (BDD) with phpspec. Mostly, it will be an introduction to the phpspec tool, but as we go, we'll touch on different BDD concepts. BDD is a hot topic these days and phpspec has gained a lot of attention in the PHP community recently.

SpecBDD & Phpspec

BDD is all about describing the behavior of software, in order to get the design right. It is often associated with TDD, but whereas TDD focus on testing your application, BDD is more about describing its behavior. Using a BDD approach will force you to constantly consider the actual requirements and desired behavior of the software you're building.

Two BDD tools have gained a lot of attention in the PHP community recently, Behat and phpspec. Behat helps you describe the external behavior of your application, using the readable Gherkin language. phpspec, on the other hand, helps you describe the internal behavior of your application, by writing small "specs" in the PHP language - hence SpecBDD. These specs are testing that your code has the desired behavior.

What We Will Do

In this tutorial, we'll cover everything related to getting started with phpspec. On our way, we'll build the fundament of a todo list application, step-by-step, using a SpecBDD approach. As we go, we'll have phpspec lead the way!

Note: This is an intermediate article about PHP. I assume you have a good grasp of object-oriented PHP.

Installation

For this tutorial, I assume you have the following stuff up and running:

• A working PHP setup (min. 5.3)
• Composer

Installing phpspec through Composer is the easiest way. All you have to do is run the following command in a terminal:

$ composer require phpspec/phpspec
    Please provide a version constraint for the phpspec/phpspec requirement: 2.0.*@dev

This will make a composer.json file for you and install phpspec in a vendor/ directory.

In order to make sure that everything is working, run phpspec and see that you get the following output:

$ vendor/bin/phpspec run
    
    0 specs
    0 examples 
    0ms

Configuration

Before we start, we need to do a little bit of configuration. When phpspec runs, it looks for a YAML file named phpspec.yml. Since we will be putting our code in a namespace, we need to make sure that phpspec knows about this. Also, while we are at it, let's make sure that our specs looks nice and pretty when we run them.

Go ahead and make the file with the following content:

formatter.name: pretty
    suites:
        todo_suite:
            namespace: Petersuhm\Todo

There are many other configuration options available, which you can read about in the documentation.

Another thing we need to do, is to tell Composer how to autoload our code. phpspec will use Composer's autoloader, so this is required for our specs to run.

Add an autoload element to the composer.json file that Composer made for you:

{
        "require": {
            "phpspec/phpspec": "2.0.*@dev"
        },
        "autoload": {
            "psr-0": {
                "Petersuhm\\Todo": "src"
            }
        }
    }

Running composer dump-autoload will update the autoloader after this change.

Our First Spec

Now we are ready to write our first spec. We'll start by describing a class called TaskCollection. We'll have phpspec generate a spec class for us by using the describe command (or alternatively the short version desc) .

$ vendor/bin/phpspec describe "Petersuhm\Todo\TaskCollection"
    $ vendor/bin/phpspec run
    Do you want me to create `Petersuhm\Todo\TaskCollection` for you? y

So what happened here? First, we asked phpspec to create a spec for a TaskCollection. Second, we ran our spec suite and then phpspec automagically offered to create the actual TaskCollection class for us. Cool, isn't it?

Go ahead and run the suite again, and you'll see that we already have one example in our spec (we'll see in a moment what an example is):

$ vendor/bin/phpspec run
    
          Petersuhm\Todo\TaskCollection
    
      10  ✔ is initializable
    
    
    1 specs
    1 examples (1 passed)
    7ms

From this output, we can see that the TaskCollection is initializable. What is this about? Take a look at the spec file that phpspec generated, and it should be clearer:

<?php
    
    namespace spec\Petersuhm\Todo;
    
    use PhpSpec\ObjectBehavior;
    use Prophecy\Argument;
    
    class TaskCollectionSpec extends ObjectBehavior
    {
        function it_is_initializable()
        {
            $this->shouldHaveType('Petersuhm\Todo\TaskCollection');
        }
    }

The phrase 'is initializable' is derived from a function named it_is_initializable() which phpspec has added to a class called TaskCollectionSpec. This function is what we refer to as an example. In this particular example, we have what we refer to as a matcher called shouldHaveType() that checks the type of our TaskCollection. If you change the parameter passed to this function to something else and run the spec again, you will see that it will fail. Before completely understanding this, I think we need to investigate in what the variable $this refers to in our spec.

What Is $this?

Of course, $this refers to the instance of the class TaskCollectionSpec, since this is just regular PHP code. But with phpspec, you have to treat $this different from what you normally do, since under the hood, it's actually referring to the object under test, which is in fact the TaskCollection class. This behavior is inherited from the class ObjectBehavior, which makes sure that function calls are proxied to the spec'ed class. This means that SomeClassSpec will proxy method calls to an instance of SomeClass. phpspec will wrap these method calls in order to run their return values against matchers like the one you just saw.

You don't need a deep understanding of this in order to use phpspec, just remember that as far as you are concerned, $this actually refers to the object under test.

Building Our Task Collection

So far, we haven't done anything ourself. But phpspec have made an empty TaskCollection class for us to use. Now is the time to fill in some code and make this class useful. We will add two methods: an add() method, to add tasks, and a count() method, to count the number of tasks in the collection.

Adding a Task

Before we write any real code, we should write an example in our spec. In our example, we want to try to add a task to the collection, and then afterwards make sure that the task is in fact added. In order to do this, we need an instance of the (so far non-existing) Task class. If we add this dependency as a parameter to our spec function, phpspec will automatically give us an instance that we can use. Actually, the instance isn't a real instance, but what phpspec refers to as a Collaborator. This object will act as the real object, but phpspec allows us to do more fancy stuff with this, which we'll see soon. Even though the Task class doesn't exist yet, for now, just pretend it does. Open up the TaskCollectionSpec and add a use statement for the Task class and then add the example it_adds_a_task_to_the_collection():

use Petersuhm\Todo\Task;
    
    ...
    
    function it_adds_a_task_to_the_collection(Task $task)
    {
        $this->add($task);
        $this->tasks[0]->shouldBe($task);
    }

In our example, we write the code "we wish we had". We call the add() method and then try to give it a $task. Then we check that the task was in fact added to the instance variable $tasks. The matcher shouldBe() is an identity matcher similar to the PHP === comparator. You can use either shouldBe(), shouldBeEqualTo(), shouldEqual() or shouldReturn() - they all do the same.

Running phpspec will yield some errors, since we don't have a class named Task yet.

Let's have phpspec fix that for us:

$ vendor/bin/phpspec describe "Petersuhm\Todo\Task"
    $ vendor/bin/phpspec run
    Do you want me to create `Petersuhm\Todo\Task` for you? y

Running phpspec again, something interesting happens:

$ vendor/bin/phpspec run
    Do you want me to create `Petersuhm\Todo\TaskCollection::add()` for you? y

Perfect! If you take a look at the TaskCollection.php file, you will see that phpspec made an add() function for us to fill out:

<?php
    
    namespace Petersuhm\Todo;
    
    class TaskCollection
    {
    
        public function add($argument1)
        {
            // TODO: write logic here
        }
    }

phpspec is still complaining, though. We don't have a $tasks array, so let's make one and add the task to it:

<?php
    
    namespace Petersuhm\Todo;
    
    class TaskCollection
    {
        public $tasks;
    
        public function add(Task $task)
        {
            $this->tasks[] = $task;
        }
    }

Now our specs are all nice and green. Note that I made sure to typehint the $task parameter.

Just to make sure we got it right, let's add another task:

function it_adds_a_task_to_the_collection(Task $task, Task $anotherTask)
    {
        $this->add($task);
        $this->tasks[0]->shouldBe($task);
    
        $this->add($anotherTask);
        $this->tasks[1]->shouldBe($anotherTask);
    }

Running phpspec, it looks like we're all good.

Implementing the Countable Interface

We want to know how many tasks are in a collection, which is a great reason for using one of the interfaces from the Standard PHP Library (SPL), namely the Countable interface. This interface dictates that a class implementing it must have a count() method.

Earlier, we used the matcher shouldHaveType(), which is a type matcher. It uses the PHP comparator instanceof to validate that an object is in fact an instance of a given class. There are 4 type matchers, which all does the same. One of them is shouldImplement(), which is perfect for our purpose, so let's go ahead and use that in an example:

function it_is_countable()
    {
        $this->shouldImplement('Countable');
    }

See how beautiful that reads? Let's run the example and have phpspec lead the way for us:

$ vendor/bin/phpspec run
    
            Petersuhm/Todo/TaskCollection
      25  ✘ is countable
            expected an instance of Countable, but got [obj:Petersuhm\Todo\TaskCollection].

Okay, so our class isn't an instance of Countable since we haven't implemented it yet. Let's update the code for our TaskCollection class:

class TaskCollection implements \Countable

Our tests won't run, since the Countable interface has an abstract method, count(), which we have to implement. An empty method will do the trick for now:

public function count()
    {
        // ...
    }

And we're back to green. At the moment our count() method doesn't do much, and it's actually pretty useless. Let's write a spec for the behavior that we wish it to have. First, with no tasks, our count function is expected to return zero:

function it_counts_elements_of_the_collection()
    {
        $this->count()->shouldReturn(0);
    }

It returns null, not 0. To get a green test, let's fix this the TDD/BDD way:

public function count()
    {
        return 0;
    }

We're green and all is good, but this is probably not the behavior we want. Instead, let's expand our spec and add something to the $tasks array:

function it_counts_elements_of_the_collection()
    {
        $this->count()->shouldReturn(0);
    
        $this->tasks = ['foo'];
        $this->count()->shouldReturn(1);
    }

Of course, our code is still returning 0, and we have a red step. Fixing this is not too difficult and our TaskCollection class should now look like this:

<?php
    
    namespace Petersuhm\Todo;
    
    class TaskCollection implements \Countable
    {
        public $tasks;
    
        public function add(Task $task)
        {
            $this->tasks[] = $task;
        }
    
        public function count()
        {
            return count($this->tasks);
        }
    }

We have a green test and our count() method works. What a day!

Expectations & Promises

Remember I told you that phpspec allows you to do cool stuff with instances of the Collaborator class, AKA the instances that are automatically injected by phpspec? If you have been writing unit tests before, you know what mocks and stubs are. If you don't, please don't worry too much about it. It's only jargon. These things refers to "fake" objects that will act as your real objects, but allow you to test in isolation. phpspec will automatically turn these Collaborator instances into mocks and stubs if you need it in your specs. 

This is really awesome. Under the hood, phpspec uses the Prophecy library, which is a highly opinionated mocking framework that plays well with phpspec (and is build by the same awesome folks). You can set an expectation on a collaborator (mocking), like "this method should be called", and you can add promises (stubbing), like "this method will return this value". With phpspec this is really easy and we'll do both things next.

Let's make a class, we'll call it TodoList, that can make use of our collection class.

$ vendor/bin/phpspec desc "Petersuhm\Todo\TodoList"
    $ vendor/bin/phpspec run
    Do you want me to create `Petersuhm\Todo\TodoList` for you? y

Adding Tasks

The first example we'll add, is one for adding tasks. We will make an addTask() method, that does nothing more than adding a task to our collection. It simply directs the call to the add() method on the collection, so this is a perfect place to make use of an expectation. We do not want the method to actually call the add() method, we just want to make sure that it tries to do it. Furthermore, we want to make sure that it calls it only once. Take a look at how we can go about this with phpspec:

<?php
    
    namespace spec\Petersuhm\Todo;
    
    use PhpSpec\ObjectBehavior;
    use Prophecy\Argument;
    use Petersuhm\Todo\TaskCollection;
    use Petersuhm\Todo\Task;
    
    class TodoListSpec extends ObjectBehavior
    {
        function it_is_initializable()
        {
            $this->shouldHaveType('Petersuhm\Todo\TodoList');
        }
    
        function it_adds_a_task_to_the_list(TaskCollection $tasks, Task $task)
        {
            $tasks->add($task)->shouldBeCalledTimes(1);
            $this->tasks = $tasks;
    
            $this->addTask($task);
        }
    }

First, we have phpspec provide us with the two collaborators we need: a task collection and a task. Then we set an expectation on the task collection collaborator that basically says: "the add() method should be called exactly 1 time with the variable $task as a parameter". This is how we prepare our collaborator, which is now a mock, before we assign it to the $tasks property on the TodoList. Finally, we try to actually call the addTask() method.

Ok, what does phpspec have to say about this:

$ vendor/bin/phpspec run
    
            Petersuhm/Todo/TodoList
      17  ! adds a task to the list
            property tasks not found.

The $tasks property is non-existing - easy one:

<?php
    
    namespace Petersuhm\Todo;
    
    class TodoList
    {
        public $tasks;
    }

Try again, and have phpspec guide our way:

$ vendor/bin/phpspec run
    Do you want me to create `Petersuhm\Todo\TodoList::addTask()` for you? y
    $ vendor/bin/phpspec run
    
            Petersuhm/Todo/TodoList
      17  ✘ adds a task to the list
            some predictions failed:
              Double\Petersuhm\Todo\TaskCollection\P4:
                Expected exactly 1 calls that match:
                  Double\Petersuhm\Todo\TaskCollection\P4->add(exact(Double\Petersuhm\Todo\Task\P3:000000002544d76d0000000059fcae53))
                but none were made.

Okay, now something interesting happened. See the message "Expected exactly 1 calls that match: ..."? This is our failing expectation. This happens because after calling the addTask() method, the add() method on the collection was not called, which we expected it to be.

In order to get back to green, fill in the following code in the empty addTask() method:

<?php
    
    namespace Petersuhm\Todo;
    
    class TodoList
    {
        public $tasks;
    
        public function addTask(Task $task)
        {
            $this->tasks->add($task);
        }
    }

Back to green! It feels good, right?

Checking for Tasks

Let's have a look at promises too. We want a method that can tell us if there are any tasks in the collection. For this, we'll simply check the return value of the count() method on the collection. Again, we do not need a real instance with a real count() method. We just need to make sure that our code calls some count() method and do some stuff depending on the return value.

Take a look at the following example:

function it_checks_whether_it_has_any_tasks(TaskCollection $tasks)
    {
        $tasks->count()->willReturn(0);
        $this->tasks = $tasks;
    
        $this->hasTasks()->shouldReturn(false);
    }

We have a task collection collaborator that has a count() method that will return zero. This is our promise. What this means is that every time someone calls the count() method, it will return zero. We then assign the prepared collaborator to the $tasks property on our object. Finally, we try to call a method, hasTasks(), and make sure it returns false.

What does phspec have to say about this?

$ vendor/bin/phpspec run
    Do you want me to create `Petersuhm\Todo\TodoList::hasTasks()` for you? y
    $ vendor/bin/phpspec run
    
            Petersuhm/Todo/TodoList
      25  ✘ checks whether it has any tasks
            expected false, but got null.

Cool. phpspec made us a hasTasks() method and not surprisingly, it returns null, not false.

Once again, this is an easy one to fix:

public function hasTasks()
    {
        return false;
    }

We are back to green, but this is not quite what we want. Let's check for tasks when there are 20 of them. This should return true:

function it_checks_whether_it_has_any_tasks(TaskCollection $tasks)
    {
        $tasks->count()->willReturn(0);
        $this->tasks = $tasks;
    
        $this->hasTasks()->shouldReturn(false);
    
        $tasks->count()->willReturn(20);
        $this->tasks = $tasks;
    
        $this->hasTasks()->shouldReturn(true);
    }

Run phspec and we'll get:

$ vendor/bin/phpspec run
    
            Petersuhm/Todo/TodoList
      25  ✘ checks whether it has any tasks
            expected true, but got false.

Okay, false is not true, so we need to improve our code. Let's use that count() method to see if there are tasks or not:

public function hasTasks()
    {
        if ($this->tasks->count() > 0)
            return true;
    
        return false;
    }

Tah dah! Back to green!

Building Custom Matchers

Part of writing good specs is to make them as readable as possible. Our last example can actually be improved a tiny bit, thanks to phpspec's custom matchers. It's easy to implement custom matchers - all we have to do is to overwrite the getMatchers() method that is inherited from ObjectBehavior. By implementing two custom matchers, our spec can be changed to look like this:

function it_checks_whether_it_has_any_tasks(TaskCollection $tasks)
    {
        $tasks->count()->willReturn(0);
        $this->tasks = $tasks;
    
        $this->hasTasks()->shouldBeFalse();
    
        $tasks->count()->willReturn(20);
        $this->tasks = $tasks;
    
        $this->hasTasks()->shouldBeTrue();
    }
    
    function getMatchers()
    {
        return [
            'beTrue' => function($subject) {
                return $subject === true;
            },
            'beFalse' => function($subject) {
                return $subject === false;
            },
        ];
    }

I think this looks pretty good. Remember, that refactoring your specs is important in order to keep them up to date. Implementing your own custom matchers can clean up your specs and make them more readable.

Actually, we can use the negation of the matchers as well:

function it_checks_whether_it_has_any_tasks(TaskCollection $tasks)
    {
        $tasks->count()->willReturn(0);
        $this->tasks = $tasks;
    
        $this->hasTasks()->shouldNotBeTrue();
    
        $tasks->count()->willReturn(20);
        $this->tasks = $tasks;
    
        $this->hasTasks()->shouldNotBeFalse();
    }

Yeah. Pretty cool!

Conclusion

All our specs are green and look at how nicely they document our code!

      Petersuhm\Todo\TaskCollection
    
      10  ✔ is initializable
      15  ✔ adds a task to the collection
      24  ✔ is countable
      29  ✔ counts elements of the collection
    
          Petersuhm\Todo\Task
    
      10  ✔ is initializable
    
          Petersuhm\Todo\TodoList
    
      11  ✔ is initializable
      16  ✔ adds a task to the list
      24  ✔ checks whether it has any tasks
    
    
    3 specs
    8 examples (8 passed)
    16ms

We have effectively described and achieved the desired behavior of our code. Not to mention, our code is 100 % covered by our specs, which means that refactoring won't be a fear-inducing experience.

By following along, I hope you got inspired to give phpspec a try. It is more than a testing tool - it's a design tool. Once you get used to using phpspec (and its awesome code generation tools), you'll have a hard time letting go of it again! People often complain that doing TDD or BDD slows them down. After incorporating phpspec in my work flow, I really feel the opposite way - my productivity is significantly improved. And my code is more solid!