Yesterday I announced that the new major version of the league URI packages were released.
Because I am not the best expert in marketing I presume that people assume that only one
package was released while in fact 3 packages were released at the same time.<\/p>\n\n\n\n
As you might notice they all share the same version number and some packages just jumped major version released. The reason behind the jump is rather simple, all 3 packages have been developed as mono-repo for more than a year so it was about time that I normalise their release cycle.<\/p>\n\n\n\n
And while on the surface this is just a number change behind the scene for the past couple months I have been rewriting and re-organising the architecture of those 3 packages to ease maintenance but more important to boost the packages usage. A great example of that is the example I have shown in one of my announcement
post:<\/p>\n\n\n
\nuse League\\Uri\\BaseUri;\nuse League\\Uri\\Modifier;\n\n$uri = "https:\/\/www.bbc.co.uk";\n$relativeUri = "path\/to\/..\/..\/the\/sky\/?foo.bar";\n$appendQuery = "foo.bar=tata";\n\n$resolvedUri = BaseUri::from($uri)->resolve($relativeUri);\n$newUri = Modifier::from($resolvedUri)\n ->appendQuery($appendQuery)\n ->removeLabels(1)\n ->removeTrailingSlash()\n ->getUriString();\n\necho $newUri;\n\/\/ displays https:\/\/www.bbc.uk\/the\/sky?foo.bar&foo.bar=tata\n<\/pre><\/div>\n\n\nIt might surprise some of you but this was already possible using the previous packages
versions. The code would then look like this:<\/p>\n\n\n
\nuse League\\Uri\\Uri;\nuse League\\Uri\\UriModifier;\nuse League\\Uri\\UriResolver;\n\n$uri = "https:\/\/www.bbc.co.uk";\n$relativeUri = "path\/to\/..\/..\/the\/sky\/?foo.bar";\n$appendQuery = "foo.bar=tata";\n\n$baseUri = Uri::createFromString($uri);\n$relativedUri = Uri::createFromString($relativeUri);\n$resolvedUri = UriResolver::resolve($relativedUri, $baseUri);\n$newUri = UriModifier::appendQuery($resolvedUri, $appendQuery);\n$newUri = UriModifier::removeLabels($newUri, 1);\n$newUri = UriModifier::removeTrailingSlash($newUri);\n$newUri = $newUri->__toString();\n\necho $newUri;\n\/\/ displays https:\/\/www.bbc.uk\/the\/sky?foo.bar&foo.bar=tata\n<\/pre><\/div>\n\n\nApart from chaining, the main differences between those two style of code is that in v7 we are less strict on the input argument type, it should at least be a string or a Stringable<\/code> object, we are still as strict on the returned value. This means that the code is smart enough to detect the input and if it is not a known URI object it will attempt to convert the input into one before performing the intended action. In contrast, with the older version, we expected the developper consuming the library to do it for us before submitting the URI the to package API.<\/p>\n\n\n\nTo achieve the new behaviour I had to re-organised the packages. Before, The URI and and URI
components were fully decoupled. You could download and install each package independently.
This is no longer true, each package is now built on top of the other. The URI package
requires the URI interfaces package and the URI component package requires the URI package.
With this change it means that, for instance, the URI component Modifier<\/code> class knows how to
instantiate at any given time a URI. This was not possible before.<\/p>\n\n\n\nSame code, new features<\/h2>\n\n\n\n
Another improvement because of the new coupling between classes is that I could re-organised the classes between packages. For instance, all the parsers (the URI parser and the Query parser) are now part of the URI Interface packages. The role of this package has evolved since its first release. It used to be a package that only contains contracts used by the other two packages, now it is also a package that exposes common tools to use when handling URI, parsers fall into that description. In addition, the new architecture gave me the opportunity to rewrite and expose other tools independent of URI packages.<\/p>\n\n\n
\nuse League\\Uri\\Idna\\Converter as IdnConverter;\nuse League\\Uri\\IPv4\\Converter as Ipv4Converter;\n\necho IdnConverter::toAscii('b\u00e9b\u00e9.be')->domain(); \/\/display "xn--bb-bjab.be"\necho Ipv4Converter::fromEnvironment()->toDecimal('192.87.125'); \/\/display "192.87.0.125"\n<\/pre><\/div>\n\n\nThose two features were already present in the codebase but the rewrite and architectural
changes enabled their exposition and improved their usage inside and outside the packages.<\/p>\n\n\n\n
Avoid re-inventing the wheel<\/h2>\n\n\n\n
One of the most difficult thing when complying to RFC and specifications is that most of them handle
gracefully errors and mistakes. Which means that it may be hard for developers to know if something
is not the expected result or not. In this new version, I try to improve the developer experience when possible using the following pattern:<\/p>\n\n\n
\nuse League\\Uri\\UriTemplate;\n$template = 'https:\/\/api.example.com\/{version}\/search\/{term}\/{?q*,limit}';\n\n$params = [\n 'term' => ['john', 'doe'],\n 'q' => ['a', 'b'],\n 'limit' => '10',\n];\n\n$uriTemplate = new UriTemplate($template);\necho $uriTemplate->expand($params);\n\/\/ display https:\/\/api.example.com\/\/search\/john,doe\/?q=a&q=b&limit=10 with missing version\n\/\/ this is valid and follow the specifications\n\necho $uriTemplate->expandOrFail($params);\n\/\/ will throw a TemplateCanNotBeExpanded exception with the following message\n\/\/ Missing variables `version`\n<\/pre><\/div>\n\n\nThe new expandOrFail<\/code> method is stricter than the RFC compliant expand<\/code> method and throw if a variable is missing. It will be easier for developer to recognise the method behaviour because it is a well established signature in some PHP communities but more importantly it avoids adding extra boolean argument to a well establish method which makes the intent clearer. In summary, when possible, stricter method are provided with the orFail<\/code> suffix.<\/p>\n\n\n\nBackward compatibility<\/h2>\n\n\n\n
What’s great about all these changes is that you will not have to rewrite your application, as the new version is fully backward compatible with the previous packages. Which all your current code is still valid with the new version even if your IDE of choice will more than likely flag the code as being deprecated.
This should give you plenty of time to upgrade your current codebase but if you are new to the package I encourage you to not look in the past and to embrace the new public API which frees you for most of the basic usage from learning how URI works and let’s you focus on your actual application logic.<\/p>\n\n\n\n
While this post is not aiming at presenting all the new features, you can head over the
documentation website<\/a> to get the full public API, I hope it gave you the underlying motivation for this new version which was to make the code easier to interact with and more intuitive.<\/p>\n\n\n\nLast but not least<\/h2>\n\n\n\n