Debugging PHP SOAP over SSL using Charles

I'm currently integrating against a SOAP server using PHP which wasn't working as I expected, so I wanted to find out what was happening over the wire. I have Charles installed and use it regularly with OS X's system-wide proxy settings. However, PHP's SoapClient doesn't use these, so I had to work out how to do it manually.

Enabling SoapClient to send via a proxy is really easy and is documented by Lorna Mitchell in Using Charles To Debug PHP SOAP:

$options = [
    "cache_wsdl" => WSDL_CACHE_NONE,
    "soap_version" => SOAP_1_1,
    "trace" => 1,
    "proxy_host" => "localhost",
    "proxy_port" => 8888,
];

$client = new \SoapClient($wsdl, $options);

I did this and saw traffic in Charles. However, my service endpoint is SSL and I saw this error:

PHP Fatal error:  SOAP-ERROR: Parsing WSDL: Couldn't load from 'https://example.com/Service.svc?singleWsdl' : failed to load external entity "https://example.com/Service.svc?singleWsdl" in SoapServiceProcessor.php on line 167

Looking in Charles, I saw the note:

You may need to configure your browser or application to trust the Charles Root Certificate. See SSL Proxying in the Help menu.

Aha!

Again, we turn back to Lorna for how to do sort this out. This time, we need Manipulating HTTP with Charles Proxy, that she wrote for TechPortal. Unhelpfully, that website doesn't use section links, so scroll all way down to the Charles and SSL section to find out the relevant information about how to set up Charles for SSL proxying.

On OS X, you simply do:

  • Help -> SSL Proxying -> Install Charles Root Certificate
  • Proxy -> SSL Proxying Settings:
    • Check Enable SSL Proxying
    • Add the endpoint's domain to the list of locations

Finally, I needed to tell SoapClient to trust Charles' root certificate so that it can decrypt the SSL traffic.

This is done by downloading the Charles root certificate (Help -> SSL Proxying -> Save Charles Root Certificate) and storing it somewhere. I chose to put it in /usr/local/etc/charles-ssl-proxying-certificate.crt.

Finally, configure a new stream_context that knows about this certificate and add it to the SoapClient:

