Docker + xdebug

Presenting various ways to setup and configure your docker container with xdebug and how to integrate with your IDE.

Debugging, an issue that all developers should live with.

There are several strategies we can use to manage debugging, from stopping execution after dump / print the content of the variable we want to inspect (I still with this more often that I’d like to admit) to more sophisticated tools or web-server  modules.

Okay, it does not enough complicated so, now let’s add DevOps. Yeah, if you want to use a tool like xdebug (here is a great tutorial about how to install it Remote PHP Debugging with Xdebug) within Docker containers.

Some questions came to my mind when I stumbled upon this situation: How do I setup the container? How can I expose xdebug outside of my containers? How can I integrate remote debugging with my IDE workflow?

Well, I don’t have the answer for all this questions, but I will show some examples and tips various ways to setup xdebug inside your docker container and connect it with PHPStorm.

Creating Docker container

This step is pretty much the same for all alternatives and OS platforms. Here we will discuss the very basic settings to create a container.

My example will be based on a clean Erdiko project, so I already have the structure to test, umm debug, some code.  To try out the container clone from github, https://github.com/arroyolabs-blog/docker-xdebug

So let’s start creating a custom Dockerfile that will look like this:

FROM php:5.6-fpm
MAINTAINER Leo Daidone <leo@arroyolabs.com>

RUN apt-get update && apt-get install -y \
    libpq-dev \
    libmemcached-dev \
    curl

# Xdebug
# here is the installation
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug
# here I'm copying the config file we will discuss in the next section
COPY ./etc/xdebug.ini /usr/local/etc/php/conf.d/

RUN usermod -u 1000 www-data

CMD ["php-fpm"]

We need to create this file instead of use the official php:5.6-fpm image, because we need to run the pecl install command within the created container. Note that I also copied “xdebug.ini” from etc folder, both, folder and file should exists in the same directory as Dockerfile, otherwise you will need to change the source path to the real location of your custom “xdebug.ini”. I choose this way because I think is easier to maintain an .ini file instead of a bunch of bash command.

Now we will need a docker-compose.yml to orchestrate the whole setup. Let’s break down the example below:

version: '2'
services:
  data:
    image: busybox
    volumes:
      - ../:/var/www/code
      - ./nginx/:/etc/nginx/conf.d

  web:
    image: nginx
    volumes_from: [data]
    links:
      - fpm
    ports:
      - "8088:80"

  fpm:
    build:
      context: .
      dockerfile: Dockerfile-PHP
    volumes_from: [data]
    environment:
      PHP_IDE_CONFIG: "serverName=docker"

I’ve defined three services, data, a busybox with the only purpose of mount and map volumes that will be shared by the other services. One web service that is an official Docker nginx image, the web server I will use in this example, finally, fpm, that will be based on our previous Dockerfile and where we will discuss variations in the next section.

Note that I’m not exposing the 9000 port (the default xdebug port) in any of Docker settings. This is the first trick for Linux, do not expose the port, just use it. That way when you try to use you IDE, you will not see an error like

Can't start listening for connections from 'xdebug': Port 9000 is busy.

Setting up xdebug

xdebug.default_enable=1
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
; port 9000 is used by php-fpm
xdebug.remote_port=9000
xdebug.remote_autostart=1
; no need for remote host
xdebug.remote_connect_back=1
xdebug.idekey="PHPSTORM"

This is the basic configuration I use with the Docker code defined in the previous section. It should work fine on Linux boxes, but I found some issues trying to run it in Mac OS. I will show you some changes I tried that worked on both OS.

First issue I found when I tried to make my project works on Mac was the ports’ binding and interfaces. How can I overcome the port busy error?

After some tries I found a nice trick, I recommend, add an alias to our interface with static IP.

In Mac:

sudo ifconfig en0 alias 10.254.254.254 255.255.255.0

In Linux:

sudo ip addr add 10.254.254.254/24 brd + dev eth0 label eth0:1

Now in order to use this new static IP, we need to add this two new lines in our xdebug.ini:

xdebug.profiler_enable=0
xdebug.remote_host=10.254.254.254

I suggest set to zero all other lines except for “remote_enable” and of course “remote_port“.

Finally, our docker-compose.yml shold looks like this:

version: '2'
services:
  data:
    image: busybox
    volumes:
      - ../:/var/www/code
      - ./nginx/:/etc/nginx/conf.d

  web:
    image: nginx
    volumes_from: [data]
    links:
      - fpm
    expose:
      - "9000"
    ports:
      - "8088:80"

  fpm:
    build:
      context: .
      dockerfile: Dockerfile-PHP
    volumes_from: [data]
    environment:
      PHP_IDE_CONFIG: "serverName=docker"
      PHP_XDEBUG_ENABLED: 1 # Set 1 to enable.
      XDEBUG_CONFIG: remote_host=10.254.254.254

Note that now I’m exposing “9000”, this is because I’m using a different IP address to bind this port. Also I’ve added two new environment vars, one to enable xdebug and other to set the remote host address.

Configuring you IDE

As I mention above, I’m going to use PHPStorm to show you how to setup a Debug client. For practical purpose it will be separated in two sections, the first one based on Linux approach, and other for Mac.

But first let me start with common steps for all platforms:

