Book Call

How to use Composer to manage WordPress core, plugins, and themes as dependencies?

So, you’re looking to wrangle your WordPress site like a pro, right? Specifically, you’re wondering if you can use Composer to manage your WordPress core, plugins, and themes. The short answer is: yes, absolutely! It’s a fantastic way to bring order to the chaos, especially for larger or more complex sites, or if you’re a developer who likes things tidy.

Think of Composer as your super-organized assistant for all your PHP projects, and WordPress is no exception. Instead of manually downloading, uploading, and updating every single piece of your site, Composer lets you define what you need, and it handles the rest.

Why Bother with Composer for WordPress?

Let’s be real for a second. Managing WordPress manually can get messy. You’ve got the core files, then all those plugins you’ve added, and then the themes, some of which you might have even customized yourself. Keeping track of versions, making sure everything’s compatible, and rolling back when something breaks can be a real chore.

Composer steps in and offers a much cleaner, more predictable way to handle all of that. It’s all about dependency management – figuring out what your project needs and making sure you have the right versions of everything.

Here’s what you gain:

  • Version Control: You know exactly which version of WordPress, which plugins, and which themes are installed. No more guessing games.
  • Reproducibility: You can recreate your exact site environment on another server or for another developer with ease. This is a lifesaver for development and staging sites.
  • Simplified Updates: Updating core, plugins, and themes becomes a one-command operation. Much less clicking.
  • Streamlined Deployment: Deploying your site to production becomes far less prone to error.
  • Better Organization: Your project structure becomes more logical and easier to navigate, especially for those who are used to Composer workflows from other PHP projects.

It’s not magic, and it does require a bit of a learning curve, but the payoff in terms of efficiency and sanity is huge.

If you’re looking to enhance your WordPress site’s performance after managing your core, plugins, and themes with Composer, you might find it beneficial to explore how to optimize your site further. A related article that provides valuable insights on improving website speed and performance is available at Google PageSpeed Insights: A Comprehensive Guide. This resource can help you understand the metrics that affect your site’s loading times and offer practical tips for achieving better results.

Getting Started: The Composer Basics

Before we dive into the WordPress-specific stuff, let’s get some Composer fundamentals under your belt. If you’re already familiar with Composer, feel free to skim through this.

Installing Composer

First things first, you need Composer installed on your system. If you haven’t done this already, head over to the official Composer website and follow the instructions for your operating system. It’s usually a simple download and execution.

Once installed, you can verify it by opening your terminal or command prompt and typing:

“`bash

composer –version

“`

You should see the Composer version number. Easy peasy.

The composer.json File

The heart of any Composer project is the composer.json file. This file lives in the root of your project and tells Composer what you need. It’s a JSON file, so it’s structured with keys and values.

Here’s a super simplified example of what a composer.json might look like:

“`json

{

“name”: “your-username/your-wordpress-site”,

“description”: “A Composer-managed WordPress site.”,

“require”: {

“php”: “>=7.4”

}

}

“`

  • name: Your project’s name, usually in a vendor/project format.
  • description: A brief explanation of what your project is.
  • require: This is where you list your project’s dependencies. We’ll be adding WordPress and its components here shortly.

The composer.lock File

When you run Composer commands like composer install or composer update, it creates a composer.lock file. This file records the exact versions of all installed dependencies. It’s crucial for ensuring that everyone working on the project, or you deploying the project, uses the same set of package versions. You should always commit your composer.lock file to your version control system (like Git).

Key Composer Commands

  • composer install: Reads the composer.json file and installs all the specified dependencies in the exact versions locked in composer.lock. If composer.lock doesn’t exist, it will create it based on the composer.json.
  • composer update: Reads the composer.json file, checks for newer versions of your dependencies that satisfy the version constraints, and installs them. It then updates the composer.lock file to reflect these new versions. Use this carefully, as it can introduce breaking changes if not managed properly.
  • composer require : Adds a new package as a dependency to your project and installs it. It also updates your composer.json and composer.lock files.
  • composer remove : Removes a package as a dependency and uninstalls it, updating the relevant files.

Setting Up WordPress with Composer

Now let’s get to the good stuff: managing WordPress itself with Composer. This is where things get a bit more specific.

