Category Archives: PHP

All things PHP

Documentation Driven Development

Documentation Driven Development

At adopting a new and growing trend, “documentation driven development” via “swagger” and now the newly updated specification, “OpenAPI 3”.

Documentation driven development (DDD) is not something new (some of its earliest concepts date back to 2011), but up until recently it never had an officially accepted name, nor an industry standard for the world to agree upon. It is the process of describing an API’s endpoints and what it expects as a request and should respond with. This enables a front-end team to easily use an API within their apps and mock the response.

Documentation driven development boils down to a two high level and basic principles:

  • Design the API first, then build it
    • The API design must adhere to the OpenAPI Specification (formerly known as Swagger)
    • The yaml file can be broken up with swagger-chunk
    • The finished result of the API design should be a Yaml or JSON file
    • The actual API routes should be built on what is documented in the design
    • The client, eg the browser, should communicate with the API via a generated file, built from a tool such as swagger-code-gen
  • An endpoint not documented should not exist
    • A JavaScript front-end engineer using a generated DDD API access file should not look outside of this file to access the API
    • As all routes must be documented, any other routes can be seen as not required &/or dangerous

Adhering to DDD simultaneously increases development speed whilst solving a growing issue regarding how the front-end and back-end teams both build and communicate. Further more this is not limited to company cross-team dynamics but also expandable to cross-company communications.

Looking to the future

DDD has given us some very big gains as described, but what could the future look like and how do we aim to streamline this process yet further.

Currently the API design must be written in a single Yaml file. When the API gets bigger than trivial the need to break the file down into sizable chunks becomes a must, this is where swagger-chunk comes in. swagger-chunk allows the developer to write many smaller and managable Yaml files which swagger-chunk then combines together into one.

Swagger-chunk is one step in the right direction, but it can be easy to get lost in a myriad of similar looking files. Further more, designing an API does not nesasarily depend on skill of a developer if there were an alternative to writing pure Yaml chunks…. Enter openapi-gui.

Openapi-gui is a graphical user interface to building the API design. The API designer does not require anything more than a web browser and technical knowledge on what a RESTfull API should be and deliver. In laymans terms, the API design can now be realised by a skilled technical product owner

 

Server side rendering with phpv8/v8js on Ubuntu

https://vuejsdevelopers.com/2017/11/06/vue-js-laravel-server-side-rendering/ requires phpv8/v8js. Here is how to install the latest (at the time of writing) with php7.1.

Add the latest ppa from this guy: https://launchpad.net/~pinepain

Update the sources:

Install libv8:

Install and compile v8js

Optionally remove the files from the install from /tmp.

After this the SSR of the example vuejs app should work.

Expose all variables in a Twig template in Symfony

Ever worked on a big framework and been new to it.. then you have to somehow figure out a twig tpl without know what variables have been passed?

 

Simple solution, dump all the var keys in the twig tpl:

Injecting twig template names into html source on develop environment

After working on a few big projects, or jumping into existing big projects one trick that helps people get up to speed quickly is highlighting which template has been used at which point in the views. With the Twig tpl system that is reasonably simple:

Assuming a custom php project you can control most from a single render function.

Now you need you twig debug template

 

In the render function you can see I also include some custom twig functions, these come from a file like this:

 

Sort a multi dimensional array

Function to sort php multi-dimensional arrays

eg

Laravel and the lighter sibling

 

Symfony has it’s lightweight sibling, and they called it Silex.

Under the hood of Laravel is Symfony, yet Laravel somehow managed to make a light weight version of the Laravel stack that runs faster that Silex… they called it Lumen:

https://lumen.laravel.com

And as with the Laravel framework it has some beautiful documentation to go with it… Nice work Taylor Otwell!

(Laravel has got to be one of the few if not only frameworks out there that really just works. On top of that, I rarely find the need to stray away from the official documentation either. Why can’t all frameworks be like that! It cannot be that hard can it?)

Laravel 5.4 dropped support to switch out the default blade tags… Use Twig instead, pretty much the same anyway.

Dropping out the default blade syntax used to be as simple as dropping this into the AppServiceProvider->boot function:

But out of the blue, they dropped the setContentTags support..

As a result the migration 5.3->5.4 was either change out all the js tpl syntax for alternatives, or preface every single non-blade with @{{ somethingFromAng }}.

As Twig is basically the same syntax as blade and uses pretty much the same inheritance system, instead of changing any template code, the easier option is to drop blade in favour of twig. Twig is a more flexible tpl language IMHO opinion anyway so win win 🙂

EZPublish migrating content types.

Use this: https://github.com/kaliop-uk/ezmigrationbundle

The basic idea is to write yaml files that act as migration files. If you are familiar with the db migrations from the Laravel 4+ framework you will already have a feel for it.

Each migration is only run once and stored in the database.

First create the migration file after installing with:

Change the content of the YML to something like this simple content type.

Run the migration on the server:

Getting EZPlatform to display google maps in the admin

As of writing ezplatform still cannot handle google maps api keys.

This is a hack till the release is out there to use ( https://jira.ez.no/browse/EZP-26068 )

First up grab yourself a key

  1. https://console.developers.google.com click on the library section in the side nav.
  2. In the top nav should now be a button for enable, you will need to then follow the on screen instruction to get an api key.
  3. Then do the same for Google Maps Geocoding API. This will enable the address lookup for the content type.

Next add your key to the following files where they ref. the google url:
Definitely needed:
ezplatform/vendor/ezsystems/platform-ui-bundle/Resources/public/js/services/ez-googlemapapiloader.js

Might as well whilst you are there:
ezplatform/vendor/ezsystems/platform-ui-bundle/Tests/js/services/assets/ez-googlemapapiloader-tests.js
ezplatform/web/bundles/ezplatformui/js/services/ez-googlemapapiloader.js

That should be it, clear ‘dem cache and you should be good to go. Just remember to repeat this on every environment and after a composer update… although hopefully this should be fixed soon!