you will need to go to Settings ( linux shortcut: ctrl+alt+s; Mac shortcut: Cmd+, ) and check in Language & Frameworks / PHP / Debug looks like the image

linux_xdebug

After that go to DBGp Proxy and follow the steps for each platform

preferences

Linux example

Since you are using localhost (127.0.0.1) and xdebug has PHPSTORM as ide_key those two values can be empty here:

linux_dbgp

now you have to go to Debug configuration:

server_dropdown

with the green plus sign, add a new PHP Remote Debug, change Name to docker, fill Ide Key field, and click on periods to add a new server

linux_remote

after you click on periods this new window will be opened. Again, click on green plus sign to add a new server that will be named docker, fill all field as it’s being shown, including Use path mappings check, this is a very important step, you need to let IDE know how to related docker path with local path.

linux_servers

Mac example

Assuming here you are using the tweak settings with IP alias, the steps are the same as linux, just need to change values for the one in screenshots:

preferences_2

run_debug_configurations

Note this time Host field is not 127.0.0.1 but the new alias IP.

servers

Finally, to start debugging just click on the phone icon and green bug icon

server_dropdown

add some breakpoints and happy debug!

 

Thanks for reading, I hope you have enjoyed this article and don’t miss our next entry where I will bring you a tutorial about PHPdbg, and how to use it with Docker.

Moving to Slim PHP

After developing Erdiko for over 4 years we are making some big changes for the next major release. We are modifying the framework to support Slim. Erdiko will soon be built on top of the great features of the Slim PHP micro framework.

We have been developing our open source micro framework for 4 years now.  We haven’t publicized it much but we’ve poured hundreds of hours into it and use it considerably on client projects. The framework and many of its modules are used and liked in the PHP community.

We are ready to take Erdiko to the next level and in the process of architecting a new Erdiko framework.  The next version will be more modular, better tested and, most importantly, built on top of an existing micro framework.

When we started Erdiko the other micro frameworks weren’t there yet, thats part of the reason we start Erdiko.  Silex and slim were in infancy, lumen didn’t exist (and Laravel was just starting to get more notice), and heck composer was less than a year old and wasn’t on many people radar yet.  Fast forward a few years and we now find a very different landscape for PHP and JavaScript development.

Speaking of this landscape, the fact that we can and do move much of the app to the front-end with powerful JavaScript frameworks means the duty of the back end has changed.  You no longer need to add ridiculous layers of front-end logic in your PHP classes and templates.  This shift alone means you need to rethink what you need from a php framework.

Thats where micro frameworks soar…places where you need a fast backend and leveraging a smarter front-end (e.g. SPA with JavaScript).  Add the great SaaS tools at your disposal as well and you have all the ingredients to make performant websites that you can grow your business with.  You don’t need a big bloated full stack in most cases.  If you do, often the built in feature X just won’t cut it and you end up integrating a 3rd party package or writing that component yourself anyways.

Now back to the topic at hand, what’s the deal with SlimPHP?  After reviewing numerous frameworks it became apparent that SlimPHP was the best of bunch for the kind of code we like, community we like and of course the kind of features and performance we like.  It’s router, http objects and flexibility has Erdiko beat.  We also looked at and experimented with Silex, lumen and some others before making the decision.

Erdiko adds the MVC and theming support to a typical micro framework.  We’ve developed some useful components and feel that adding these on top of an existing framework will make development even more efficient and flexible.

Erdiko has some special features that will aim to make development more enjoyable and lead to better applications.  We have been distilling pieces of Erdiko that will be moved and improved to work with Slim.  Right now we feel the configuration, theme engine and controller support will make the cut.  Actually quite a bit of erdiko will exist in the new framework, but we will strive to leverage slimphp and the slim paradigm whenever possible.  On the model side we have included wrappers for powerful ORMs so that developers can pick the best one for the job and install with one command.

Remote PHP Debugging with Xdebug

Introduction

In our previous posts, we discussed how to use some tools to explore and debug legacy code. This blog post will explore one of these tools that I personally use quite often in depth: Xdebug and Remote Debugging.

We’ll explore the installation, the required settings tweaks, and some basic tools and workflows to get you started. The least fun and hardest part of this whole process is the installation.

Having xdebug up and running will speed up your code investigations and will really help you dig into troublesome code. It will also give you the best insight into code you aren’t familiar with works without resorting to die statements and var_dumps for small windows.

Development Only

Please only install this on your development and staging environments! Do not install this on any public facing server!

Remote Debugging

I want to take a minute and explain the concept of remote debugging with Xdebug. Until a few years ago, I would install XDebug only to get the “pretty error printing” features. While these features allowed some better control over how I was viewing errors and my var_dump results, it really added nothing I critically needed. Remote debugging now makes XDebug a short list of ‘need to install’ things when setting up a new environment.

Xdebug offers mechanisms to allow you to set breakpoints in your code to stop it’s execution and view the current state. This means you can say “stop here and let me take a look around at what the code is doing at this moment” on the server itself. You actually connect to the server and can poke around, set some conditional break points (where you stop execution when a variable is set to a certain value) and even evaluate some raw PHP on the server given certain conditions.

