Embedding PHP forms in Vue.js

Using forms rendered and processed by PHP in a Vue.js single-page application.

There are many different approaches to migrating a PHP web application to Vue.js. Rewriting everything at once is usually not the best solution, as it almost always takes much more work than you expect. So a progressive approach is usually better.

One way to do that is to embed Vue.js components in pages which are rendered using PHP. I wrote about this last week. Today we will do something opposite: we will embed existing PHP forms inside a Vue.js application.

This time I will use a more concrete example, because I’m just working on a new version of WebIssues, an open source issue tracker written in PHP.

Like many web applications, WebIssues has one main view, which displays a list of issues and the details of the selected issue. It also has a bunch of forms for editing issues, configuration and administration tasks.

The main view is most important, so I’m rewriting it completely using Vue.js. However, rewriting all the remaining forms would take a lot of time, so I decided to leave them as they are for now.

But switching back and forth between the new Vue.js page and the old PHP forms wouldn’t be a good solution. One problem is efficiency; the whole point of using Vue.js is to avoid constantly reloading the whole page. Besides, such switching wouldn’t feel very consistent to the users.

After some experiments, I decided to implement a hybrid solution. I created a single-page application in Vue.js which has a header, a sidebar and a list of issues. Both the issue details and the PHP forms are displayed in an overlay window. This gives a consistent look and feel and makes it possible to use all the forms without reloading the page.

Here’s an example of what it looks like:

Note that the form doesn’t have to be placed in an overlay window, it’s just an example. I can be displayed in the main content area of the page or anywhere else.

The solution that I’m presenting here doesn’t use any iframes, the content of the form is placed directly on the page. So how does it work?

It’s simple, we use AJAX requests to load the form. When the form is first opened, we send a GET request to the form URL, and when it’s submitted, we send a POST request.

The form is rendered and processed by the PHP code as usual. The result of the request is simply some HTML which can be displayed inside a Vue.js component.

This sounds easy in theory, but of course the devil is in the details, so let’s implement this step by step.

Displaying the form content

Normally the page rendered by PHP contains not just the form, but also the header, footer and other elements that we don’t want to display.

There are a few ways to solve this. We could parse the HTML on the client side and extract only the element that we need, but that would be slightly inefficient. We can also detect that the request comes from AJAX, for example using a special X-Requested-With header, and strip those unnecessary elements on the server side.

We can even go one step further. When the PHP code detects the special header, it can return the response in JSON format, including not just the HTML content of the form, but also additional metadata, such as its title.

Such response looks more or less like this:

{"content":"<form>...</form>","title":"My Form"}

Let’s create a simple component called DynamicForm.vue that will load and display the form:

import axios from 'axios'
<template>
  <div>
    <h1>{{ title }}</h1>
    <div v-html="content"></div>
  </div>
