Commit and Deploy Webhooks

As well as receiving e-mail notifications, you can set up repository-specific commit and deploy webhooks for your WordPress.com VIP code.

Set up

To tell WordPress.com which webhooks to ping, simply add a wpcom-meta.php to the root of your repo with something like this;


<?php
/**
 * Commit Webhook: https://incoming.my-webhook.com/commit
 * Deploy Webhook: https://incoming.my-webhook.com/deploy
 */

Committing that file is all you need to do to create the webhooks. If you have any difficulties, or need more information, don’t hesitate to open a ticket with us.

Note: Services, such as Slack, require data to be transformed into a standard format for their platform. So in this instance you would have to transform the data prior to passing it to Slack.

Commit Webhook

The commit webhook will provide the following data:

  • repo – The name of the repository.
  • theme – The name of the theme.
  • revision – The committed revision number.
  • committer – The WordPress.com username of the committer.

Deploy Webhook

The deploy webhook will provide the following data:

  • repo – The name of the repository.
  • theme – The name of the theme.
  • previous_revision – The previously deployed revision.
  • deployed_revision – The deployed revision number.
  • deployer – WordPress.com username of the person who deployed the revision.
  • revision_log – A log of commits between the previously deployed and newly deployed revisions.

Understanding the WordPress.com VIP Codebase

Can you explain the WordPress.com VIP Codebase to me?
Why, yes we can! Here’s a visual guide.

[visual-guide guide=”codebase”]

Where can I track the development of WordPress?
WordPress is an open-source project. You can track the development of it on the Make WordPress Core blog, and see the latest tickets in trac. In addition, there are weekly developer chats that are open to the public.

Roughly three times a year, the WordPress open source project releases a new update of the WordPress software. The project’s timeline and features can be tracked on the main core blog.

What version of WordPress does WordPress.com VIP run?
WordPress.com VIP runs on WordPress.com. WordPress.com is always running as close to the latest version of WordPress as possible, often incorporating code from beta releases.

WordPress.com is a single multisite running millions of sites. It has 200+ extra features built on top of core WordPress to help with everything from performance, to SEO, to security. Many of these features are available via the Jetpack plugin.  In addition, WordPress.com VIP users have access to more than a hundred vetted-and-approved plugins.

What direction do code releases go?
Generally speaking, WordPress.com incorporates the latest code from the WordPress open-source project. However, Automattic is one of the largest contributors to WordPress, so often times improvements made on WordPress.com are contributed back to core. In addition, feedback from WordPress.com VIP helps improve development on WordPress.com and in WordPress core.

What are the names of the releases? What’s the terminology?
WordPress follows a very specific naming convention, which you can see in the release archive. Each release is named after a jazz musician. For every release, there’s a cycle: Beta (1,2,3), Release Candidate (1,2), and finally, the Release. You can see this cycle in action on an official release timeline.

Typically, WordPress.com starts incorporating code from the latest release at around the Beta 1 stage.

How do I test for an upcoming release?
The easiest way to test is a local development environment. It automatically sets you up with an SVN checkout of trunk (and auto-updates every time you run vip-init.sh or .bat). You can also use the Beta Tester plugin to easily update beta releases and test.

What about VIP plugins? How do updates affect those?
The WordPress.com VIP team maintains and updates the plugin repository. If you have any questions or spot any bugs, you can report it to the VIP team.

Accessing Your Code

All WordPress.com code is managed using the Subversion revision control system. Subversion (SVN) is the only way to access and update code on VIP Hosting.

If you are a Microsoft Windows user, we recommend using the TortoiseSVN GUI client. If you use a Mac, and you don’t grok a little UNIX, SVNX comes recommended.

Accessing SVN

To get SVN Access to your theme, please first make sure you have Two-Step Authentication enabled.

Two Step Authentication drastically reduces the likelihood that someone could gain unauthorized access by adding a second, very hard-to-guess log in requirement to your user account. To learn more about Two Step Authentication, read the support page or contact VIP.

Once that’s all set, you can request for SVN Access via your VIP Dashboard, under the “VIP” tab:

