Category: PHP

Using Composer with shared hosting

I can't use Composer because I'm using shared hosting and don't have SSH

I've seen this sentiment a few times now, so this seems like a good time to point out that you do not need SSH access to your server in order to use Composer. In fact, I don't run Composer on a live server (regardless of whether it's using shared hosting) and it's not on my list of things to do in the near future.

What you do need is a process where you handle your Composer dependencies on your own computer where you have PHP running.

In my view, you have two choices: commit your Composer dependencies directly to your project or write a build script that runs Composer for you and uploads the resulting files.

In either case, you need to install Composer globally, so follow the instructions relevant to your operating system.

Let's look at the process for both options, starting with committing your Composer dependencies.

Commit Composer dependencies

The easiest way to handle Composer dependencies is to run Composer locally and commit the vendor directory into your repository.

Write your website, using Composer, as usual and commit composer.json, composer.lock and all the files in vendor.

Note the following:

  1. Ensure that your .gitignore file does not exclude vendor. This is very common when starting from a skeleton project or using a tool like artisan to create your project.
  2. Ensure that you only use packages that have a release number. That is never use dev-master in your composer.json as if you do, Composer will install it via git and you won't be able to add it to your own repository. There are good reasons for avoiding dev-master dependencies anyway.

Your git repository now has all the files needed to run the website directly within it and so you can now simply upload your website to your shared host as you usually do.

Use a build script

If you don't want to commit the dependencies to your git repository, another solution is to write a script that you run locally that downloads the dependencies and thenuploads the files to your host.

The process looks like this:

  1. Check's out your source code to a clean directory
  2. Runs composer install
  3. Removes all .git directories and any another files and directories that shouldn't be on your live site
  4. Uploads all the remaining files to your shared host. (if your host uses FTP, then use ncftpput for this as it supports recursion)
  5. Deletes the directory

Note that in this situation, you need to ensure that the vendor directory is excluded in your .gitignore file and that composer.lock is committed to git.

Run the script every time you need to put new code onto your live site.

Summary

As you can see, using Composer to manage the dependencies of your PHP project has nothing to do with your final choice of hosting for your live site. You should always have the ability to run your PHP website on your local computer and so you can deal with Composer there and it's simply a case of transferring the right files to live.

In general, I'm a big fan of scripting things that are done by hand, so recommend using a build script, even if you choose to commit your dependencies to your own repository.

Running Phan against Slim 3

Having installed Phan, I decided to use it against the upcoming Slim 3 codebase.

Phan needs a list of files to scan, and the place I started was with Lorna's article on Generating a file list for Phan.

I started by removing all the developer dependencies:

and then built the file list for the vendor and Slim directories. I started by using Lorna's grep statement, but that found too many non-PHP files in vendor, so I ended up with:

I then reorganised the list to put interfaces and traits at the top as order matters & then ran Phan:

A lot of issues have been found – most of them due to missing dependent classes & interfaces, so I ignored those when working through the list. Next time, I'll add the relevant vendor files to see if that catches anything else.

The remaining issues found were all type errors related to the docblock saying one thing and the code doing another. These will need tidying up.

It was an interesting exercise and I encourage you to run Phan or a similar tool over your own codebase.

Installing Phan on OS X

I use Homebrew for my local PHP installation on OS X and am currently running PHP 7.0.0 RC8.

Phan is a static analyser for PHP 7 which was written by Rasmus and then rewritten by Andrew Morrison. As it benefits from PHP 7's abstract syntax tree it can find all kinds of subtle errors, so I wanted to install it locally to have a play with it.

I started by trying to install Phan into my global composer install so that it's available on my path. As it's not released on Packagist, I edited ~/.composer/composer.json and added:

to the top, so the I could then install via the standard composer method:

This immediately failed as I don't have the Nikita's ast extension installed:

To install this extension:

Now edit you php.ini file (/usr/local/etc/php/7.0/php.ini for Homebrew installations) and add extension=ast.so at the bottom.

Having installed the ast PHP 7 extension, Phan will now install:

Now, Phan works from my command line!

Writing PSR-7 middleware

Within Slim 3's Request object, there's a method called getIp() which is determines the client's IP address. However it's rather simplistic and potentially risky as it checks the X-Forwarded-For header with no ability to ignore this header or whitelist whether we trust the final proxy in the chain.

Determining the client's IP address is an ideal use-case for middleware as we can inspect the headers in the request and then set an attribute so that middleware further down the chain can use it. Following my rather unimaginative naming, I've called it rka-ip-address-middleware.

However, in this article, I want to look at how easy it is to write useful PSR-7 middleware.

Minimal valid middleware

Writing middleware is really easy, so lets look at the basics of how I built this. You simply need to provide a callable that has this function signature:

We are given a request and response object along with the next middleware in the chain and must return a response. Our middleware function must also be a callable itself and this is easy to do with a class by using the __invoke() magic method.

A minimal class that acts as PSR-7 middleware therefore looks something like this:

This middleware doesn't actually do anything by itself, but does do the minimum required:

  1. Call the $next middleware in the chain
  2. Return a $response object

Doing something interesting

For a piece of middleware to be useful, it has to do something. Generally, this means that we should look at the $request or $response objects that we have received and do something with them. For this example, we need to look at the request's headers to determine the client's IP address and then store it back into the request for use by subsequent middleware.

Obviously, if there is no subsequent middleware to call, then we don't need to do this work anyway as there's nobody to use it, so our code becomes:

(The implementation details of determineClientIpAddress are irrelevant for this discussion.)

We have to store the $ipAddress back into the $request object. The way to do this is to use the server attributes which exists to provide messaging between the middleware in the chain.

We'll call our new attribute "ip_address" and as PSR-7 messages are immutable, we use the withAttribute() method to create a new Request object:

So our middleware handler is complete:

Configuring middleware

One nice thing about using a class for your middleware is that it's easy to configure. Let's say that we want the user to be able to pick the name of the attribute to store the IP address into. We can do this quite easily by introducing a property and a constructor:

Adding middleware to your application

There are a number of PSR-7 middleware-aware frameworks, that have different method names for adding middleware:

  • Slim 3: $app->add(new RKA\Middleware\IpAddress('client_ip'));
  • Radar: $adr->middle(new RKA\Middleware\IpAddress('client_ip'));
  • Expressive: $app->pipe(new RKA\Middleware\IpAddress('client_ip'));

To sum up

Middleware is a powerful way to inspect and act upon HTTP messages in your application. The PSR-7 standard is feature rich enough that with the attributes in ServerRequestInterface it provides a way to add additional information that can be used by subsequent middleware which is very useful and allows for a lot of flexibility in building your applications.

Render an array based on accept header

I'm currently working on an API using Slim 3 and needed a generic way to render arrays to XML, JSON or HTML based on the Request's Accept header.

This is just good practice. The Accept header is used by a client to specify the media types that it accepts. Therefore if our client would like XML, I'd like to give it XML. Similarly for JSON. I also like to support an HTML rendering on my API if I can as it makes exploration much easier.

This seemed like an ideal thing for a component and so I wrote rka-content-type-renderer! (One day I'll work out how to name things, but for now, if it starts with rka, then it's probably a reusable component!)

It's PSR-7 compliant because if you're going to write something that deals with HTTP nowadays, PSR-7 is the only sensible interface to target. Therefore, this component renders to a PSR-7's Response object's body.

Usage is really simple:

The $request and $response objects must implement PSR-7's RequestInterface and ResponseInterface respectively. This makes it very easy to use within say Radar, Expressive, Slim or any other system that can bridge to PSR-7.

In this case, the output for JSON is:

& for XML:

Finally, it will also render the array as an HTML unsigned list if the content-type is text/html which makes examining an API using a web browser very easy and worth doing:

Obviously, in the HTML, we link any links so that the user can explore the API data, simply by clicking.

Hal support

While doing this, I also added support for rendering Nocarrier/Hal objects too as the HAL specification supports both JSON and XML, so it seems logical to send the correct format back to the client based on what they've asked for.

All in all, I've found this to be a useful component and if you have a similar need, then maybe this will help.

The beginner's guide to rebasing your PR

You've successfully created a PR and it's in the queue to be merged. A maintainer looks at the code and asks you to rebase your PR so that they can merge it.

Say what?

The maintainer means that there have been other code changes on the project since you branched which means that your branch cannot be merged without conflicts and they would like to you to sort this out.

These are the steps you should take.

TL;DR

Read the summary.

1. Update your target branch from upstream

I assume you already have an upstream repository as described in The beginner's guide to contributing to a GitHub project. The target branch you want to update can be found at the top of the PR on the GitHub site.

For example:

Pr title

The target branch in this example is develop, though I see master a lot too.

2. Rebase your branch

The next step is to change to your branch which is the other branch listed in the PR details (feature/validator-result-interface in this example) and then perform a rebase:

This will rewind all your commits on this branch and then replay them against the tip of the branch you are rebasing against.

As you have been asked to do this, you'll get conflicts. Don't panic!

$ git status will show you which files are in conflict. For each one, follow this process:

  1. Open in editor and search for "<<<<<<" (that's 6 <) to find the conflict
  2. Inspect and fix so that you end up with the correct text. Remove the lines starting with <<<<<<, ====== and >>>>>>.
  3. Press find-next in your editor to find the next conflict in the file.
  4. Once all conflicts in the file have been fixed, exit your editor
  5. Add this file to the staging index: git add {filename}
  6. Repeat until git status shows that all conflicting files have been added to the index

Once all conflicting files are fixed you can continue the rebase:

3. Push your newly rebased branch to origin

Finally, all you need to do is push your branch back to origin. Note that this will require a force push and you've probably been told to never do such a thing. This is the one exception to that rule because the maintainer asked you to do it.

So go ahead:

It's a good idea to leave a comment on the PR that you've done the rebase and the PR is ready for re-review.

All done

To summarise the steps required:

  1. $ git checkout {target branch}
  2. $ git pull upstream {target branch} && git push origin {target branch}
  3. $ git checkout {victim branch}
  4. $ git rebase {target branch}
  5. Fix conficts and continue rebasing
  6. $ git push -f origin {victim branch}

That's it. Being asked to rebase your PR isn't scary or (usually) difficult as long as you pay attention to what you're doing. However, if you're not fully comfortable with git, then I recommend buying the Git Workbook and working through all the exercises.

The beginner's guide to contributing to a GitHub project

This is a guide to contributing to an open source project that uses GitHub. It's mostly based on how I've seen Zend Framework, Slim Framework and joind.in operate. However, this is a general guide so check your project's README for specifics.

TL;DR

Skip to the summary.

Step 1: Set up a working copy on your computer

Firstly you need a local fork of the the project, so go ahead and press the "fork" button in GitHub. This will create a copy of the repository in your own GitHub account and you'll see a note that it's been forked underneath the project name:

Forked

Now you need a copy locally, so find the "SSH clone URL" in the right hand column and use that to clone locally using a terminal:

Which will do something like this:

Clone

Change into the new project's directory:

Finally, in this stage, you need to set up a new remote that points to the original project so that you can grab any changes and bring them into your local copy. Firstly clock on the link to the original repository – it's labeled "Forked from" at the top of the GitHub page. This takes you back to the projects main GitHub page, so you can find the "SSH clone URL" and use it to create the new remote, which we'll call upstream.

You now have two remotes for this project on disk:

  1. origin which points to your GitHub fork of the project. You can read and write to this remote.
  2. upstream which points to the main project's GitHub repository. You can only read from this remote.

Step 2: Do some work

This is the fun bit where you get to contribute to the project. It's usually best to start by fixing a bug that is either annoying you or you've found on the project's issue tracker. If you're looking for a place to start, a lot of projects use the "easy pick" label (or some variation) to indicate that this issue can be addressed by someone new to the project.

Branch!

The number one rule is to put each piece of work on its own branch. If the project is using git-flow, then it will have both a master and a develop branch. The general rule is that if you are bug fixing, then branch from master and if you are adding a new feature then branch from develop. If the project only has a master branch, the branch from that. Some projects, like Slim use branches named after the version number (2.x and 3.x in Slim's case). In this case, pick the branch that's relevant.

For this example, we'll assume we're fixing a bug in zend-validator, so we branch from master:

Firstly we ensure we're on the master branch. Then the git pull command will sync our local copy with the upstream project and the git push syncs it to our forked GitHub project. Finally we create our new branch. You can name your branch whatever you like, but it helps for it to be meaningful. Including the issue number is usually helpful. If the project uses git-flow as zend-validator does, then there are specific naming conventions where the branch is prefixed with "hotfix/" or "feature/".

Now you can do your work.

Ensure that you only fix the thing you're working on. Do not be tempted to fix some other things that you see along the way as your PR will probably be rejected. Make sure that you commit in logical blocks. Each commit message should be sane. Read Tim Pope's A Note About Git Commit Messages.

Step 3: Create the PR

To create a PR you need to push your branch to the origin remote and then press some buttons on GitHub.

To push a new branch:

This will create the branch on your GitHub project. The -u flag links this branch with the remote one, so that in the future, you can simply type git push origin.

Swap back to the browser and navigate to your fork of the project (https://github.com/akrabat/zend-validator in my case) and you'll see that your new branch is listed at the top with a handy "Compare & pull request" button:

Pr button

Go ahead and press the button!

If you see a yellow box like this:

Contributing

Click the link which will take you to the project's CONTRIBUTING file and read it! It contains valuable information on how to work with the project's code base and will help you get your contribution accepted.

On this page, ensure that the "base fork" points to the correct repository and branch. Then ensure that you provide a good, succinct title for your pull request and explain why you have created it in the description box. Add any relevant issue numbers if you have them.

Create pr

If you scroll down a bit, you'll see a diff of your changes. Double check that it contains what you expect.

Once you are happy, press the "Create pull request" button and you're done.

Step 4: Review by the maintainers

For your work to be integrated into the project, the maintainers will review your work and either request changes or merge it.

Lorna Mitchell's article Code Reviews: Before You Even Run The Code covers the things that the maintainers will look for, so read it and ensure you've made their lives as easy as possible.

To sum up

That's all there is to it. The fundamentals are:

  1. Fork the project & clone locally.
  2. Create an upstream remote and sync your local copy before you branch.
  3. Branch for each separate piece of work.
  4. Do the work, write good commit messages, and read the CONTRIBUTING file if there is one.
  5. Push to your origin repository.
  6. Create a new PR in GitHub.
  7. Respond to any code review feedback.

If you want to contribute to an open source project, consider joind.in!

Simple Ansible file for Z-Ray preview

Recently, Zend made available a Z-Ray Technology Preview which takes the Z-Ray feature of Zend Server and makes it stand-alone.

This is very interesting as it means that I can run it with the PHP 5.6 on Ubuntu 14.04 LTS Vagrant set up that I prefer. I decided to create an Ansible playbook to install Z-Ray into my VM. The Z-Ray instructions are clear enough, so it was simply a case of converting them to a set of YAML steps as who wants to do manual installation nowadays?!

This is what I came up with:

I've set this up for PHP 5.6 which is what I'm using nowadays. If you're using 5.5, then you need to download zray-php5.5-Ubuntu-14.04-x86_64.tar.gz and the link needs to be to /usr/lib/php5/20121212/zray.so.

Changing the file ownership to vagrant was important – I couldn't get it work without doing this step and I have no idea why its needed…

The standalone Z-Ray looks to be very similar to the one supplied as part of Zend Server and is equally as helpful in terms of getting a grip on what's going on with your application when developing it.

It has improved since I wrote about before and is even more useful now as it's been improved and has plugins!

With the standalone version of Z-Ray, there's really no excuse to not be using it.

Improved error handling in Slim 3 RC1

From RC1 of Slim 3, we have improved our error handling. We've always had error handling for HTML so that when an exception occurs, you get a nice error page that looks like this:

Slim3 error page

However, if you're writing an API that sends and expects JSON, then it still sends back HTML:

Slim3 old json error

At least we set the right Content-Type and status code!

However, this isn't really good enough. We should send back JSON if the client has asked for JSON. Until RC1, the only way to do this was to register your own error handler:

which provides the correct output:

Slim 3 custom json error

However, we can do better than this and do it for you. Starting with RC1, Slim will now output JSON (or XML) when an error occurs if the client's Accept header is application/json (or application/xml) and it will also provide all the previous exception too. This is much nicer and also works for the two other error handlers: notFound and notAllowed.

Slim 3 rc1 error json

Finally, Note that you should never use our default errorHandler in production as it leaks too much data! We'll try and fix this before 3.0 final, though.

random_bytes() in PHP 5.6 and 5.5

Last week, I needed some random data and using the power of the PHP manual, came across random_bytes which does exactly what I need. However, it's PHP7 only.

As I target both Linux and Windows, I needed to do a bit more work to get it working which was fine, but a minor nuisance given that I know that there's a better way in PHP7.

Talking on the #joind.in IRC channel a few days later, Anthony tells us about paragonie/random_compat which is a PHP 5.x polyfill for the PHP7 methods random_bytes() and random_int(). Usage is exactly the same, so when you switch to PHP7, you just remove the library from composer and all your code using these methods will continue to work.

I hadn't heard of it; I'm guessing that you haven't either, so now you know!