Dealing with uncomposable PHP dependencies

For managing dependencies in PHP, you rely on Composer.  But how do you manage a dependency that doesn't support composer?  Simple: weave it into your repository using braid.

---

Recently, I found a need to deep profile Pattern, so I turned to xhprof.  Composer has spoiled me with its ease of use (think composer install)  but xhprof proper isn't composer-aware.  Is there a simple way to incorporate the xhprof code?

Yes!  The general problem to solve is that of "external dependency bundling".  The tried-and-true approach is to download the code, copy it into your repository, and then commit it.  But there are at least two problems with that approach:

1. Unscripted: I have to write the commands to do the work, and ensure I run those same commands each time I update the dependency from source.
2. Mutable: I might decide I want to change the library, so I tweak the source code in situ, but can no longer easily track upstream changes.

There is a tool that handles both these problems: braid (introduction).  This ruby gem is a true gem, in the sense that it's both rare and valuable.  Here's an example of how I can weave xhprof into Pattern:

$ git clone git@github.com:bishopb/pattern.git
$ cd pattern
$ braid add https://github.com/phacility/xhprof vendor/phacility/xhprof
$ git push

Done!  I now have the xhprof remote repository weaved into Pattern:

$ git log -1
commit 123456
Author: me
Date: today

  Braid: Add mirror 'vendor/phacility/xhprof' at '0bbf2a2'

$ ls vendor/phacility/xhprof
bin  CHANGELOG  composer.json  CREDITS  examples  extension  LICENSE
package.xml  README  scripts  support  xhprof_html  xhprof_lib

Time passes, xhprof has updated. I can pull the updates using braid update vendor/phacility/xhprof.

Best of all, if I make local changes to xhprof, braid can show me the changes using braid diff vendor/phacility/xhprof.  braid update handles the merge smoothly, too.  I get the same kind of merge conflict tools as with git proper, because braid uses git under the hood.

In the end, you don't actually need braid for xhprof: there is a composable fork.  So to remove a braid use braid remove vendor/phacility/xhprof.