Once read-write access has been granted, you’ll receive an email with the subversion repository URL, which is specific to your site. You’ll also receive read access to our shared VIP plugins. For more details about our shared plugins, please see the plugins section of this site.

All code development and testing should be done in your own local development environment. Only tested code should be committed to WordPress.com.

Committing Code

Once you have read-write access, you can commit your code directly. Once you do, it is spot reviewed for security and performance concerns, and then deployed to server clusters in all of our data centers. Should you not want the commit to be deployed directly after a satisfactory review, please follow the instructions for how to schedule your deploy.

For your benefit, we take code quality, security, and performance very seriously. Every commit is spot reviewed by someone on the VIP team before it can be deployed. It’s really important to include a detailed commit message to help expedite your review. Please take a look at our deploy review guidelines. Code changes are usually deployed within a few hours during US business hours, but usually much faster (within two hours).

We do expect all committed code be thoroughly tested and follow our best practices guidelines. If we see repeated mistakes, we will revoke write access.

Please check with us before committing very complicated or large chunks of code. As a general guideline, commits should include fewer than 1,000 lines of changes or modifications to PHP and unminified JS.

If in doubt, it’s best to check with us first by submitting a ticket.  It’s a lot less work for everyone (including you) if we’re able to take a look at it before committing than having to revert the change later. We also greatly appreciate if you commit often and with each functionality as a separate commit (if possible) rather than waiting and pushing a bunch of code to us all at once. It makes the code easier to review if we’re reviewing things in chunks.

We also like to review all plugins prior to committing them to your VIP repo. We have reviewed a small, but growing list of plugins, and modified some of them to make them more stable, secure, and perform better. Since these plugins have been pre-approved, we would prefer you use these plugins if possible if you need functionality similar to what they provide. Please see the Plugin Review Process if a solution isn’t yet available.

File Types That Are Auto-Deployed

We auto-deploy commits that consist entirely of static CSS or image files. If there are no other pending deploys for your theme, your CSS design changes and image commits will be deployed almost immediately with no review. If you want to ensure that a commit is auto-deployed, be certain that it only contains the file types listed below and does not have any non-auto-deploy commits in front of it. It’s worth noting, too, that even adding a new directory to a commit will prevent it from auto-deploying. So if you commit all image files inside a newly added directory, that commit will not auto-deploy.

File types that auto-deploy:

  • png
  • jpg
  • jpeg
  • gif
  • ico
  • svg
  • css
  • less
  • sass
  • scss

Note: JavaScript is not auto-deployed.

Deploy Status

At VIP → Dashboard (/wp-admin/admin.php?page=vip-dashboard), you can see the current deploy status.

Commit Messages

All commits on the VIP repo should be accompanied by a Good Commit Message.

Reverting Code

A detailed document on how to revert via svn can be found here, Rolling Back / Reverting Changes to Your Theme Using Subversion.

If you’ve committed code you’re not happy with and would like to revert, you can do so from your local checkout. Simply use the command “svn merge -c-64320 .” where “64320” would be the revision you’d like reverted. After running that command, you’ll need to commit your revert. You’ll want to use a commit message similar to “Reverted r64320 because [explain your reasoning]”.

Note that the revert will need to be deployed as well and you can open a ticket requesting that.

Shared Accounts

We don’t allow generic usernames or shared user accounts to have write-access to your VIP code repositories, as it obfuscates which developer wrote the code in the first place, and also encourages insecure password management. Please use a unique user account for each developer on your team.

Occasionally VIP development teams prefer to have a single lead developer responsible for managing their team’s code and committing to VIP on their behalf. We would like to know if this is the setup you are using and who the lead developer is. We’re happy to support this workflow so long as the person committing is themselves a developer, and takes responsibility to review the code against our guidelines before committing. If that isn’t happening, and/or we see repeated issues around code quality, we’ll need to insist that each of your developers have separate VIP accounts and support seats.

Commit and Deploy Notifications

When a code commit is deployed to WordPress.com, an email notification is generated to every WordPress.com user who has access to the theme’s SVN repository.

In addition, we support the use of webhooks for both commits and deploys. These allow you to customize the kinds of endpoints you use to receive notifications about activity in your theme code. Note that these only work for theme repositories, not shared plugin repositories.