To accomplish this, you must connect a debugging tool to your server with a specified and exposed port and talk to it using a protocol provided by XDebug. Your debugger is the tool you use on your machine, XDebug is the tool/port/settings collection you use to connect to your server.

If this sounds like the basic IDE debugging tools you have used with other languages like C++ and JAVA (and also like something overcomplicated for being such a normal feature for other development stacks), it should. It’s pretty much the same thing. The biggest difference here is that this was not a widely used debugging method for hosted PHP. I’d like to help change that with this blog post.

Installing the Xdebug Extension

The xdebug project and github page offer some installation instructions that feel woefully lacking. Also, they offer little advice tailored to individual setups and environments. I’ll try and provide some examples of common installation methods.

Please note that these methods assume you are installing on the same server you host your development environment that serves the PHP code you wish to debug. This means, if you are running a vagrant box or docker container to host your code, install xdebug on this server instance. If you host your locally code on the same machine you are edit and maintain the code on, install xdebug on this machine. See the section above for some clarification on remote debugging.

All of these instruction assume you have administrator access and some level of comfortability with the *unix command line. If you do have access to your server in this capacity, or you are not comfortable with running these commands, you might want to find a grown up to help you.

pecl / pear

You can install Xdebug extension with the pecl tool and then tweak your php.ini file to include the installed extension. The official docs recommend this route first actually. The installation instructions are the same with the pear tool as they are for pecl. I have found this is the easiest installation method if you are running your server on a MacOS environment.

After you are sure you have pecl installed, run this command on your command line.

pecl install xdebug

apt-get / yum

If you are running your server on an Ubuntu/Debian/CentOS machine, you can install the xdebug with your specific package manager.

sudo apt-get install php5-xdebug

or

yum install php5-xdebug

Homebrew

This is a method I have never tried personally but I know there are some recipes specifically for installing xdebug with homebrew.

From what I read, you will need to add the homebrew-php repository and install this from the command line as well. Check out this repo link for more information.

Compiling it yourself

Another method I have never tried personally, but I know its possible. If you are want to do this yourself, you might be beyond the scope of this post. I’ll just point you to the project page for the most up to date information.

Update your php.ini file

Find your newly installed php extension and add this line to your php.ini file

zend_extension=“/usr/local/php/modules/xdebug.so”

Replace the “xdebug.so” file with whatever your tool installed. It’s also safe to create a symlink with the filename “xdebug.so” as well. If you have trouble finding this file, try the following command to find the extension file:

find / -name ’*xdebug*.so’ 2> /dev/null

Verifying your XDebug Installation

Restart apache and create a test file called test.php with the following lines of code and load it into your browser:

<?php

phpinfo();

Search for “xdebug” and you should see something like this in your browser:

image

If you see a line that looks like the one highlighted above, congrats, you have installed xdebug!

Port Forwarding

You will need to expose some ports on your server to allow connections from your debugging client. How you accomplish this will certainly depend on your individual environment setup, but I would like to note this to save you the time I lost trying to find out why I could not connect.

And we will explain the port you will need to be expose and forward in this next section…

Xdebug INI Settings

Here are some of the INI settings you will need to update in order to enable remote connections. These settings will be found in your php.ini file, or a possible xdebug.ini file if one was created by your install method.

  • xdebug.remote_host
    • This setting allows you to specify an address where you debugging client is connecting from.
    • In most cases, this will be set to “localhost”, but may differ in your development environment.
    • This setting is ignored if xdebug.remote_connect_back is set to TRUE. See more info below.
  • xdebug.remote_autostart
    • This setting enables remote debugging, turn this on!
  • xdebug.remote_port
    • This setting allows you to specify a port for your debug client to connect to the remote server with. You will need this value when configuring your remote debugging tool.
    • This is typically set to 9000 but you can update this to any port that isn’t being used if you feel contrary.
  • xdebug.var_display_max_children
    • This setting allows you to specify the amount of array children and object’s properties are shown when you use a var_dump or use your debugging client’s function trace tool.
    • By default this is set to 128, but you can set it to -1 if you want to remove the limit entirely.
  • xdebug.var_display_max_data
    • Like var_display_max_children, this setting allows you to set a  maximum string length that is shown when variables are displayed in var_dumps or function traces.
    • By default this is set to 128, but you can set it to -1 if you want to remove the limit entirely.
  • xdebug.var_display_max_depth
    • Another setting that allows you to set a limit when using var_dump or function tracing, but this one sets the nested levels of array elements and object properties displayed.
    • By default, this is set to 128, but again if you live dangerously you can remove the limit entirely and set it to -1.
  • xdebug.scream
    • Setting this value to true will disable the @ (the “shut up”) operator entirely.
    • This is super useful when you find out when you predecessor was just hiding a critical error behind the @ operator and you can finally go to be because you found the elusive notice showing the variable was never set in the first place and you had no idea and thats why you can’t get the page to load when you don’t have a cookie set in IE 9.
  • xdebug.remote_connect_back
    • Setting this value to true will allow you to connect and attach a remote debugging client to your server from any address.
    • This setting is great for shared development environments but is quite dangerous since it will just allow anyone to connect who tries. YES, anyone.
    • Also of note, this will override the xdebug.remote_host setting.

Remote Debugging Tools

Editors

PHPStorm & SublimeText

