Magento 2 WordPress Integration Documentation

Installation

Before installing the free extension, we must first install and configure WordPress. This is easy and only takes a few minutes. We can then install the extension and connect Magento and WordPress securely via the WordPress API. Finally we can install the Yoast SEO plugin (optional). This process is explained below.

Install WordPress

You can install WordPress on it's own server or in a subdirectory of Magento.

Install on Separate Servers

This is the most secure method of integrating WordPress into Magento 2 as it keeps Magento and WordPress completely separate.

When installing this way, you can install WordPress using any domain or subdomain, it does not have to match the Magento domain/sub-domain (although if it does, it's not a problem).

Install WordPress on the Magento Server

If you want to install WordPress on the same server as Magento, you should install WordPress in the pub directory of Magento in a folder named 'wp'. This folder can be anything, but it shouldn't be something that you plan on using for an actual frontend URL. As an example, if you plan on having a /blog/ page, installing WordPress to /blog/ will stop this from happening. This tutorial recommends installing to /pub/wp but you can use any directory name.

Nginx

The Nginx configuration required for WordPress when it is integrated into Magento is the same as when you run WordPress on it's own. No special requirements are added because WordPress is integrated into Magento.

If you are installing WordPress on it's own server and using the external integration method then you should follow the official guides. If you are using local integration method and have WordPress installed in a subdirectory, the following Nginx code can go at the bottom of your Magento server block:

# Change /wp/ to the WordPress directory
location /wp/ {
  index index.html index.php;

  # Change /wp/ to the WordPress directory
  try_files $uri $uri/ /wp/index.php$is_args$args;

  location ~ \.php$ {
    fastcgi_pass   127.0.0.1:9000;
    fastcgi_index  /wp/index.php; # Change /wp/ to the WordPress directory
    include        fastcgi.conf;
  }
}

Configure WordPress

Now that WordPress is installed, lets make some configuration changes to get it ready for integration.

WordPress URLs

Login to your WordPress Admin and select Settings > General and change the second URL (Site Address (URL)) to your Magento base URL with any directory added on that you want your integrated blog to be visible from (eg. /blog). This directory can be anything, but /blog/ seems to be a popular choice these days. You can change this at anytime so don't worry too much about what you put while getting things set up.

Install the Extension

Now WordPress is ready, let us install the free Magento 2 WordPress Integration extension.

You can install the module for Magento 2 using Composer or you can manually install it using FTP.

# Install the module using Composer
composer require fishpig/magento2-wordpress-integration:^3.0

# Enable the module in Magento 2
php bin/magento module:enable FishPig_WordPress

# Run the Magento upgrade system
php bin/magento setup:upgrade

# Enable the module in Magento 2
bin/magento module:enable FishPig_WordPress

# Run the Magento upgrade system
bin/magento setup:upgrade

Now that the extension is installed, login to the Magento 2 Admin and select WordPress > Configuration from the navigation menu.

By default the module will be using local mode but you can change this to external mode.

External Integration Mode

External integration mode can be selected from Magento Admin > WordPress > Configuration > Mode. When selected, the module will integrate with a server through a combination of the WordPress API and database connection. Upon selecting this, you will be required to add the database connection details for WordPress. Ensure that the WordPress server will allow database connections from the Magento server.

Local Integration Mode

This is the default integration mode. In this mode, the module will look for a WordPress installation on the server using the path provided (default is wp). You will need to change the path option if you have not installed in a subdirectory named wp. You can specify an absolute or relative path. Magento will then read the wp-config.php and use this to connect to the WordPress database.

While there may be security implications of having WordPress installed on the Magento server (although this can be negated using a proper setup), there are benefits to installing using local integration mode. Dynamic image resizing is available, plus you only need one server.

WordPress Theme Installation

WordPress runs in a headless mode so the WordPress theme is not used to display the blog and Magento handles this. Instead of a WordPress theme, the module provides a WordPress theme that helps with integration. The process for updating the theme differs when in local and external integration mode.

WP Theme Installation in Local Mode

When a theme update is found, the module will try to update the theme automatically. If this happens, this will happen silently and you won't know. If an error occurs and you need to build and install the theme manually, you can do so using the commands below:

# Build theme and print path to theme ZIP to screen
bin/magento fishpig:wordpress:build-theme

# Build theme and install ZIP to --install-path
bin/magento fishpig:wordpress:build-theme --install-path=pub/wp

WP Theme Installation in External Mode

As WordPress is installed on a separate server, it's not possible to automatically install the theme. Instead, you can run the following command to generate a ZIP file containing the latest version of the theme.

bin/magento fishpig:wordpress:build-theme

This will print to the screen the path to the latest theme build. You can then install this theme in the WordPress via the WP Admin > Appearance > Themes > Add New > Upload Theme. You may be prompted about overwriting an existing theme. If this happens, confirm and the latest version will be installed on top of the existing version.

Yoast SEO

It is highly recommend to install the free Yoast SEO plugin as this provides basic SEO features that you will need. To get this data working when WordPress is integrated into Magento, you will need to install another free Magento 2 module.

You can install the module for Magento 2 using Composer or you can manually install it using FTP.

# Install the module using Composer
composer require fishpig/magento2-wordpress-integration-yoastseo:^3.0

# Enable the module in Magento 2
php bin/magento module:enable FishPig_WordPress_Yoast

# Run the Magento upgrade system
php bin/magento setup:upgrade

# Enable the module in Magento 2
bin/magento module:enable FishPig_WordPress_Yoast

# Run the Magento upgrade system
bin/magento setup:upgrade

↑ Back to Top

Customisation

The module is built using Magento standards so customising it is the same as customising any Magento 2 module.

Template Customisation

When WordPress is integrated into Magento, the WordPress theme is not responsible for the frontend display of the blog and this is handled by Magento. The module comes packaged with some basic templates that will display your blog data. These are basic templates but easy to customise so that you can achieve any design that you require.

It is highly recommended that you review the templates provided by the module as these have been written as examples of what can be achieved and include comments showing further possibilities. These templates can be found in one of the following locations (depending on how you installed the module):

Edit .phtml Template Files

If you want to edit any of these templates, do not edit the file directly. Instead copy the file to your custom theme, preserving the path. This will stop you from losing changes when updating the module.

Layout XML

Layout XML files are Magento's way of building up pages based on individual blocks and are key part of the frontend theme system. They are very powerful and will allow you to make big changes with small pieces of code if you correctly understand them.

The module uses many different layout handles, some static and some dynamic that change based on the content. Some of the more popular layout handles are included below, but to see all available layout handles, use the code listed above.

Change the Page Layout

In Magento 2, the page layout is the root template. The module comes configured to use 2columns-left layout, but this can easily be changed for 1column, 2columns-right, 3columns, empty or any custom page layout that you have setup.

To change the page layout, you need to create a custom layout XML file. Use the layout file names listed above to decide what you want to target the new page layout for and then use the XML listed below.

<?xml version="1.0"?>
<page layout="2columns-left"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
  <!--
  /*
   * Change the layout="2columns-left" above to your new page layout
   */
  -->
</page>

Change Block Templates (.phtml Files)

You can change the template of any block in Magento by finding the layout name used but the key templates you might want to change for WordPress Integration are the post list templates and single post view.

Select the correct layout handle from above and use the layout XML below to change the templates.

FishPig_WordPress::post/list.phtml

This template is used on all archive pages to list the posts. In this template, each post is displayed via a renderer (more on this below) but you could remove the renderer and just add all post list code in this template.

<?xml version="1.0"?>
<!--
/*
 * You should create custom-list.phtml at:
 * app/design/frontend/YourVendor/YourTheme/FishPig_WordPress/templates/post/custom-list.phtml
 * Copy the default post/list.phtml to get you started
 */
-->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
  <body>
    <referenceBlock name="wp.postlist.wrapper"
                    template="FishPig_WordPress::post/custom-list.phtml" />
  </body>
</page>

FishPig_WordPress::post/list/renderer/default.phtml

This template is used to display each post in an archive/post list. post/list.phtml is the wrapper template while post/list/renderer/default.phtml is the individual post template.

The module will automatically change the renderer template based on the post type using the format: FishPig_WordPress::post/list/renderer/{post_type}.phtml. If this custom template cannot be found then the default.phtml will be used.

To change this template manually via XML, use the following XML:

<?xml version="1.0"?>
<!--
/*
 * You should create custom-list.phtml at:
 * app/design/frontend/YourVendor/YourTheme/FishPig_WordPress/templates/post/list/renderer/custom.phtml
 * Copy the default post/list/renderer/default.phtml to get you started
 */
-->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
  <body>
    <referenceBlock name="wp.post.list">
      <action method="setRendererTemplate">
        <argument name="template" xsi:type="string">FishPig_WordPress::post/list/renderer/custom.phtml
      </action>
    </referenceBlock>
  </body>
</page>

As an example, you could use the above XML to change the post renderer for a specific category by using it in wordpress_category_view_123.xml (where 123 is the category ID).

FishPig_WordPress::post/view.phtml

This is the template used to view the post. This is automatically changed on the post type of the current post so you can create a new template in your theme using the post type and it will be selected automatically.

The module checks for the FishPig_WordPress::{post_type}/view.phtml template. You can create this template at FishPig_WordPress/templates/{post_type}/view.phtml in your custom theme.

You can also change this template manually via XML:

<?xml version="1.0"?>
<!--
/*
 * You should create view-custom.phtml at:
 * app/design/frontend/YourVendor/YourTheme/FishPig_WordPress/templates/post/view-custom.phtml
 * Copy the default post/view.phtml to get you started
 */
-->
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
  <body>
    <referenceBlock name="wp.post.view" template="FishPig_WordPress::post/view-custom.phtml" />
  </body>
</page>

↑ Back to Top

Code Examples

The module is built to Magento 2 standards so uses blocks, models and controllers to manipulate and display data. This means that if you can already work with products, you should be fine working with blog posts and terms as it uses the same system.

• General code examples
• Custom post lists
• Menus

↑ Back to Top

Security

From version 3.0 the module now allows for a local integration mode (this is the usual way) and a new external integration method. As each mode is very different, security is discussed below for each method.

External Mode

WordPress is installed on a separate server and has no access to Magento. This means that Magento is protected from any WordPress issues and WordPress poses no security risk to Magento.

Local Mode

WordPress is installed in a subdirectory of Magento so if WordPress is compromised it increases the chance of Magento being compromised. To combat this increased risk, ensure you follow these steps:

• Always keep WordPress updated. This includes the WordPress core and plugins.
• Uninstall all themes except the FishPig theme.
• Only install plugins from reputable sources.
• Use separate databases with separate users and a custom table prefix.
• Delete core files you don't need (license.txt, readme.html, wp-activate.php, wp-config-sample.php, wp-cron.php, wp-links-opml.php, wp-mail.php, wp-signup.php, wp-trackback.php, xmlrpc.php)

↑ Back to Top

Caching & Optimisation

As WordPress runs in headless mode (Magento displays the frontend rather than WordPress), most standard WordPress optimisation strategies will not work. Instead, focus your attention on optimising Magento as this will cover the integrated WordPress portion of the site. It's still important to optimise WordPress though, so we cover that below too.

WordPress Optimisation

Always keep WordPress up to date and remove any items (themes, plugins) that you do not use. The more code WordPress has, the longer it will take to run.

WordPress makes it easy to update and remove items so there is no excuse for running old and bloated software with WordPress.

Magento Optimisation

At FishPig, we specialise in Magento 2 optimisation are offer a very popular suite of optimisation extensions. These have all been designed to cover both Magento 2 and WordPress so will provide the best performance results when integrating WordPress.

Minify, Defer, Image Optimisation etc

The FishPig Magento 2 Page Speed extension provides asset minification, image optimisation (webp) and so much more that it will instantly - and automatically - provide a speed boost to your Magento and WordPress websites. Just install the module and the performance improvements will be applied automatically

Page Caching

The integration fully supports the native Magento 2 FPC as well as Varnish so if you're already using these then you can continue to use them.

If you want another solution for page caching, we offer a Magento 2 full page cache module that provides faster speeds than the native Magento 2 FPC but is much easier to setup than Varnish.

It's easy to install and will reduce your time to first byte (TTFB) to less than 0.5 seconds (often it gets as low as 0.1 seconds).

General Optimisation Tips

These general tips apply to both Magento and WordPress.

PHP 7 + OPCache

Use the highest version of PHP 7 that Magento currently supports (PHP 7.3 at the time of writing) and enable OPCache.

The beauty of this is that it makes PHP faster at it's core so this improves the speed for all pages, including content not usually cachable like the checkout or Magento backend.

Block Bots

Your server can only handle so much traffic at one time and as more traffic is added, each request slows down. This is bad because a slow website stops users buying and negatively affects your SEO.

This is why it makes no sense to allow bad/spam bots to browse your site and use up valuable resources that could be better spent on real customers. To combat this issue we created the Magento 2 Security extension. This security module runs various rules that it uses to identify and block bad bots from your site. It's invisible so real customers won't know it's there and it has safety nets in place to stop real customers (and good bots like Googlebot) from getting blocked. Install it and watch as the list of blocked bots increases hourly and you know that your server is only being used by real customers and good bots.

Manual Image Optimisation

When uploading any image to your blog, first run it through an image compressor. Our favourite is TinyPNG but there's plenty more out there.

↑ Back to Top