Code Review

What is a code review?

Every line of code that is committed to WordPress.com VIP is reviewed by the VIP Team. We don’t do in-depth code reviews to add more time to or delay your launch schedules. We do these lengthy code reviews to help you launch successfully.

The goal of our reviews is to make sure that on your launch, your site will be:

  • Secure, because pushing a site live with insecure code presents a liability to you and your whole userbase;
  • Performant, because going live and finding out that your code can’t handle the traffic levels that your site expects puts most of your launch efforts to waste.

We also review for development best practices to make sure that your site will continue to live on without significant maintenance costs or major issues when WordPress is upgraded.

There are typically three ways you will submit code to us:

  1. Theme Review: You are launching or redesigning your site, which means you will submit a complete theme to us (with plugins included).
  2. Plugin Review: Your site has already launched and you are looking to include a plugin that is not already a feature on WordPress.com or in our shared VIP Plugins directory. The plugin must be reviewed before being included on your site.
  3. Deploy Review: This is for more experienced VIP Developers who have been granted write access to their production SVN repo and are looking to make changes to the site. Every commit is reviewed before it can be deployed.

How long does a new theme or plugin code review take?

Please budget three weeks for the initial review process: one week for our review, one week for your fixes and one week for us to validate fixes and move your code into production SVN. Note however, that this is three weeks from when the review starts, not necessarily from when you submit. We schedule reviews bi-weekly and will let you know your review start date once it’s on the schedule. Review slots are generally scheduled at least a week in advance, so you will want to let us know as early as possible that you plan to submit code for review. The more information, the better. When do you plan to submit the theme or plugin? How many lines of code do you estimate submitting? When do you aim to have this code in production?

Include us in your plans as early as possible. It will make the initial theme or plugin review move faster and more smoothly.


What do you look for during Code Review?

Here’s a guide to what the VIP Engineering Team looks for when reviewing your code. We strongly recommend looking at this document before submitting your code to expedite your review process.


Theme Review

Overview: You are submitting a theme to be included on WordPress.com VIP. In this process, your theme and plugins will be reviewed line by line, making sure your code is secure, optimized, and well-architected. It typically takes 10-15 business days for a full theme review, but this can vary depending on complexity of code and the size of review queue.

Getting a Theme Ready for WordPress.com VIP

  1. Development Environment: Make sure your local development environment is set up correctly, as described here.
  2. Code Review Guidelines: Make sure to read all the code review documentation. The what we look for page is a great start.
  3. Starting Out: If you’re looking for a barebones theme, to start from, check out _s, which is built and maintained by Automattic.
    If you’re looking for something more robust to work from, we recommend selecting from one of the 300+ pre-approved WordPress.com themes. The code for all the free themes are available here.
    If you’re interested in working with a Premium theme, let us know and we can provide access to the code.
  4. Sharing is Caring: To streamline your review, be sure to use WordPress.com functionality (available in Jetpack), our Shared VIP Plugins, our Helper Functions, and our Shared Libraries whenever possible.
  5. WordPress Standards: We recommend all developers follow  WordPress Coding Standards. It ensures consistency, code cleanliness, and speeds up a review.
  6. Communicate Early: We recommend getting in touch with us early to communicate your planned launch date, but also to chat with us about how you plan on architecting your site. The earlier you include us in the process, the more streamlined your review will be. Please take a look at our recommended Launch Checklist.

Theme Review Checklist

A theme must meet all the following requirements before being approved:

  • You’ve reviewed your code for common blockers.
  • Your theme/plugins are either licensed under the GNU Public License v2 (GPL2), a compatible license, or are completely custom code that you’ve written in-house—split or proprietary licenses are not allowed. The reasoning for this is that you, and we, need to have the legal rights to modify the code if something is broken, insecure, needs optimization, etc.
  • Your code has been QA’ed in an up-to-date local environment.
  • Your code has been run through the VIP Scanner, all blocker-level issues are addressed, and non-blocking errors detailed in your submission materials.
  • The VIP environment is initialized with our helper function.
  • All data is properly validated, sanitized, and escaped. The first two apply to whenever you’re handing user-submitted data (e.g. post meta boxes, frontend forms, etc.) and the latter applies to whenever you’re printing data from the database.
  • Scripts and styles are enqueued, and are done so on the proper hook.
  • The theme does not use query_posts().
  • All custom functions are prefixed.
  • The vip_powered_wpcom() function is called in the theme’s footer.php.
  • The theme follows WordPress Coding Standards.