While I personally like to use the stand alone tools, I do know a lot of people who prefer to use these editors to remote debug.

While I’m sure a cursory google search can lead you to some better instructions on how to install and configure these tools, I thought it was worth mentioning since a lot of people use these tools and they offer the remote debugging tools you might want to use.

Stand Alone Tools & Helpers

MacGDBp

This is a tool I use on an almost daily basis. Its relatively small and lightweight, and gets out of the way when I am done. I also mentioned it in our last blog post. I do need to note that this tool does not seem to be updated frequently and occasionally crashes without warning. That being said, I still highly recommend it.

Chrome Xdebug Enabler

This is a simple chrome extension that allows you to toggle the xdebug remote debugging cookie for a given URL. This is great to quickly start and stop a remote debugging session.

It’s pretty much an unobtrusive button that lives in chrome. I would install it now if I were you.

Conclusion

I barely touched the surface of remote debugging using xdebug, but I hope I inspired you to install and configure it now. Stop using var_dump and die statements and debug like a grown up!

Legacy Code Evaluation Part 2 – Back End Code Evaluation and Tools

Intro

All of us will encounter legacy code, and most of us will ‘inherit’ code to maintain. In our first post on legacy code, we talked about getting the things you need to start working on a project. In this post, we will talk about how you can evaluate the backend code you will most likely have to start digging in to start new features or squashing bugs.

While you will encounter a significant amount of UX or front-end issues when starting on a new project, you are also just as likely to have to track an issue to the underlying backend code. The backend not only creates the foundation for your web app but its also the last line of defense for your back end code. At minimum issues on the backend will cause confusing results or headaches. At worst, issues on the backend will expose some of the most vital parts of your webapp to exploits.

Most backend code is the result of a lot of hours and hard work; it can be extremely confusing to wrap your head around the basic concepts let alone the deeper portions of the code. We’ll discuss some basic patterns and explain some of the tools we use to explore code, PHP code in particular, when we take on a project with some ‘baggage’.

Strategies

I like to split the application into small semantic sections. You can either break an application down into ‘workflows’, the actions a user may perform with an application; or as ‘roles’, things a particular actor will use a web app for. While this may sound like a very high level activity for inspecting back end code I think its crucial for understanding the application itself.

Once you have split the code into sections, trace the entire workflow. Follow the code from the beggining of an action to the resulting output. Tracing through the code will allow you to completely understand it.

Debugging and Tracing Tools

Xdebug

This is one of my favorite tools and is the first thing I install when I set up a new environment. Not only does this give me much easier to read error outputs, but it also gives you some great tools for interactive debugging. Seriously, if you do nothing else I suggest, at least install xdebug.

Remote Interactive Debugging – MacGDBp & chrome-xdebug-enabler

Interactive debugging is the best tool for finding that super stubborn bug or finding out why something isnt working as you expect. With a remote interactive debugger you can set break points and view exactly what the code is doing at a given point in time. You can actually inspect a variable value and watch it change as you step through the lines of code. This is something you should get excited about. Check out the screenshot below to see this in action with an example Erdiko project:

I use MacGDBp, a Cocoa based debugging tool that allows you to set break points and view the code when you set break points. I’ve been told that PHPStorm and even Sublime have some interactive debugging tools, I have not used those. MacGDBp is a bit dated, and I think almost abandonware, but it is still an indispensible tool in my aresenal. Check out the MacGDBp project docs for more info about the feature set and how to install it.

Personally, I would recommend using MacGDBp along with xdebug and the chrome extension ’chrome-xdebug-enabler’ to interact with your debugger. Using this extension you can conditionally turn the debugging off and on as you wish when refreshing the page.

I should note that while I personally use MacGDBp with vim, many other editors also include some remote debugging tools. PHPStorm has this functionality built in, but there are plugins for SublimeText and other full editors. We will explore those in a later post.

PHPLint and PHPCodesniffer

There are two great tools for getting some high level information about a PHP codebase: PHPLint and PHPCodesniffer.

PHPCodesniffer evaluates code based on a provided set of rules and standards and outputs a report that can give you a good idea of how ‘bad’ things look under the hood. It’s actually two tools: phpcs and phpcbf. phpcs evaluates the code, phpcbf attempts to fix the code. Personally, I like to use some discretion when tweaking code, so I would reccomend using phpcbf sparingly.

PHPLint is another tool, very similar to PHPCS that also outputs information on a code base based on rules and validation sets. This one is also very useful for generating user docs based on docblocks. This can be EXTREMELY useful when you need to collect a lot of information about a large codebase and create some baseline documentation for your team.

Unit Testing

Unit testing is often touted as the best prevention of introducing new bugs and finding conflicting code. I would also like to note, most people ignore the fact that introducing unit testing to legacy code is a painful process. Code written without testing in mind can often be a pain to manage dependencies and ‘magically’ required code.

This is a topic that actually deserves its own blog post, but I do want to mention it in this one.

… to be continued

In my next post, ill include some instructions on how to install xdebug on your local *nix development environment.

A New Framework Architecture for 2016

Why a new architecture?

PHP is the most popular language on the net and has a wide array of frameworks, apps and packages available.  Most of the best ones are open source, free or have a freely available version of their paid app.