$options = [
    "cache_wsdl" => WSDL_CACHE_NONE,
    "soap_version" => SOAP_1_1,
    "trace" => 1,
    "proxy_host" => "localhost",
    "proxy_port" => 8888,
    "stream_context" => stream_context_create([
        'ssl' => [
            'cafile' => '/usr/local/etc/charles-ssl-proxying-certificate.crt'
        ]
    ];
];

$client = new \SoapClient($wsdl, $options);

Now everything works and I can see the actual data that's being sent to the SSL SOAP service and I solved my problem!

First beta of Slim Framework 3

Last night, I tagged beta 1 of Slim Framework 3! This is a significant upgrade to v2 with a number of changes that you can read on the Slim blog.

For me, the two key features that I'm most excited about are:

  • PSR-7 support, along with the standard middleware signature of:
        function($request, $response, $next) { return $response; }
  • Dependency injection container with container-interop compliance. We ship with Pimple by default, but I'm planning to use Zend\ServiceManager.

There's lots of other changes and we believe we have kept to the key tenants of Slim, keeping it focussed as a micro-framework suitable for building any application that you want to build. Slim is a particularly good choice our new Composer-based world where you can pick the best of breed components to build your application.

Testing

The easiest way to get going with a Slim 3 application is to use my skeleton application:

$ composer create-project -n -s dev akrabat/slim3-skeleton my-app
$ cd my-app
$ php -S 0.0.0.0:8888 -t public public/index.php

and browse to http://localhost:8888. I wrote up some more about my skeleton application previously.

Alternatively, the README file has information on starting from scratch.

This is a Beta!

Obviously, this is beta release – we are sure there are bugs and issues to be improved. We really want you to test it and kick the tyres. Please report any issues you find to us. We also appreciate pull requests!

You can also find helpful people on IRC in the #slimphp channel on Freenode.

Also not that while we hope that we won't need to change any function signatures, we aren't promising that we'll keep BC before 3.0 stable.

Docs

The new docs are very much a work in progress! They are incomplete and out of date in places. Again, please report any issues and pull requests are very welcome!

Next steps

We shall be concentrating on documentation and ensuring that Slim 3 is as stable as we can make it. This is an exciting time and I'm looking forward to when Slim 3.0 final is released.

Selecting the service port with PHP's SoapClient

I'm currently integrating with a SOAP service which has two different services defined.

The relevant part of the WSDL is:

<wsdl:service name="Config">
    <wsdl:port name="BasicHttpBinding_IConfiguration" binding="tns:BasicHttpBinding_IConfiguration">
        <soap:address location="http://nonsecure.example.com/Configuration.svc"/>
    </wsdl:port>
    <wsdl:port name="BasicHttpsBinding_IConfiguration" binding="tns:BasicHttpsBinding_IConfiguration">
        <soap:address location="https://secure.example.com/Configuration.svc"/>
    </wsdl:port>
</wsdl:service>

I discovered that PHP's SoapClient will select the first port it encounters and doesn't provide a way to select another one. This was a nuisance as I wanted to use the SSL one.

Through research, I discovered that I can use __setLocation():

$client->__setLocation('https://secure.example.com/Configuration.svc');

However, I don't control that endpoint, so I would rather select based on the port's name.

As I couldn't find a way to get the data from SoapClient, I decided to parse the WSDL myself and pull the information out. I don't do a lot with XML namespaces, so had to look up how to handle them and then how to extract the right data using XPath.

As I had to look it up, I'm putting it here, so I can find it again more easily!

I converted my new found knowledge into a method to extract the location attribute from the <soap:address> element of the <wsdl:port> with the correct name element:

function getLocationForPort($wsdl, $portName)
{
    $file = file_get_contents($wsdl);

    $xml = new SimpleXmlElement($file);

    $query = "wsdl:service/wsdl:port[@name='$portName']/soap:address";
    $address = $xml->xpath($query);
    if (!empty($address)) {
        $location = (string)$address[0]['location'];
        return $location;
    }

    return false;
}

Xpath is ideal for this job!

Usage is simply:

$client = new SoapClient($wsdl);
$sslLocation = getLocationForPort($wsdl, 'BasicHttpsBinding_IConfiguration');
if ($sslLocation) {
    $client->__setLocation($location);
}
// work with $client as normal

Now, all my calls to the SOAP service are via SSL as they should be!

Accessing services in Slim 3

One of the changes between Slim Framework 2 and 3 is that the application singleton has gone.

In Slim 2, you could do this:

$app = \Slim\Slim::getInstance();
// do something with $app

In general, you didn't need access to $app itself, but rather you wanted access to something that the app knows about, such as a database adapter, or the router for access to the urlFor method to create a URL to a route.

With Slim 3, there is no getInstance() on App, so you need to inject the instances of whatever you need where ever you need them.

Setup the container

Let's start by setting up the container with a fictional mapper:

// create container and configure it
$settings = require 'settings.php';
$container = new \Slim\Container();

$container['pdo'] = function ($container) {
    $cfg = $container->get('settings')['db'];
    return new \PDO($cfg['dsn'], $cfg['user'], $cfg['password']);
};

$container['books'] = function ($container) {
    return new BookMapper($container->get('pdo'));
};

// create app instance
$app = new \Slim\App($container);

This is standard Slim 3 initialisation code, to which we have added a DI entry called books which depends on a PDO instance, so we have also registered that to allow the container to create the BookMapper when we ask for it.

How would we get at books within our application?

Route callables

Let's start by looking at the two common ways to write a route callable.

A route callable closure:

If you use a closure, then Slim binds the application instance to $this.

$app->get('/', function($request, $response, $args) {
    $books = $this->getContainer()->get('books');
    // do something with $books and then return a response
};

There's also a shortcut you can use as App implements __get which proxies to the container object's get method:

$app->get('/', function($request, $response, $args) {
    $books = $this->books; // retrieve from the container
    // do something with $books and then return a response
};

A route callable class:

If you use a class method for a route callable like this:

$app->get('/', 'HomeAction:dispatch');

Slim will look for a DI key of HomeAction, use the DI container to instantiate the class and then dispatch by calling the dispatch() method.

Hence, you should use the DI container to inject what you need into the class constructor:

class HomeAction {
    public function __construct($books)
    {
        $this->books = $books;
    }

    public function dispatch($request, $response, $args)
    {
        $books = $this->books;
        // do something with $books and then return a response
    }
}

We now need to register the class with the container:

// in index.php:
$container['HomeAction'] = function ($container) {
    return new HomeAction($container->get('books'));
};

The registered route will now work and have access to the BookMapper.

All of Slim's services are in the container, so where I've used books in this example, you can access anything that Slim has registered, such as settings or router and in addition to what you have registered yourself.

Middleware

The same thing pattern works with both app and route middleware.

Middleware closure

If you use a closure in middleware, then the container is bound to $this:

$app->add(function ($request, $response, $next) {
    $settings = $this->get('settings');
    // do something with $settings
    return $next($request, $response);
});

Middleware class

You can also use a class which works exactly as it does for a route:

$app->add('App\Middleware\AppMiddleware:run');

Slim will look for a DI key of App\Middleware\AppMiddleware, use the DI container to instantiate it and then call the run() method.

As before, inject your dependencies via the class constructor:

namespace App\Middleware;

class AppMiddleware
{
    public function __construct($settings)
    {
        $this->settings = $settings;
    }

    public function run($request, $response, $next)
    {
        $settings = $this->settings;
        // do something with $settings
        return $next($request, $response, $next);
    }
}

and register with the container:

$container['App\Middleware\AppMiddleware'] = function ($container) {
    return new App\Middleware\AppMiddleware($container->get('settings'));
};

I've found this pattern to be nicely consistent and easy to remember.

To sum up

Slim 3 encourages you to think a little more carefully about which dependencies you need for any given middleware or action. Due to closure binding and the built-in DI container, it's easy to access the classes you need, when you need them.

Testing my ZF1 app on PHP7

Zend Framework 1 is still actively maintained and we fully intend to ensure that ZF1 works with no problems on PHP 7 when its released.

Now that PHP 7.0.0 Alpha 1 has been released, it's time to find out if your Zend Framework 1 app works with it. The easiest way to do this is to use a virtual machine. My preference is Vagrant with Rasmus' PHP7dev box.

A simple VM

I wanted to test a client's ZF1 application with PHP 7, so I created this drop-dead simple Vagrantfile to will boot up a virtual machine running PHP7:

# -*- mode: ruby -*-
# vi: set ft=ruby :

VAGRANTFILE_API_VERSION = '2'

# Inline provisioning shell script
@script = <<SCRIPT

# Set up variables
DB_NAME=my_db_name
MYSQL_DUMP_FILE=/vagrant/docs/my_db_dump_file.sql

# Switch to PHP7
newphp 7

# rebuild PHP7
makephp 7


# Configure nginx to point at our public/ directory and set APPLICATION_ENV to php7dev
echo '
server {
    listen       80;
    server_name  localhost;
    root         /vagrant/public;
    index        index.php index.html index.htm;
    access_log   /var/log/nginx/default-access.log  main;
    error_log    /var/log/nginx/default-error.log;

    location / {
        try_files $uri $uri/ @rewrite;
    }
    location @rewrite {
        index index.php;
        rewrite ^(.*)$ /index.php;
    }

    location ~ \.php {
        include                  fastcgi_params;
        fastcgi_keep_conn        on;
        fastcgi_index            index.php;
        fastcgi_split_path_info  ^(.+\.php)(/.+)$;
        fastcgi_param            PATH_INFO $fastcgi_path_info;
        fastcgi_param            SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param            APPLICATION_ENV php7dev;
        fastcgi_intercept_errors on;
        fastcgi_pass             unix:/var/run/php-fpm.sock;

    }
}

' > /etc/nginx/conf.d/default.conf
service nginx restart

cd /vagrant

# Do we need to install and run composer?
if [ -e composer.json ]
then
  curl -Ss https://getcomposer.org/installer | php
  php composer.phar install --no-progress
fi

# Do we need to create a MySQL database?
if [ -e $MYSQL_DUMP_FILE ]
then
    mysql -uvagrant -pvagrant -e "DROP DATABASE IF EXISTS $DB_NAME";
    mysql -uvagrant -pvagrant -e "CREATE DATABASE $DB_NAME";
    mysql -u vagrant -pvagrant $DB_NAME < $MYSQL_DUMP_FILE
fi

echo "** Visit http://localhost:8888 in your browser for to view the application **"
SCRIPT


# Vagrant configuration
Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
  config.vm.box = 'rasmus/php7dev'
  config.vm.network :forwarded_port, guest: 80, host: 8888
  config.vm.hostname = "zf1app.local"
  
  config.vm.provision 'shell', inline: @script

  config.vm.provider "virtualbox" do |vb|
    vb.customize ["modifyvm", :id, "--memory", "1024"]
  end

end

The nice thing about creating the provisioning script within the Vagrantfile itself is that we now have a one file solution, but it's probably not the best solution for more complex set ups!

It's slow to start because it re-compiles PHP 7 via the makephp 7 command. Note that the MySQL username and password is vagrant, so I set APPLICATION_ENV to php7dev, so that I can set the correct configuration in application.ini.

What I found

You must read the UPGRADING file as it tells you all the BC breaks. There's a lot of nice tidy-ups and consistency improvements, which fortunately, haven't affected us.

As we've been working on ensuring ZF1 works with PHP7, my client's website worked with just one issue:

"Deprecated: Methods with the same name as their class will not be constructors in a future version of PHP;"

It turned out that we had an old version of the PHP Markdown library. So I upgraded it and this issue was sorted.

In summary

I've explored using Rasmus' box before for unit testing and playing with extensions, but it also turned out that it's the ideal starting point for running my web applications under PHP7 too! I was pleased to discover that so far, I've found nothing broken on my ZF1 applications.

Brent Simmons: How Not to Crash #9: Mindset

Brent Simmons has recently posted How Not to Crash #9: Mindset:

I used to think that means I should write code that’s about 80% as clever as I am. Save a little bit for debugging.

But over the years I’ve come to think that I should write code that’s about 10% as clever as I am. And I’ve come to believe that true cleverness is in making code so clear and obvious that it looks like nothing at all.

I'm on the same journey. I used to be proud that I could solve a problem in fewer lines of code. Now I'm proud of simple code. I'm still learning though and there are plenty of cases where my code doesn't live up to my ideals.

Because its too clever.

20 years of PHP

Today marks 20 years since PHP was released by Rasmus Lerdorf and Ben has been asking for how we started our PHP journey.

My first use of PHP was to write a website for an online computer gaming guild for EverQuest, back in 1999. A friend recommended it when I asked him how people programmed webpages in something other the C! That first website is still going and I'm not proud of the code. I'm very proud that it's still going strong and running on PHP 5.6 and has had some very minor updates for PHP version changes:

Oh yeah – I also fixed the SQL inject and XSS vulnerabilities!

That's quite a short list to make a PHP 3 application run on PHP 5.6! Of course, it's not object oriented, so I bypassed the upgrade pain there and it doesn't follow the latest best practices.

That PHP website also led to my first job in the web industry as I was headhunted from my job programming Windows applications. My first commercial website was an internal business application for sales tracking in an Internet hosting company. I've mostly staying in internal business applications and B2B apps ever since!

Of course, the way I write in PHP has changed considerably over the years. My first application was HTML pages with PHP where I needed it. I developed a library of procedural functions and moved most of my PHP code into .inc files. My first framework was Fusebox 4, which I first used in 2005. It was a procedural framework, but was a genuine Front Controller and encouraged separation of concerns. When I was ready to replace it with an OOP framework, Zend Framework had been announced and I jumped onto it…

PHP was built from day one for the web and, for me, it's still the best tool for the job!

My Xdebug configuration

With the release of Xdebug 2.3, I have updated my xdebug php.ini settings, so it seems sensible to write them down where I won't lose them!

The new-for-2.3 features which prompted this are xdebug.overload_var_dump, which Derick has written about and xdebug.halt_level which I have previously written about. I find both of these very useful.

This is my current php.ini configuration:

; Xdebug settings

; var_dump() displays everything, including filename and line number
xdebug.overload_var_dump        = 2
xdebug.var_display_max_children = -1
xdebug.var_display_max_data     = -1
xdebug.var_display_max_depth    = -1

; don't supress errors
xdebug.scream = 1

; stop if there's a warning/notice
xdebug.halt_level = E_WARNING|E_NOTICE|E_USER_WARNING|E_USER_NOTICE

; remote debugging
xdebug.remote_enable       = 1
xdebug.remote_connect_back = 1
xdebug.remote_port         = 9000

; profiling is triggered via browser extension
xdebug.profiler_enable         = 0
xdebug.profiler_enable_trigger = 1

For every other setting, I've found that the default is fine.

I control html_errors within my app so that it's set to 1 when the app is rendering HTML, and 0 otherwise, such as with CLI applications.

Turn warnings into exceptions

As I keep looking this up in other projects that I've written, I'm putting it here so I can find it more easily.

There are a number of built-in PHP functions that generate a notice or warning that you can't turn off when something goes wrong, such as parse_ini_file and file_get_contents.

One common solution to this is to suppress using the @ operator:

$result = @file_get_contents($url);
if (false === $result) {
    // inspect error_get_last() to find out what went wrong
}

This doesn't work when using Xdebug with the xdebug.scream set to 1 and its also inelegant and inefficient..

A better way is to use set_error_handler:

set_error_handler(function ($severity, $message, $file, $line) {
    throw new \ErrorException($message, $severity, $severity, $file, $line);
});

$result = file_get_contents($url);

restore_error_handler();

In this case, we register our own error handler that converts every notice, warning and error into an ErrorException that can then be caught elsewhere. We then call the PHP function of interest and immediately call restore_error_handler to put back the one we had earlier.

Interestingly, in PHP7, we can expect to see exceptions in the engine itself which should allow us to solve this problem like this:

try {
    $result = file_get_contents($url);
} catch (EngineException $e) {
    // do something with $e
}

A Slim3 Skeleton

Warning Slim 3 is currently under active development. Expect BC breaks!

I'm creating a number of projects in Slim 3 (which is currently under development) at the moment in order test things out and found that I was setting them up in essentially the same way. To save me having to do this each time, I've now created a skeleton project that is set up with the directory structure that I like and also includes Twig and Monolog.

To create a new Slim 3 project, simply do this:

$ composer create-project -n -s dev akrabat/slim3-skeleton my-app

This will create a new folder called my-app with the project files in it and then install the composer dependencies. You now have a working skeleton application, so test it using the built-in PHP web server:

$ cd my-app
$ php -S 0.0.0.0:8888 -t public public/index.php

Browse to http://localhost:8888 and you should see this:

Slim3 skeleton screenshot

What's included?

When exploring the application, these are the key files to look at.

  • index.php instantiates the Slim application object, sets the application up using files in app/ and runs it.
  • app/dependencies.php contains all the dependencies that are registered with Pimple.
  • app/middleware.php is where you should register any application middleware that you want to use. It's empty in the skeleton.
  • app/routes.php contains all the routes that the application responds to. I like having them all in one place and to keep the file sensible, I use the DIC to grab the action for dispatch.
  • app/src/Action/HomeAction.php is the class that is loaded by the DIC and then the dispatch method is executed. The nice thing about having a class like this is that I can load the dependencies via the constructor. Look in dependencies.php for the factory for this class.
  • app/templates/home.twig is the Twig view script that is rendered.

That's it

From this point on, you should delete what you don't want and add what you do in order to write your application!