Ensuring a successful theme review

  • If the theme is more than just a basic theme, it will speed up the review process for us to fully understand the purpose of any custom code and what it’s trying to accomplish. Therefore, the more technical and in-depth documentation you have at the time of theme submission, the better.
  • VIP does not accept off-the-shelf, commercial themes since they tend to be overloaded with excess functionality and code which are potential security and performance risks. If you have an off-the-shelf theme that is lean, mean, secure, and performs well then let’s talk. If you’re looking for something robust to work from, we recommend selecting from one of the 300+ pre-approved WordPress.com themes. The code for all the free themes are available here.
  • If you’re running a number of sites you’ll want to take the common theme approach – it’s a single theme used across multiple sites. If each site contains some unique functionality you can add that via Child Themes. Learn more about child themes here.
  • Please make sure that the code you submit for review is well-tested and includes all the information needed to function on a clean, current WordPress installation. If any content needs to be setup in order to test your theme, please provide a WordPress export with sample data.
  • We review all plugins you include in your theme. We have reviewed a small, but growing list of plugins, and modified some of them to make them more stable, secure, and performant. If your site hasn’t launched yet on WordPress.com, then please only consider the few plugins crucial for your user experience. It will make the launch process go much smoother.
  • Please note that plugins and other functions that alter the database structure or perform write operations on the filesystem interfere with our architecture, and we likely will not be able to approve these kinds of scripts. More details are shared in Best Practices.
  • Make sure that all of your plugins are included and running from within your theme folder. The plugins will be loaded by the themes’ functions.php file or similar methods. Some plugins need alteration of paths and/or urls in order to keep functioning in such an environment.

How to submit a theme

Congrats! You are ready to submit a theme for review. To do so, zip up your theme and submit it to us via the VIP Support Portal. Here’s an example zip command that excludes development environment files that wouldn’t be included on WordPress.com:

zip -r <theme-dir>.zip <theme-dir> -x "<theme-dir>/.git*" "<theme-dir>/node_modules*" "<theme-dir>/bin*" "<theme-dir>/tests*" "<theme-dir>/phpunit*" "<theme-dir>/vendor*" "<theme-dir>/.sass-cache*" "*.DS_Store"

Please include the following information in addition to attaching the results from VIP Scanner (required):

  1. What date are you targeting to have this code launched? Please allow sufficient time in your schedule for our review and launch process.
  2. Please provide a 1-2 sentence description of your submission.
  3. Please provide a brief architectural overview of your code.
  4. Is the code GPL compatible? WordPress code is licensed under the GNU Public License v2 (GPL2). All theme and plugin code needs to be GPL compatible. Custom code you’ve written in-house—split or proprietary licenses are not allowed. The reasoning for this is that you, and we, need to have the legal rights to modify the code if something is broken, insecure, needs optimization, etc.
  5. Is this code based off of existing code? If yes, provide specific details (eg: “includes code from XYZ project…”)
  6. Does this code run successfully in a local development environment?
  7. Has this code been ran through the VIP Scanner, and have all blocker-level issues been addressed and other errors closely investigated? You’ll need to upload scanner results along with your submission
  8. Does the code correctly escape, sanitize and validate data? Our requirements may be more stringent than you’re accustomed to. Please follow our “late-escaping” best practice.
  9. Which URL do you intend to use for this site? (We do not support the www subdomain, or mapping domains to a subdirectory)
  10. Is the theme named correctly?
  11. Does this theme follow the WordPress coding standards?
  12. All custom functions must be consistently prefixed. Which prefix did you use?
  13. Does the themes root directory include the functions.php and style.css files?
  14. Is vip-init.php included at/near the top of functions.php?
  15. Are scripts and styles are enqueued, and done so on the proper hook?
  16. Is the vip_powered_wpcom() function called in the theme’s footer.php?
  17. Does the 404.php contain any database queries?
  18. Is there a “plugins” sub-directory at the theme root?
  19. Which plugins does this theme use?
  20. Are plugins in the “plugins” sub-directory called properly in functions.php? The plugin should not rely on the plugin activation and deactivation hooks as VIP plugins are a part of your theme and are loaded using require_once() rather than the plugins menu.
  21. Are there any external services, dependencies, or applications that utilize or rely on this VIP site or content (e.g. a mobile app that fetches content from the site)? If yes, how do these services interact with the site? (eg: RSS, XML-RPC, etc.)
  22. Are there any significant features or components that are to-be-developed before launch, but not included in this initial submission?
  23. Who are the main representatives from your team responsible for launch and should be included in communications?