The composer.json for WordPress

Instead of creating your composer.json from scratch with just a PHP requirement, we’ll be using a popular package that helps us manage WordPress core. The most common way to do this is by requiring the johnpbloch/wordpress package.

Here’s how you might structure your composer.json for a WordPress site. Let’s assume you’re setting up a new project:

“`json

{

“name”: “your-username/your-wordpress-site”,

“description”: “A Composer-managed WordPress site.”,

“type”: “project”,

“license”: “MIT”,

“require”: {

“php”: “^7.4|^8.0|^8.1|^8.2|^8.3”,

“johnpbloch/wordpress”: “^6.4.0”,

“composer/installers”: “^2.0”

},

“extra”: {

“installer-paths”: {

“web/wp-content/plugins/{$name}/”: [“type:wordpress-plugin”],

“web/wp-content/themes/{$name}/”: [“type:wordpress-theme”]

}

},

“repositories”: [

{

“type”: “composer”,

“url”: “https://wpackagist.org”

}

]

}

“`

Let’s break this down:

  • "type": "project": This tells Composer that this composer.json file defines a project, not just a library.
  • "require":
  • "php": "^7.4|^8.0|^8.1|^8.2|^8.3": Specifies the PHP version requirements. WordPress has its own minimum PHP requirements, so it’s good practice to align with those.
  • "johnpbloch/wordpress": "^6.4.0": This is the key. We’re requiring the WordPress core files themselves. The ^6.4.0 means we want version 6.4.0 or any later minor or patch version (e.g., 6.4.1, 6.5.0, but not 7.0.0).
  • "composer/installers": "^2.0": This is a utility package that helps Composer install packages into specific directories based on their type (plugins, themes). Essential for WordPress.
  • "extra": This section is crucial for mapping package types to installation paths.
  • "installer-paths": This tells composer/installers where to put things.
  • "web/wp-content/plugins/{$name}/": ["type:wordpress-plugin"]: Any package marked as type: wordpress-plugin will be installed in the web/wp-content/plugins/ directory, with {$name} being the plugin’s package name. Note: The web/ prefix assumes your web server’s document root is web/. Adjust this if your setup is different (e.g., public_html/ or just wp-content/).
  • "web/wp-content/themes/{$name}/": ["type:wordpress-theme"]: Similarly, themes of type: wordpress-theme go into web/wp-content/themes/.
  • "repositories": This tells Composer where to look for packages.
  • "type": "composer", "url": "https://wpackagist.org": This points Composer to WPackagist, a fantastic repository that mirrors the official WordPress plugin and theme directory as Composer packages. This is how we can easily install plugins and themes from the WordPress.org repository using Composer.

Initializing the Project

Once you have your composer.json file ready, open your terminal, navigate to the directory where you want your WordPress project to live, and run:

“`bash

composer install

“`

This command will:

  1. Download WordPress core files from johnpbloch/wordpress into your project.
  2. Download composer/installers and make it available to handle installations.
  3. Create your vendor/ directory (where Composer puts downloaded packages).
  4. Create your composer.lock file.

After this initial run, your project structure will start to take shape. You’ll typically have a vendor/ directory containing WordPress core and composer/installers. You’ll also need to create your wp-config.php file manually in the root of your project for now, and configure your database connection.

Managing Plugins and Themes

This is where Composer really shines for WordPress management. Instead of going to wp-admin and clicking “Add New,” you’ll use Composer to add and manage your plugins and themes.

Adding Plugins

Let’s say you want to add the popular Yoast SEO plugin. You’d use WPackagist (which we configured in our repositories) to find its package name. A quick search on WPackagist (or remembering common ones) tells us it’s yoast/wordpress-seo.

To add it, run:

“`bash

composer require yoast/wordpress-seo –prefer-dist

“`

  • composer require yoast/wordpress-seo: This tells Composer to find the yoast/wordpress-seo package and add it to your dependencies.
  • --prefer-dist: This tells Composer to download the zip archive (dist) rather than the source code, which is usually faster and simpler for WordPress plugins and themes.

Composer will then:

  1. Update your composer.json to include yoast/wordpress-seo in the require section.
  2. Download the plugin from WPackagist.
  3. Because of the installer-paths configuration in your composer.json and the type: wordpress-plugin identifier provided by WPackagist, it will automatically place the plugin in web/wp-content/plugins/wordpress-seo/.
  4. Update your composer.lock.