That being said, it’s only more recent that the frameworks are being made, or attempts are made, to make them work together as components.  I thinks its about time to rethink or re-imagine how a developer or architect can create complex systems in an incremental and meaningful way.

I spoke a bit about the history and features of PHP previously.  Folks like Facebook and Baidu use it extensively. Some of the PHP platforms that are widely adopted are Drupal, WordPress, Magento, Joomla, Media Wiki, Symfony, Laravel, and Yii.  All have considerable user bases and impressive feature sets.  They all however, have very different conventions, coding styles and theming styles.

Speaking of theming, the way developers create a UI these days is dramatically different than how it was done in the past.  Browsers are more powerful and devices are more diverse.  JavaScript is much more powerful and more uniformly supported than it was a decade ago when PHP 5 came out (don’t forget about the V8 engine too).

  • Theming: Not everything has to be PHP anymore.  We now have
    • Bootstrap, & Material
    • Pre-compiling theme & components
      • Less/Sass
      • Gulp, bower, & grunt composition and code prep
    • Powerful JS frameworks and libraries: Angular, React, & more
      • Many more options than just jQuery these days

What’s missing from existing frameworks

  • Modularity
    • Some frameworks handle it well, but often the modularity is very limited to a smaller ecosystem, or at least an isolated ecosystem.
  • Composibility
    • Things are too often configured (db and config file) and not composed.  That is very convenient, but leads to slow production code and is more limited than a composable system
  • Security
    • Code should be outside the web root
    • Should work with and without a reverse proxy
    • Protect against common attacks
  • Models / ORM
    • The framework should work with any composer based (or modular) ORM
      • With so many rich ORMs and data connection tools available I don’t believe the framework should be relegated to only one ORM or model paradigm
      • Different scenarios call for different model approaches.  How can the framework facilitate the right data tool for the job?
  • Mashability
    • Create components that can easily be used together
    • Easy to add to any framework including erdiko
      • Leverage more code across and between frameworks
        • e.g. Use Eloquent in Slimphp
  • Routing
    • Symfony Request & Response
    • Symfony Router
    • Easy Compiled Routes
      • PhpMatcherDumper
    • Via plugins
      • Database routes (cms content)
      • Application specific routes
        • e.g. Magento, WordPress, Drupal
  • Server Automation
    • Work well with containers, modern deployments and popular coding workflows

The Developer / Architect paradox

This does however have a downside and that is what I call the developer / architect paradox.  This is developers wanting a complete solution and picking a tool that gets them 80% of the way there very quickly but they struggle with the 20% and have to make too many sacrifices and concessions to make the full system work.

Legacy Code Evaluation Part 1 – Intro

All of us will encounter legacy code, and most of us will ‘inherit’ code to maintain. Even on the freshest of projects 99 % of the time you will encounter some ‘baggage’ code that we will have to maintain. This is especially true as a contractor for any PHP project. Deservedly or not, PHP has a bad reputation for code quality

The good news is that you can mitigate some of the worst aspects of a legacy project by doing some work up front. Making sure you have all the assets you need up front can prevent embarrassing emails to the client asking for random things and generally making your life easier.

For this first of three blog posts about legacy code, we’ll spit this into two lists: Things you need and nice to haves.

Things you need:

Server Access 

This should be a no brainer. You need access to the server to make sure you have the most up to date code, and hopefully you will be deploying some updates in the near future. Yes, this may seem very obvious but you would be surprised how easy it is to forget this step in the excitement of a new project.

Ask the client how they access and how the previous team accessed the server. Make sure you try and actually login with these credentials as well. After you successfully get access, you may need to deactivate or in the minimum change some passwords of the previous server users.

Code in Version Control

You will also want access to the most up to date version of the codebase, hopefully in a form of version control. Again, while this seems like a no-brainer, it is very important to track changes you make once you start to dig into the code. It can also provide some information as to what the previous developer was thinking with the code in the past.

Once you have access to this you can convert it to your VCS of choice or continue to use the one provided. You will really want to consider keeping the VCS the same if you are working with other existing teams or with the client who needs access to the code.

It is also worth your time to ensure that the code in the VCS is sync’d and up to date with what is on the production server. There are many file comparison tools that can be used to compare entire directories which we will cover in our next post. While you can assume a previous team who had a code base in version control has kept things up to date… like the Russians say: Trust, but verify.

Documentation

Ask for any documentation the client can provide, good or bad. Something is better than nothing.

You should also plan on converting this into some form of living document you can edit and share easily. A self hosted wiki works great for tracking changes, but so does a markdown file stored in the repo itself. Anything easy to edit will remove another barrier that will prevent you from updating documentation, and already loathsome task.

You should be documenting everything as you explore the project. Document the file and database structure, document the existing workflows. Ask the client how things “should work” and then note how things are broken. Get it all into a living document so you can track your progress.

Nice to Haves:

A Shared Project Management System

Create a method in which you can communicate your project status with the customer. This will also provide a great resource in which you and the client can document bugs and future updates.

A shared system will allow you to manage your project beyond instant messages and emails. It also provides instant feedback to the client allowing them to see ‘exactly what they are paying you for’ and allows for the easier exchange of ideas.