What happens now?

The VIP Team will now peer review your theme to prepare it for production on WordPress.com VIP.

Our code review process is collaborative, and we hope to not only make your theme better, but also help you become a better WordPress developer. For reviews, we use the VIP Review Trac to help give you feedback on any errors, irregular code, or calls in the theme that must be fixed before the theme can be approved. Learn more about the review process with Trac here.

After your theme has been approved, we’ll provide access to your theme’s subversion repository.


Plugin Review

Overview: If you are interested in using a plugin that isn’t available as a pre-approved VIP shared plugin,  review it for stability, performance, and security before it can be used on WordPress.com.

Plugin Review Checklist

A plugin must meet all the following requirements before being approved:

  • WordPress code is licensed under the GNU Public License v2 (GPL2). All plugin code needs to be GPL compatible or custom code you’ve written in-house. Split or proprietary licenses are not allowed. The reasoning for this is that you, and we, need to be have the legal right to modify the code if something is broken, etc.
  • The plugin needs to run on the latest version of WordPress with MultiSite enabled.
  • The plugin should not directly write to the filesystem as this will not work with our distributed environment. You can use the WordPress API though, such as wp_handle_upload().
  • The plugin should use the existing database tables and structure (no alterations). Custom post types, custom taxonomies, post meta, etc. are incredibly flexible.
  • The plugin should not rely on the plugin activation and deactivation hooks as VIP plugins are a part of your theme and are loaded using require_once() rather than the plugins menu.
  • The plugin must follow WordPress Coding Standards.
  • The plugin must follow all VIP Code review guidelines

Other helpful information

  • If you are submitting a third-party plugin for review, we still require your team to complete an internal code review following our stated guidelines before submission.
  • If you’re currently using Jetpack on your self-hosted WordPress site, you don’t need to include it on your WordPress.com VIP site—every feature that exists in Jetpack is already included in WordPress.com.
  • When submitting a plugin, we appreciate as much detail as possible about how the plugin will be used and what it’s trying to accomplish (examples are particularly helpful). Our code review process is collaborative — we encourage you to introduce yourself to how it works.

How to submit a plugin

Congrats! You are ready to submit a plugin for review. To do so, zip up the plugin and submit it to us via the VIP Support Portal. Please include the following information:

  • Name of Plugin:
  • Expected launch date:
  • Short description of plugin:
  • Brief architectural overview:
  • Is the code GPL compatible, or custom-code written in-house?
  • Does the code follow WordPress Coding Standards?
  • Does the code properly escape, sanitize and validate data?
  • Have you checked the plugin for “Blockers” as listed in our documentation?

What happens now?

The VIP Team will now peer review your plugin to prepare it for production on WordPress.com VIP.

Our code review process is collaborative. For reviews, we use the VIP Review Trac to help give you feedback on any errors or irregular code that must be fixed before the theme can be approved. Learn more about the review process with Trac here.

Once your plugin is approved

Plugins on WordPress.com VIP are organized differently than a standard self-hosted WordPress.org site, since on VIP you only have access to your site’s theme folder. To use plugins on a WordPress.com VIP site, you add them to a “plugins” directory within your theme directory, and require_once/include_once them in functions.php. e.g.:

require_once( __DIR__ . '/plugins/custom-plugin/custom-plugin.php' );

Deploy Review