You can then activate Yoast SEO from your WordPress admin area as usual.

Adding Themes

The process for themes is very similar. Let’s say you want to use the Astra theme:

“`bash

composer require wp-themes/astra –prefer-dist

“`

Composer will download Astra and place it in web/wp-content/themes/astra/.

Managing Custom/Private Plugins and Themes

What about plugins or themes you’ve developed yourself or are using from a private repository? Composer can handle those too.

Local Path Dependencies

If you have a plugin or theme in a local subdirectory of your project, you can manage it as a path repository.

Let’s say you have a custom plugin at ./my-custom-plugin. You can add it to your composer.json like this:

“`json

{

// … other parts of your composer.json …

“repositories”: [

{

“type”: “composer”,

“url”: “https://wpackagist.org”

},

{

“type”: “path”,

“url”: “my-custom-plugin”,

“options”: {

“symlink”: true

}

}

],

“require”: {

// … other requirements …

“my-company/my-custom-plugin”: “*”

}

}

“`

And then in your composer.json‘s require section, you’d list it: "my-company/my-custom-plugin": "*".

  • "type": "path": Indicates this is a local path.
  • "url": "my-custom-plugin": The relative path to your plugin.
  • "options": { "symlink": true }: This is powerful. It creates a symbolic link from your vendor directory (or the wp-content/plugins directory, depending on how composer/installers is configured for this type) to your local plugin directory. This means changes you make locally are immediately reflected without needing to re-run composer install.

After adding this to your composer.json, run composer install. Composer will create a symlink, and composer/installers will ensure it’s placed correctly in your wp-content directory.

Private Git Repositories

If your custom plugin or theme is hosted on a private Git repository (like GitHub, GitLab, Bitbucket), you can add it as a VCS (Version Control System) repository.

“`json

{

// … other parts of your composer.json …

“repositories”: [

{

“type”: “composer”,

“url”: “https://wpackagist.org”

},

{

“type”: “vcs”,

“url”: “git@github.com:your-username/your-private-plugin.git”

}

],

“require”: {

// … other requirements …

“your-company/your-private-plugin”: “dev-main”

}

}

}

“`

  • "type": "vcs": Indicates a Version Control System repository.
  • "url": The URL of your Git repository. For private SSH access, use the git@... format. For HTTPS, use https://.... If using HTTPS with private repositories, you’ll need to configure authentication.
  • "your-company/your-private-plugin": "dev-main": This tells Composer to require a package named your-company/your-private-plugin and to look for the main branch (or master, or a specific tag). You might need to replace dev-main with a tag name for stable releases.

You’ll need to ensure your SSH keys are set up correctly for private Git repositories, or use other authentication methods for HTTPS.

Removing Plugins and Themes

When you no longer need a plugin or theme, you can remove it using Composer:

“`bash

composer remove yoast/wordpress-seo

“`

This will:

  1. Remove the dependency from your composer.json.
  2. Remove the plugin files from your wp-content/plugins/ directory.
  3. Update your composer.lock.

You can then deactivate the plugin or theme through your WordPress admin area just to be sure.

If you’re looking to streamline your WordPress development workflow, understanding how to use Composer to manage WordPress core, plugins, and themes as dependencies is essential. For a deeper dive into this topic, you might find it helpful to read a related article that discusses best practices and tips for using Composer effectively. This resource can provide valuable insights and enhance your understanding of dependency management in WordPress. You can check it out here: related article.

Managing WordPress Core Updates

With johnpbloch/wordpress in your composer.json, updating WordPress core is as simple as running:

“`bash

composer update johnpbloch/wordpress

“`

This will upgrade your WordPress core to the latest version that satisfies the constraint in your composer.json. For example, if you had "johnpbloch/wordpress": "^6.4.0", running composer update could potentially update it to 6.5.0 or 6.4.3, but not 7.0.0.

