Yo friends! Oh, SO glad you've made it for our phpspec tutorial! You will not regret it. Thing number one to know about phpspec is: it's... just... fun!

Ok, but what is phpspec? It's a unit testing tool... exactly like phpunit. Wait... that's not totally right. If you watched our PHPUnit tutorial, then you know that PHPUnit is a perfectly fine tool for unit testing your code. So... why are we even talking about phpspec?

Here's the truth: yes, phpspec is a tool for unit testing your code. But, that's not its main job. Nope, it's a tool for helping you design your code in a well-organized, meaningful and maintainable way. You probably already think about the design and user experience of your front-end. But, have you ever thought about the design and experience of your PHP classes?

That's phpspec's job. And yes, as a nice by-product, you will get unit tests. And as a nicer by-product, you will also enjoy the process - coding with phpspec is fun. Oh, and later - we'll talk about how phpspec & PHPUnit fit together - like should we use both in the same app? Short answer: yes!

Starting Point: Empty Project!

Ok, let's go! Just like in our PHPUnit tutorial, we're going to design & build a dinosaur park - complete with T-Rex, stegosaurus, enclosures for our dinosaurs and, with any lucky, some security systems that - thanks to our tests - won't fail as soon as a storm rolls in or a developer leaves early for lunch.

To make sure our dinosaurs don't once again rule the Earth, you should totally code along with me. Download the course code from this page. When you unzip it, you'll find a start/ directory with the same code that you see here. But... well... what we have here is... nothing! Just an empty project with a composer.json file that also... has nothing important inside. This tutorial directory does have a few files that we'll use later - so make sure you have it.

We're starting with an empty project because phpspec is truly a framework-agnostic library. But don't worry - if you're a Symfony user, we'll build a structure that will be very familiar to you - with the same directories and namespaces as a Symfony app.

Installing phpspec

To get phpspec installed, open a terminal, move into the project, close Facebook, and run:

composer require phpspec/phpspec --dev

And.... ding! Just like with PHPUnit, installing phpspec means that you get a new, shiny executable! Run:


The phpspec executable really only has two commands: describe and run. And we'll talk about both of them very soon.

Configuration autoload in composer.json

But first, we need just a little bit of configuration to get things working. The first piece of configuration... has nothing to do with phpspec at all! Our app has no PHP classes yet. But when we add some, I want to put them in the src/ directory and prefix each namespace with App. That will be exactly like a Symfony project.

Open composer.json. To make sure Composer's autoloader knows where our classes live, we need to add some config here. This is code that you normally get automatically when you start, for example, a new Symfony project. But I want to show how it's done by hand so that we can truly understand what's going on behind the scenes.

Add autoload, then psr-4, then say that classes starting with App\\ will live in the src/ directory.

13 lines composer.json
... lines 2 - 6
"autoload": {
"psr-4": {
"App\\": "src/"

To make Composer notice this change, find your terminal and run:

composer dump-autoload

Autoloading... done!

Configuring phpspec

Next, one of my favorite things about phpspec is that it generates code for you! But to do that, it also needs to know that our classes will live in the src/ directory and that each namespace will start with App. Unfortunately, phpspec can't automatically get all this info from composer.json, but it's no problem.

Create a phpspec.yml file at the root of the project - phpspec automatically knows to look for this. Inside add suites then default. Like most testing tools, you can organize your tests into multiple groups, or "suites" if you want. In this tutorial, we'll stick to using the one, "default" suite.

5 lines phpspec.yml
... lines 3 - 5

Under this, add namespace: App - because all of our classes will start with the App namespace - and psr4_prefix: App. Those two lines are enough to help phpspec know where to generate our files.

5 lines phpspec.yml
... lines 1 - 2
namespace: App
psr4_prefix: App

And... team, we're ready to go! Next, let's create our first specification... ooOOOOooo. That's the file where we will describe how a single class should behave by writing examples. Woh.

Leave a comment!

  • 2019-01-10 weaverryan

    Yea! Awesome! Thanks for letting me know Diaconescu Petrisor! I'm still getting used to this new tool myself :).

    Happy new year to you too!

  • 2019-01-09 Diaconescu Petrisor

    Happy new year, thank you and cheers, all at once. Indeed it works like in the api-platform example

  • 2019-01-07 weaverryan

    Hey Diaconescu Petrisor!

    Let me give you a quick recommendation - and we can see if it helps :). Instead of setting up Nginx, try using the new Symfony console tool - you can see how to get it on this page:

    This tool allows you to create https servers without any issues - e.g.

    symfony serve --port=8443

    This should start an https web server in that project.

    It's a super new tool - but it should make your life easier :). A lot of the commands/features are only documented in the commands themselves. For example:

    # see all commands
    symfony list

    # get info about any command
    symfony serve --help

    Let us know if this helps!


  • 2019-01-07 Diaconescu Petrisor

    What I am to ask is not linked to phpspec.
    I discovered a new tool for api designing at the site
    I try to follow the chapter [Using Symfony Flex and Composer (advanced users)]
    I use Ubuntu 16.04 for development and nginx as web server. My problem is when I want to serve the page https://localhost:8443/
    I never set ssh connection before so I'm not sure I have to do. I respected directions from as far as regarding nginx+ssh and symfony docs for the rest. So my nginx now looks like so:
    server {
    listen 80 default_server;
    listen [::]:80 default_server;
    server_name localhost;
    root /home/---/www/Symfony/bookshop-api/public;
    include snippets/self-signed.conf;
    include snippets/ssl-params.conf;

    # SSL configuration
    listen 8443 ssl http2 default_server;
    listen [::]:8443 ssl http2 default_server;

    location / {
    # try to serve file directly, fallback to index.php
    try_files $uri /index.php$is_args$args;

    location ~ ^/index\.php(/|$) {
    fastcgi_pass unix:/var/run/php/php7.2-fpm.sock;
    fastcgi_split_path_info ^(.+\.php)(/.*)$;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    fastcgi_param DOCUMENT_ROOT $realpath_root;


    # return 404 for all other php files not matching the front controller
    # this prevents access to other php files you don't want to be accessible.
    location ~ \.php$ {
    return 404;

    error_log /home/----/logs/nginx/symfony_error.log;
    access_log /home/----/logs/nginx/symfony_access.log;

    With these setings htt content is served OK but when i type:https://localhost:8443/ as it's expected I hit the privacy error page(Your connectiois not private). I don't know how to do from here.
    In api-platform docs says "You'll need to add a security exception in your browser to accept the self-signed TLS certificate that has been generated for this container when installing the framework. " Which framework is reffered? api-platform ? symfony? This TLS certificate must be generated itself ? Is already generated ? Where it is? How I add this mentioned security exception in google chrome? In chrome I found in private and security settings "Manage certificates" option. I presume I must follow the tab "Your certificates" and Import the aforementioned TLS certificate. I think right? And again where is this TLS certificate?