Once your theme and plugins have passed review, they are moved to the VIP production repo. Eventually, you will be granted the necessary access to submit code changes. Every commit is reviewed to ensure that it is secure, optimized and performant before it can be deployed. We also run automated PHPCS checks against all changesets so it’s worth setting up PHPCS in your local dev environment.

At VIP, we believe in a partnership with our clients. Deploy review is the most hands-on way we work together to ensure that your site is performant and secure. Feedback will typically be shared with you in a ticket, and if you ever have questions or concerns, we are always happy to discuss. We typically have three types of feedback we share:

Blockers: This category includes all security issues as well as any serious performance concerns. Code that fits in this category will not be deployed, and will be reverted if the concerns are not addressed by the end of the business day.

Fixes Required: This category includes potentially non performant code, along with code that does not follow best practices. If you have received feedback and your code has been deployed it means that the feedback needs to be addressed as soon as possible, typically within one business day.

Informational feedback: This category contains suggestions from our team. During code review we will sometimes spot bugs or have suggestions for clarity, architecture, or readability. We will always explicitly note which changes are not required but are informational in nature.

Tip for deploying on VIP:
  • Only commit tested code. Never use WordPress.com for testing or debugging. If there is something you cannot reproduce or work out in your local environment, please open a ticket and ask for assistance.
  • Including a detailed commit message speeds up the time it takes us to review and deploy the code, and is also essential for future debugging or in case of emergencies.
  • If you have significantly large or complex changes (anything over 1,000 lines) to push, please send the changes in as a patch ahead of time.
  • As always, follow Best Practices and Code Review Guidelines.

Keeping the queue clear

Given commits in subversion are linear, any commit that has feedback may delay the deployment of earlier, or subsequent, commits. Keeping the queue clear is important so that if any emergency commits need to be made, those can be deployed quickly.

For this reason, if commits have been sitting in the queue for a while, without feedback being addressed we may revert them to keep the queue clear. We’ll generally allow 24 hours but in some instances, such as wekends, we may revert sooner. If you need help generating a diff to re-commit the changes, let us know.

How to commit code

Please see Accessing Your Code for more information.

Once you’ve committed your code

We review everything before deploying, so you can expect tickets, commits, or reverts from us if we find any issues.

If issues are found in submitted code and it’s a simple fix, we fix the issue and notify the developer before pushing the code live. If it’s a more complex problem, we do not deploy the code. We may revert the code or hold the deploy depending on the severity of the issue(s) and notify the developer with guidelines on how to fix the problem.

We deploy code changes to VIP sites throughout the European and North American business day and strive to have all changes live within two hours. Note that changes to CSS files and images are deployed automatically.

WordPress.com vs. WordPress.org

WordPress is a publishing platform that makes it easy for anyone to publish online, and proudly powers millions of websites. It comes in two flavors: the fully hosted WordPress.com, and the self-hosted version available at WordPress.org. You can read more about the general differences between the two.

There are a few key differences to keep in mind when developing a theme or plugin for a WordPress.com site compared to how you might do it for self-hosted/WordPress.org sites. We’ve outlined a non-exhaustive list below.

Caching

WordPress.com provides full page caching, along with persistent object caching, out of the box. Anonymous page views are retrieved from memory for high performance and high scalability, and many db queries and other code-level objects are stored in-memory for fast retrieval. For more information, see our caching documentation.

Comments

WordPress.com has a custom comment form that allows visitors to leave comments as guests or using their WordPress.com, Facebook, or Twitter accounts. This comment form is also available for self-hosted sites via Jetpack.

Core WordPress.com features

While WordPress.com is running on trunk WordPress, we’ve added a lot of bells and whistles in the form of features for every WordPress.com user and site owner. For more information about WordPress.com core features, take a read through the WordPress.com features category in the VIP Lobby and the WordPress.com features on the main WordPress.com Support site.

Custom Database Tables

Custom database tables are not supported on WordPress.com. You should try to work within the WordPress API and use existing storage mechanisms like Custom Post Types, Taxonomies, Post Meta/Custom Fields, and so on.

Custom Fields Meta Box