Important Note on WordPress Core Updates: While Composer makes updating core easy, you cannot directly update WordPress core files by simply changing the version number in composer.json and then running composer update. The johnpbloch/wordpress package is designed to be installed into a specific location, and its updates are managed by Composer. You will likely need to follow a specific workflow for core updates that involves potentially moving files or using scripts provided by the johnpbloch/wordpress package itself. Often, the recommended approach is to delete the core directory and re-run composer install, or to follow specific instructions provided by the johnpbloch/wordpress maintainers for their update process. Always check the package’s documentation for the most current and safest update procedure for core. A common pattern is to have custom scripts in your composer.json that handle core updates more gracefully.

Structuring Your Project Files

A Composer-managed WordPress site often has a slightly different file structure organization. The goal is to keep your core WordPress files and your vendor directory separate from your custom code.

A common and recommended structure looks something like this:

“`

your-wordpress-project/

├── env/ # Optional: For environment specific configs

│ ├── development.php

│ └── production.php

├── web/

│ ├── wp-admin/

│ ├── wp-includes/

│ ├── wp-content/

│ │ ├── mu-plugins/ # For Must-Use plugins

│ │ ├── plugins/ # Managed by Composer

│ │ ├── themes/ # Managed by Composer

│ │ └── uploads/ # User uploads

│ ├── index.php # Main WordPress index file

│ └── .htaccess # Apache configuration

├── vendor/ # Managed by Composer

│ ├── johnpbloch/ # WordPress core files

│ ├── composer/

│ └── … # Other dependencies

├── wp-config.php # WordPress configuration file (manual for now)

└── composer.json

└── composer.lock

“`

In this structure:

  • The web/ directory contains all the publicly accessible WordPress files. This is often the document root for your web server.
  • wp-content/ is inside web/ and contains your plugins, themes, and uploads.
  • vendor/ is outside web/. This is crucial because you do not want your vendor directory to be publicly accessible. It contains WordPress core and all your Composer-managed plugins and themes. The composer/installers package, when configured with paths like web/wp-content/..., will place them within the web/ directory.
  • You’ll need to modify your index.php to point to the correct wp-load.php and wp-settings.php within the vendor/johnpbloch/wordpress directory. The johnpbloch/wordpress package usually provides instructions on how to do this in its README.

Adapting wp-config.php and index.php

With this structure, your wp-config.php file needs to be in the root, and your index.php in web/ needs to be adjusted.

A typical web/index.php might look like this:

“`php

/**

  • WordPress front controller

*

  • This file isolates the WordPress bootstrapping process.
  • It’s included by the Composer autoloader.

*

  • @package WordPress

*/

require __DIR__ . ‘/../vendor/autoload.php’; // Autoloader

require __DIR__ . ‘/../wp-config.php’; // User configuration

require_once ABSPATH . ‘wp-load.php’; // WordPress core loader

“`

And your wp-config.php will reside in the project root. You’ll need to define ABSPATH correctly.

“`php

/**

  • The base configuration for WordPress

*

  • The wp-config.php creation script uses this file as its template.
  • You do not have to edit this file, you can simply fill in the database settings. A support page is available
  • at https://codex.wordpress.org/Editing_wp-config.php.

*

  • This file also contains the plugin installer paths.

*

  • @link https://codex.wordpress.org/Editing_wp-config.php

*/

// Define the absolute path to the WordPress directory.

// This is important for the Composer installed WordPress core.

define( ‘ABSPATH’, __DIR__ . ‘/vendor/johnpbloch/wordpress/’ );

// … other database settings and WordPress constants …

define( ‘DB_NAME’, ‘database_name_here’ );

define( ‘DB_USER’, ‘username_here’ );

define( ‘DB_PASSWORD’, ‘password_here’ );

define( ‘DB_HOST’, ‘localhost’ );

define( ‘DB_CHARSET’, ‘utf8’ );

define( ‘DB_COLLATE’, ” );

// … salts and keys …

define( ‘AUTH_KEY’, ‘put your unique phrase here’ );

define( ‘SECURE_AUTH_KEY’, ‘put your unique phrase here’ );

define( ‘LOGGED_IN_KEY’, ‘put your unique phrase here’ );

define( ‘NONCE_KEY’, ‘put your unique phrase here’ );

define( ‘AUTH_SALT’, ‘put your unique phrase here’ );

define( ‘SECURE_AUTH_SALT’, ‘put your unique phrase here’ );

define( ‘LOGGED_IN_SALT’, ‘put your unique phrase here’ );

define( ‘NONCE_SALT’, ‘put your unique phrase here’ );

// Load Composer’s autoloader

require __DIR__ . ‘/vendor/autoload.php’;

// Add required plugin installer paths from composer/installers

// Make sure your composer.json extra.installer-paths matches these.

define(‘WP_PLUGIN_DIR’, __DIR__ . ‘/web/wp-content/plugins’);

define(‘WP_THEME_DIR’, __DIR__ . ‘/web/wp-content/themes’);

/ That’s all, stop editing! Happy publishing. /

/** Sets the WordPress directory */

//define( ‘ABSPATH’, dirname(__FILE__) . ‘/’ ); // Original ABSPATH definition

“`