If you’re lucky, the client may already have one (and be trained on how to use it.) It’s also very likely the client does not know how or what a Project Management System is, in which case priority number one is showing them how it is useful.

A separate Staging and local development environment

Tools like Docker and Vagrant allow you to spin up servers quickly and provide tools to re-recreate the server after you mess it up. This will become very important as you dig in and mess things up while trying to determine exactly what is wrong.

Our next post will focus on some frameworks and tools we commonly use to evaluate legacy code. We’ll also provide some basic examples of how to use these tools.

Evolution of the PHP Language

PHP is a language for the web, the most popular one in fact.  That’s not to say it’s the best, or the worst for that matter but the number of webpages powered by PHP outweighs all the other languages including JAVA, python, Ruby on Rails, etc.

On the heels of the launch of PHP 7, I thought it would be interesting to see the evolution of PHP.  The focus here is mostly on the evolution of PHP starting with PHP 5.0 which was released almost a decade ago.  Objects were introduced in Version 4, but PHP didn’t really become a more modern object oriented language until version 5.  It’s when the language really started to grow up.

Let’s take a look at what each version of 5 brought us.

PHP 5.0

Version 5 continues the move toward object oriented programming

New Features

  • Zend Engine 2, which greatly improved PHP’s performance
  • MySQLi, or improved MySQL, was introduced
  • SQLite is now built into PHP

For more information check out, http://php.net/manual/en/migration5.incompatible.php

PHP 5.1

New Features and Improvements

  • Support for custom autoloading was eventually a game changer for PHP framework creators
    • spl_autoload_register in PHP 5.1.2
  • A complete rewrite of date handling code, with improved timezone support.
  • Significant performance improvements compared to PHP 5.0.X.
  • PDO extension is now enabled by default.
  • Over 30 new functions in various extensions and built-in functionality.
  • Over 400 various bug fixes

For more information check out, http://php.net/manual/en/migration51.changes.php

PHP 5.2

New Features

  • Improved memory manager and increased default memory limit. The new memory manager allocates less memory and works faster than the previous incarnation.
  • New Extensions (The following are new extensions added (by default) as of PHP 5.2.0)
    • Filter – validates and filters data, and is designed for use with insecure data such as user input. This extension is enabled by default; the default mode RAW does not impact input data in any way.
    • JSON – implements the JavaScript Object Notation (JSON) data interchange format. This extension is enabled by default.
    • Zip – enables you to transparently read or write ZIP compressed archives and the files inside them.

PHP 5.3