For security reasons, the “Custom Fields” meta box is disabled on WordPress.com. If your theme makes use of post meta, you should add custom meta boxes to allow users to enter data. The bonus is that this makes for a better user experience.

PHP File Whitelist

WordPress.com has a PHP file whitelist, which restricts direct access to PHP files that are not core WordPress files. This means that PHP files in your theme cannot be accessed directly, which goes against best practices anyway.

Plugins

Plugins on WordPress.com VIP are organized differently than a standard self-hosted/WordPress.org site, since on VIP your access is specific to your site’s theme folder. To use plugins on a WordPress.com VIP site, you add them to a “plugins” directory within your theme directory, and require_once/include_once them in functions.php.

Registering Users

By default, users registered through VIP-hosted websites are created as WordPress.com users and must go through the WordPress.com user registration process and agree to the WordPress.com terms of service. This means that the millions of users logged in to WordPress.com will also be logged in on your domain, making it easier for them to comment on your site. If you’d like to be able to register your own user profiles or create custom registration fields you’ll need to use a 3rd-party registration service, such as our partners at Janrain. Note that you can invite any existing WordPress.com user to join your site at any permitted user level.

Server-side Cookie Handling

Because of full-page caching, cookies should not be accessed or manipulated server-side. Any cookie handling code should be done client-side.

Textdomains

For translations, WordPress.com uses the “default” textdomain and your theme should too.

Toolbar

All logged-in users will see the WordPress.com admin bar. This cannot be removed as it is integral to the user experience on WordPress.com.

URL Functions

In your VIP theme and plugins, home_url() always returns the custom domain as mapped in WordPress.com whereas site_url() returns the *.wordpress.com domain.

Admin-ajax on domain-mapped sites

If your site uses a custom domain (and not just the default *.wordpress.com one) and your theme or plugin makes requests to admin-ajax.php, you’ll need to follow these instructions to make sure your requests are successful. This extra step is necessary because your site’s backend is served at a different domain than the front of your site.

Fetching remote data

On WordPress.com VIP, we provide special cached functions for fetching external data, and require that you use these, rather than the normal WordPress.org functions. Full details on how to use these functions are here.

Storing user data

User data storage works only slightly differently on WordPress.com VIP than on WordPress.org. The basic difference is that WordPress.org’s use of the user_meta is replaced by user_attributes. From a coding perspective the two behave exactly the same and and are set and accessed through the same functions. The one difference is that unique keys are required for user_attributes. Full details are here.

Embedding Rich Media

WordPress.com VIP takes particular care to protect your site and data from malicious code embedded in your site or content. When compared to WordPress.org, on WordPress.com VIP provides additional access to additional tools in the form of shortcodes and other protections that will keep you safe when you need to embed object, iframe and script tags. Please read the full documentation on embedding content.

Custom fields

The custom fields UI isn’t supported on WordPress.com. Please create your own custom meta boxes instead.

Caching

Site speed is essential to a great web experience. WordPress.com employs multiple levels of caching automatically.

  • Full page cache: using the Batcache plugin, this caches full pageviews for a period of 5 minutes for all logged-out users
  • CDN / front-end caching: all scripts and stylesheets are served from our CDN. Images are served from our dedicated *.files.wordpress.com domain.
  • Object cache: using memcached, this provides a persistent backend for WordPress’ built-in Object cache and is used for storing transient data and short-lived data that needs to persist across page loads.
  • Advanced Post Cache: Caches WP_Query calls to minimize database queries.

While we do our part to optimize load performance, we need your help. This page has information on how to make the most of our performance optimizations in your development work.

CDN / Front-End Caching

As noted, our CDN handles serving Javascript, CSS and theme image, while uploaded images are served from our dedicated *.files.wordpress.com domain. When new versions of CDN-served files are deployed, the CDN will automatically flush its own cache and start serving the new version. This does not necessarily affect browser-side caching.

For CSS and Javascript, we automatically bust browser caches by appending a query string, ?m=[modified_time] to them in the source with a filter. For images, you will need to either change the file name or add a query string where the URL to the image is referenced.

Although not exactly caching, we concatenate both Javascript and CSS code and also minify CSS. You will not need to change the way your Javascript or CSS is written to take advantage of this optimization.