The crucial part here is adjusting ABSPATH to point to where Composer installed WordPress core files (inside vendor/johnpbloch/wordpress/). You’ll also need to adjust WP_PLUGIN_DIR and WP_THEME_DIR to point to the correct locations within your web directory where composer/installers will place the downloaded packages.

Advanced Tips and Considerations

Using Composer for WordPress is powerful, but there are a few advanced concepts and things to keep in mind.

Version Constraints

Understanding Composer’s version constraints is key to managing updates.

  • ^1.2.3: Allows updates to any minor or patch version within the 1.x series (e.g., 1.2.4, 1.3.0, but not 2.0.0). This is often the default and recommended.
  • 1.2.3: Requires exactly version 1.2.3.
  • >=1.2.3: Requires version 1.2.3 or higher.
  • <2.0.0: Requires any version less than 2.0.0.
  • ~1.2.3: A more restrictive version of ^1.2.3 which allows patch versions but not minor versions (e.g., 1.2.4 but not 1.3.0).

Use these constraints thoughtfully. For plugins and themes, sticking to ^ or even pinning to specific versions (1.2.3) can be safer, especially for critical production sites.

Autoloader and wp-load.php

Composer’s autoloader (vendor/autoload.php) is what makes loading classes and files seamless. Your WordPress setup will need to include this autoloader so that all your dependencies are available.

The interaction between Composer's autoloader and WordPress's own loading mechanism (wp-load.php) is important. Make sure your index.php and wp-config.php are correctly configured to load both.

Custom Themes and Plugins

When developing your own themes or plugins, you can also manage them with Composer. You can put them in your vendor directory and point composer/installers to install them into wp-content/themes or wp-content/plugins. Alternatively, for themes and plugins that are part of your site's architecture but not necessarily shared libraries, you might keep them in a separate directory and use path repositories as described earlier.

Deploying Composer-Managed WordPress Sites

Deployment with Composer involves a few steps:

  1. Commit composer.json and composer.lock: Always commit these files to your version control.
  2. Install Dependencies on Server: When deploying to a staging or production server, you'll typically run composer install --no-dev (the --no-dev flag skips development dependencies) to install all necessary packages.
  3. Handle Files: Ensure your theme and plugin files from vendor/ are correctly symlinked or copied into the web/wp-content/ directory.
  4. Database: Always provision your database separately and manage it with database migration tools if necessary.
  5. Uploads: User uploads (web/wp-content/uploads/) are typically not managed by Composer and should be handled via file transfer (e.g., SFTP, rsync).

Security Considerations

  • Private Repositories: Be careful with credentials when accessing private Git repositories. Use SSH keys or secure token-based authentication.
  • vendor Directory: Never expose your vendor directory to the public internet. Ensure your web server's document root is correctly configured outside of this directory.
  • wp-config.php: Keep your wp-config.php secure, and do not commit sensitive database credentials directly into your repository. Use environment variables or a secrets management system.

Conclusion

Using Composer to manage your WordPress core, plugins, and themes is a significant step towards a more professional, organized, and maintainable WordPress development workflow. It brings the power of PHP package management to your WordPress projects, offering better control over versions, simplifying updates, and making deployments far more reliable. While there's an initial learning curve, the long-term benefits in terms of efficiency and reduced headaches are well worth the effort. It might feel a bit unusual at first, especially if you’re used to the traditional WordPress way, but embrace it, and you'll find yourself wondering how you ever managed without it.