</template>
<script>
export default {
  data() {
    return {
      title: '',
      content: '',
      components: null
    };
  },
  methods: {
    load( url ) {
      axios.get( url, {
        headers: 'X-Requested-With': 'XMLHttpRequest'
      } ).then( response => {
        this.title = response.data.title;
        this.content = response.data.content;
        this.components = response.data.components;
      } );
   }
}
</script>

The component has three data properties. The title is displayed in the header element. The content is displayed in the inner <div> element. We use the v-html directive to display it as HTML instead of plain text. I will talk about the components property a bit later.

The load() method takes the URL as an argument and sends an AJAX request which loads the form. Then we extract the properties from the response. The content of the component is automatically updated by Vue.js so the form is displayed inside our <div>.

Note that I use axios to perform AJAX requests, but you can use vue-resource or another library.

Submitting the form

If you run this code and press the submit button in the form, the whole page will be redirected to its target URL, which is not what we want.

We have to intercept submitting the form and replace it with our logic. To do this, let’s add a click handler to the inner <div> element:

<div v-html="content" v-on:click.capture="handleClick"></div>

Note that we use the capture modifier to ensure that our handler is called before other click handlers.

The handleClick() method looks like this:

handleClick( e ) {
  if ( e.target.tagName == 'INPUT' && e.target.type == 'submit' ) {
    let data = formSerialize( e.target.form, {
      hash: false, empty: true
    } );
    data += '&' + e.target.name + '='
         + encodeURIComponent( e.target.value );
    axios.post( url, data, {
      headers: 'X-Requested-With': 'XMLHttpRequest'
    } ).then( response => {
      this.title = response.data.title;
      this.content = response.data.content;
      this.components = response.data.components;
    } );
    e.preventDefault();
  }
}

First, we check if the clicked element is an input element and if it’s actually a submit button.

Then we serialize the data from all input fields in the form. To do this we use the form-serialize module, which handles a whole variety of elements. I’m setting the empty option to true to include fields without values, because it’s more similar to typical browser behavior.

The formSerialize() function doesn’t include information about the button that was used to submit the form, so we have to append it manually. We use the name and the value of the button just like browsers do. This way the code on the server side can perform appropriate action depending on the button.

Finally, we send the AJAX request just like in the previous example, but this time we use the POST method and send the serialized data in the request.

We also call e.preventDefault() so that the browser doesn’t submit the form on its own.

Note that this mechanism also works when the form is submitted using the enter key, because the browser emulates a click event in such case.

Creating child components

Your forms can contain not just plain input fields, but also interactive elements: date pickers, autocomplete fields, etc. Of course we want to use Vue.js components to handle them.

We have to make sure that the components within the form are correctly created and destroyed when the form is reloaded. To do this, we have to handle a few lifecycle hooks of our DynamicForm:

mounted() {
  this.createFormComponents();
},
beforeUpdate() {
  this.destroyFormComponents();
},
updated() {
  this.createFormComponents();
},
beforeDestroy() {
  this.destroyFormComponents();
}

The mounted() hook is called when the component is displayed, in other words attached to a DOM element. Depending on the application, the component can only be displayed when the form is already loaded, so we need to create the form components at this point.

When the form is reloaded and the data properties are updated, first the beforeUpdate() hook is called. We destroy the old form components there. Then Vue.js updates the DOM, so the content of the form is replaced. Finally, the updated() hook is called and we can create the new form components.

We also handle beforeDestroy() to destroy our form components when the DynamicForm is about to be destroyed.

There are many ways to implement the createFormComponents() method which depend on your specific case. I wrote about this last week.

In WebIssues I simply include the information about all form components that need to be created in the JSON response from the server. That’s the purpose of the components property that you saw earlier.

So the createFormComponents() method is really simple:

createFormComponents() {
  if ( this.components ) {
    this.$formComponents = this.components.map( data => new Vue( {
      el: data.el,
      render( h ) {
        return h( data.type, { props: data.props } );
      }
    } ) );
  }
}

All created components are stored in the $formComponents property, so the destroyFormComponents() method is also quite simple:

destroyFormComponents() {
  if ( this.$formComponents ) {
    this.$formComponents.forEach( cmp => cmp.$destroy() );
    this.$formComponents = null;
  }
}

Forcing updating the HTML

The above implementation works correctly in most cases, but it has one bug which is hard to notice.

It may happen that after submitting the form, the returned HTML will be identical to the previous content. In such case, Vue.js won’t update the content of the inner <div> because it assumes it’s not necessary.

However, when we create form components, they modify the content of the form. So what happens in that case is that we destroy the old components, the content of the <div> remains unchanged — so it still includes the modifications introduced by these components — and we try to create these components again. This may lead to errors or other strange results.

To fix this, we can update the innerHTML of the <div> element manually instead of using the v-html directive.

So we slightly change the template:

<template>
  <div>
    <h1>{{ title }}</h1>
    <div ref="body" v-on:click.capture="handleClick"></div>
  </div>
</template>

We also need to change the corresponding code:

mounted() {
  this.$refs.body.innerHTML = this.content;
  this.createFormComponents();
},
beforeUpdate() {
  this.destroyFormComponents();
},
updated() {
  this.$refs.body.innerHTML = this.content;
  this.createFormComponents();
},
beforeDestroy() {
  this.destroyFormComponents();
}

Handling redirects

The result of submitting a form is very often a redirect to another page. When we submit the form using AJAX, the redirect is processed automatically and a new request to the new URL is made, which is not always what we want.

So instead of returning the 302 Found response, the server side code should return a standard 200 OK response and include the target URL in the returned JSON data.

Here’s an example PHP function which performs a redirect:

function redirect( $url )
{
  if ( $_SERVER[ 'HTTP_X_REQUESTED_WITH' ] == 'XMLHttpRequest' ) {
    header( 'Content-Type: application/json' );
    echo json_encode( array( 'redirect' => $url ) );
  } else {
    header( 'Location: ' . $url );
  }
  exit;
}

This function detects the X-Requested-With header and either returns this special JSON response or performs a regular redirect.

This way we can detect the redirect on the client side and act accordingly:

axios.post( url, data, {
  headers: 'X-Requested-With': 'XMLHttpRequest'
} ).then( response => {
  if ( response.data.redirect ) {
    handleFormRedirect( response.data.redirect );
  } else {
    this.title = response.data.title;
    this.content = response.data.content;
  }
} );

I deliberately left out displaying progress, handling errors, etc. to keep the examples simple enough to understand. There will probably be other things that you will have to take care of when implementing a fully working solution.

However, I think that this is a good starting point if you’re migrating a classic PHP application towards a single-page application using Vue.js. Such hybrid approach isn’t perfect, but it’s definitely easier than rewriting all the forms using Vue.js.