Database Queries

You should avoid direct database queries and always use the WordPress API. Many of the existing WordPress functions contain internal caching and will serve previously queried data if it’s still valid. Be wary of uncached functions, though.

For cases when you are sure that you cannot use a function that contains caching and need to do something that is resource intensive, you should cache the results using one of the options noted below.

Object cache and Transients

There are two approaches to caching within WordPress core, transients and the object cache. For a standard WordPress.org install, the difference is that transients are persistent and write to the options table with a timestamp whereas object cache functions are not persistent and cache on a page-by-page basis.

However, if you have persistent caching enabled on the server, then the transient functions become wrappers for the normal cache functions. On WordPress.com, transients act essentially identically to data stored in the object cache. Data stored in the cache will be available across multiple page loads but they can be cleared outside of your control.

This means that for both, you’ll need to check whether a value was returned from cache, and regenerate the data if it wasn’t. It can look something like this:

// Load my data from cache
$my_data = wp_cache_get( 'my-data' );
// Check if the cache actually returned something
if ( false === $my_data ) {
	$my_data = $wpdb->get_results( $query );
	wp_cache_set( 'my-data', $my_data );
}
// Present $my_data

Options table

Only when you’re storing a small amount of data that can’t easily be regenerated from a page request should you cache data in the options table.

Example: caching WP_Query

Here’s what a typical WP_Query loop looks like:

<?php $args = array( 'orderby' => 'comment_count', 'posts_per_page' => '1', 'ignore_sticky_posts' => 1 );
$query = new WP_Query( $args );
while ( $query->have_posts() ) : $query->the_post();
	// do stuff
endwhile;

Here’s how to modify that loop to cache the results of the WP_Query object:

// First, let's see if we have the data in the cache already
$query = wp_cache_get( 'ordered_comments_query' ); // the cache key is a unique identifier for this data

if( false === $query ) {
	// Looks like the cache didn't have our data
	// Let's generate the query
	$args = array( 'orderby' => 'comment_count', 'posts_per_page' => '1', 'ignore_sticky_posts' => 1 );
	$query = new WP_Query( $args );

	// Now, let's save the data to the cache
	// In this case, we're telling the cache to expire the data after 300 seconds
	wp_cache_set( 'ordered_comments_query', $query, '', 300 ); // the third parameter is $group, which can be useful if you're looking to group related cached values together
}

// Once we're here, the $query var will be set either from the cache or from manually generating the WP_Query object
while ( $query->have_posts() ) : $query->the_post();
	// do stuff
endwhile;

Other considerations

Keep in mind that even though the object cache is meant to be a persistant data store, cache entries can and do get evicted. As such, your code should fail gracefully or regenerate the data as needed.

Ideally, you wouldn’t pass an expires value and do smart cache invalidation instead. For example, hook into save_post and call wp_cache_delete with the cache key(s). That way you ensure that you only really need to regenerate the cache data when it’s changed.

There are certain cases where you would use unique cache keys, for example, say you have a gallery slider on different category pages and you’re caching the results of the query used to generate it. If you used the same key across the board, you’d end up with the same data everywhere. Instead, you can suffix the cache key with something like the category id to make sure you have unique key for each cached data set. In particularly complex cases, you can use an md5 value of the query args as the cache key.

Try and avoid cache slams when setting multiple caches by using a more random cache expiration time, using something like;

wp_cache_set( $cache_key, $data, null, mt_rand( 5 * MINUTE_IN_SECONDS, 10 * MINUTE_IN_SECONDS ) );

Caching Remote Data

The most common cause of slow page load times for our customers has been with 3rd party services and pulling in content from other sites. For 3rd party services try to late load them when possible, keywords: load without blocking, lazy load, and delay loading. For second group of common problems check out Fetching Remote Data.

Ready to get started?

Tell us about your needs

Let us lead the way. We’ll help you select a top tier development partner. We’ll train your developers, operations, infrastructure, and editorial teams. We’ll coarchitect your deployment processes. We will provide live support for peak events. We’ll help your people avoid dark alleys and blind corners, and reduce wasted cycles.