One of the most important updates to PHP that I can think of.  Don’t be surprised if you come across a site that is still running version 5.3 (however this is not recommended 😉

New Features

  • Support for namespaces has been added
  • Support for Late Static Bindings has been added
  • Support for jump labels (limited goto) has been added.
  • Support for native Closures (Lambda/Anonymous functions) has been added.
  • There are two new magic methods, __callStatic() and __invoke().
  • Nowdoc syntax is now supported, similar to Heredoc syntax, but with single quotes.
  • It is now possible to use Heredocs to initialize static variables and class properties/constants.
  • Heredocs may now be declared using double quotes, complementing the Nowdoc syntax.
  • Constants can now be declared outside a class using the const keyword.
  • The ternary operator now has a shorthand form: ?:.
  • The HTTP stream wrapper now considers all status codes from 200 to 399 to be successful.
  • Dynamic access to static methods is now possible

For more information check out, http://php.net/manual/en/migration53.new-features.php

PHP 5.4

Traits and built in development web server are really cool.  Although they have been here since 5.4 some folks are just now using them.

New Features

  • Support for traits has been added.
  • Short array syntax has been added, e.g. $a = [1, 2, 3, 4]; or $a = [‘one’ => 1, ‘two’ => 2, ‘three’ => 3, ‘four’ => 4];.
  • Function array dereferencing has been added, e.g. foo()[0].
  • Closures now support $this.
  • <?= is now always available, regardless of the short_open_tag php.ini option.
  • Class member access on instantiation has been added, e.g. (new Foo)->bar().
  • Class::{expr}() syntax is now supported.
  • Binary number format has been added, e.g. 0b001001101.
  • Improved parse error messages and improved incompatible arguments warnings.
  • The session extension can now track the upload progress of files.
  • Built-in development web server in CLI mode.

the <?= tag has been a contentios item in some code bases, especially with larger teams, it’s great that it is always available now.  It’s cleaner and easier to write than <?php echo

For more information check out, http://php.net/manual/en/migration54.new-features.php

The page on traits is worth a read too, http://php.net/manual/en/language.oop5.traits.php

PHP 5.5

New Features

  • finally keyword added
  • password_hash()
  • foreach now supports list()
  • empty() supports arbitrary expressions
  • array and string literal dereferencing
  • Generators added

For more information check out, http://php.net/manual/en/migration55.new-features.php

To learn more about Generators read, http://php.net/manual/en/language.generators.overview.php

PHP 5.6

New Features

  • Constant expressions
  • Variadic functions can now be implemented using the … operator, instead of relying on func_get_args().
  • Arrays and Traversable objects can be unpacked into argument lists when calling functions by using the … operator. This is also known as the splat operator in other languages, including Ruby.
  • A right associative ** operator has been added to support exponentiation, along with a **= shorthand assignment operator.
  • use function and use const
    • The use operator has been extended to support importing functions and constants in addition to classes. This is achieved via the use function and use const constructs, respectively.
  • phpdbg – PHP now includes an interactive debugger called phpdbg implemented as a SAPI module.
  • Default character encoding
  • php://input is reusable
  • Files larger than 2 gigabytes in size are now accepted.
  • GMP supports operator overloading
  • hash_equals() for timing attack safe string comparison
  • The __debugInfo() magic method has been added to allow objects to change the properties and values that are shown when the object is output using var_dump().
  • gost-crypto hash algorithm
  • SSL/TLS improvements
  • pgsql async support

For more information check out, http://php.net/manual/en/migration56.new-features.php

PHP 6?

PHP 6 was a false start and development was eventually abandoned in favor of V7.  I never used it but from the sound of it I didn’t miss much.

If for some reason you are using PHP 6, upgrade to 7 ASAP!

PHP 7

As mentioned earlier, PHP 7 is huge step forward.  Type declarations will make code less error prone and the the 2x speed improvement will speed up your site.

New Features

  • Scalar type declarations
    • Scalar type declarations come in two flavours: coercive (default) and strict. The following types for parameters can now be enforced (either coercively or strictly): strings (string), integers (int), floating-point numbers (float), and booleans (bool). They augment the other types introduced in PHP 5: class names, interfaces, array and callable.
  • Return type declarations
  • Null coalescing operator
  • The null coalescing operator (??) has been added as syntactic sugar for the common case of needing to use a ternary in conjunction withisset(). It returns its first operand if it exists and is not NULL; otherwise it returns its second operand.
  • Spaceship operator (<=>)
  • Constant arrays using define()
  • Anonymous classes
  • Closure::call()
  • Filtered unserialize()
  • Expectations
  • Group use declarations
  • Generator Return Expressions
  • Generator delegation
  • Session options
  • preg_replace_callback_array()
  • CSPRNG Functions
  • list() can always unpack objects implementing ArrayAccess

For more information check out, http://php.net/manual/en/migration70.new-features.php

Other useful PHP7 links

Bonus Points

Do you remember what PHP stood for originally?

Headless WordPress (A Primer)

What is headless

There are many great open source software packages out there.  Some of the most popular are WordPress, Drupal and Magento.  It has been gaining popularity in recent years to run these apps as headless.  But what does that mean?

Running headless means to use the admin and data collected in an app but use something else to render the front-end.  For instance you could manage all of your content in the wordpress admin but site that the end user sees is rendered in some other technology all together.

At the end of the day the websites that we visit are all HTML, CSS and JavaScript.  Behind the scenes the story get more complex.  Since all your data has been crafted in wordpress you can pull this content out and render it in your favorite

Who is it for?

So why would I decapitate my WordPress site?

Let me start by who it is not for.  If you are using wordPress and have no problems with how your site currently acts or functions than headless is not for you.

If you run a WordPress site but are having issues with scaling, security, and customizations than it is definitely something you should take a look at.  Keep reading 🙂

 

Why headless WordPress

Advantages
There are many advantages to using an app (CMS) like WordPress headless.  To start it allows you take full control of your front-end.   More importantly it allows you to compose your site using the latest front-end technologies of your choosing.  Love Angular, React or some old Famous animation; then use it in a clean way and don’t be stuck trying to use it in a way that only some random module says it can be used.

Use can use pure bootstrap (or Foundation) [add links]
Easily integrate JavaScript
If you hate PHP you are not stuck with it, you can use Node.js, RoR, Python or any other language and framework you choose.
Improved security (if you use a more secure front-end)
Improved
It is much easier than it sounds
You can more easily mix wordpress content with non-wordpress content
I’ve done demos using both
Potential for a richer UI/UX and faster browsing
SPA, turn your blog into a single page app and impress your friends

[links to other posts]

Disadvantages
Out of the box WordPress has an easy to use user front-end and numerous themes available for free or cheap on the web.  This

You can no longer use all those free wordpress themes
it does take more than casual programming
For a large site that has lots of content and numerous plugins, going headless could be a little time consuming
If are trying to use both wordpress and Drupal 7 (or lower) you have to use one via an API
I did some experiments in 2014 bootstraping both together and there are just too many conflicts.  Things may be different with Drupal 8

Basic headless

How to get headless working

In order to go headless you need to include wp-load.php, which is in the root of your wordpress code.  In my case I have wordpress in a folder wordpress/ which is inside lib/

define(‘WORDPRESS_ROOT’, ROOT.’/lib/wordpress’);

if ( !isset($wp_did_header) ) {

$wp_did_header = true;

require_once( WORDPRESS_ROOT . ’/wp-load.php’ );

}

after that you have WordPress running headless.

now try to pull some data.  For instance try,

$post = get_post(1); // get post is a WP function to pull a single blog post by post id

var_dump($post);

How-to with Erdiko-WordPress

going headless with Erdiko is very simple if you have composer.  In your favorite composer based framework or micro framework (Laravel, Symfony, Erdiko, Slim, etc) simply run

composer require erdiko/wordpress

you’re done.

To test it out create a route in your app and simply instantiate this model.

$wpModel = new /erdiko/wordpress/Model;

// you can call any wordpress api function for instance get_post()
$post = $wpModel->get_post(1);

var_dump($post);

https://github.com/ArroyoLabs/erdiko-wordpress

Multi-site

Multi-site works in a similar fashion, however some additional steps are needed to let WordPress know which site you are on.  Also depending on the use case there is some auto-routing you can do to make things easier.

This will be part of a future post.  It’s not as clean as the going headless on a single site.  If your multi-site is very complex you may struggle a bit running it headless.

Conclusions

Headless is great, but its not for everybody.  Keep in mind, in an enterprise scenario you either need to go headless or harden your out of the box WordPress app.

Next steps
We will post more examples and advanced use case throughout the year.  Please comment and share your thoughts if you would like to see a specific headless example.  Stay tuned!

Talk about API first development

image

It was a pleasure speaking at the WAPRO event by Uncoded earlier this month.  I got to speak about API first architectures and open source mash ups with Erdiko.

API first is a technology paradigm for building apps that is emerging as an excellent way to think about your application and how it grows.  We’ve been a big fan of it for a while now.

The early days of web software (websites) were desktop first.  With the rise of smart phones and tablets it moved to a Mobile First paradigm.  We’re now seeing a shift to API First.

What does that mean?

It means that you are designing your app at the data and interaction level first.  This will inform your mobile UI, desktop UI, and public/partner APIs.

We will write more on this topic in posts to come.   Till then, download the slides from my talk in Long Beach, CA.

http://arroyolabs.com/downloads/talks/WAPRO-Talk.pdf

Tutorial: Doctrine DBAL (PHP Database Abstraction Layer)

This tutorial will show you how to connect a database using Doctrine DBAL.  The examples are for Erdiko, but could be applied to any PHP framework that uses composer.

Installation

If you have not installed Erdiko, please go to http://erdiko.org/getStarted.html#installation

To install Erdiko via Composer. simply run

composer create-project erdiko/erdiko my-project-name

After you have installed Erdiko (or your other favorite framework), it is very easy to install Doctrine.

via composer:

composer require doctrine/dbal 2.3.*

Alternatively, you can do it by hand by modifying the composer.json file in the root folder.  You just need to add this line:

{“require”: {“doctrine/dbal”: “2.3.4”}}

Then run ‘composer update’ to install Doctrine DBAL.

Basic usage

1. Getting a connection

We can get a connection through the DoctrineDBALDriverManager class.

$connectionParams = array(
    ‘dbname’ => ‘database_name’,
    ‘user’ => ‘user_name’,
    ‘password’ => ‘user_password’,
    ‘host’ => ‘localhost’,
    ‘driver’ => ‘pdo_mysql’
);
$conn = DoctrineDBALDriverManager::getConnection($connectionParams, $config);

Now, you are ready to retrieve and manipulate data.

2. Data Retrieval And Manipulation

After you have established a connection with database, it is easy to manipulation data.

In this tutorial, we create a table “Products" and create three fields for it.

The three fields are Name, Qty, and Price.

Inserting Data

$sql = “INSERT INTO Products (Name, Qty, Price) VALUES (‘Mango’, ’10’,5)”;
$stmt = $conn->query($sql);

Retrieving Data

$sql = “SELECT * FROM Products”;

$stmt = $conn->query($sql);

while ($row = $stmt->fetch()) {

    echo $row[‘Name’].’, Qty: ’.$row[‘Qty’].’, Price: ’.$row[‘Price’];

}

The output should be “Mango, Qty:10, Price:5”.

Advanced usage:

To perform fancy data manipulation or query, we will need to set up the class loader before establishing a connection.

Setting up class loader

We can open the Example controller(Example.php) under Erdiko/app/controllers/.

In the Example controller, we will need to add the following line before the class scope and it will allow the program to access the class ClassLoader.

use DoctrineCommonClassLoader;

Then, we can add the following code to a page.

$classLoader = new ClassLoader(‘Doctrine’);

$classLoader->register();

$config = new DoctrineDBALConfiguration();

Note: 

It is not a good practice to set connection parameters every time we get a connection with database.  A better way to do it would be storing all these parameters to a config file and creating a data model to read the config file.

For example, we can create a db.json config file under Erdiko/app/config/local/

In the db.json, we can set the connection parameters.

{

      “data":{       

          “dbname": ‘database_name’,

          “user": ‘user_name’,

          “password": ‘user_password’,

          “host": ‘localhost’,

          “driver": ‘pdo_mysql’

     }

}

Then, we can create a data model and it should looking something like below.

public function getDbConfig($dbConfig)

{

     $config = Erdiko::getConfig(“local/db”);

     $connectionParams = array(

         ‘dbname’ => $config[“data"][“dbname”],

         ‘user’ =>  $config[“data"][“user”],

         ‘password’ =>  $config[“data"][“password”],

         ‘host’ =>  $config[“data"][“host”],

         ‘driver’ =>  $config[“data"][“driver”],

     );

     return $connectionParams;

}

The getDbConfig function will make the program easy to maintain and also reduce the amount of code.

Now, getting a connection will be only required the following line:

$conn = DoctrineDBALDriverManager::getConnection($connectionParams, getDbConfig(‘data’));composer create-project erdiko/erdiko project-name