How do I use the PHP Composer extension?

This FAQ was last modified on: Friday, May 15, 2020 12:58pm
Category: 

The new PHP Composer UI tool makes it easier to manage your Composer-based applications right from your site control panel.

What is Composer?

Composer is a tool to help manage PHP applications with more complex dependencies, such as Drupal 8.

By telling Composer what your site project needs, like a new module, it can install all the required files.

It can also update your site project's installed dependencies. Composer can calculate when a newer version might not be compatible with another dependency, reducing the risk of your site breaking during an update.

PHP Composer on Plesk: How do I...

While it's strongly recommended to use Composer CLI to develop and manage your site projects locally, the PHP Composer tool on Plesk provides some helpful options for managing Composer applications from your site control panel.

Where can I find the PHP Composer tool?

The PHP Composer tool has an icon button on the Websites & Domains landing page of your site's control panel.

How do I tell PHP Composer about my site project?

Composer scans the entire site account for composer.json files it can use.

Once it finishes scanning: click the [change] option to select and confirm the folder where your site project's composer.json lives.

Once loaded, you will see the list of dependencies that Composer has identified for your project, along with the current versions and any available updates.

How do I install the files my site project needs?

To download and install any of the files your site project needs, just click the Install button.

How do I update my site project files?

To update your dependencies to the latest compatible versions, just click the Update button.

How do I add a new dependency to an existing project?
  1. Go to edit your composer.json file
  2. Manually add the dependency you'd like to include
    Note: Without using Composer CLI, you'll need to determine how to correctly declare the new dependency.
  3. Save your composer.json file changes
  4. PHP Composer will prompt you to click Update
How do I remove an installed dependency?
  1. Go to edit your composer.json file
  2. Manually remove the dependency from your composer.json file
  3. PHP Composer will prompt you to click Update
My site project requires files hosted on github.gatech.edu, or another private repo. How do I provide PHP Composer credentials to use?

The PHP Composer tool won't read local files where you would normally set credentials (e.g. auth.json), so they need to be passed to the tool as an environment variable.

The environment variable is COMPOSER_AUTH, which accepts a JSON-formatted string using the same information as the auth.json file.

Note: Multiple sets of credentials can be listed in with the JSON-formatted string, in case you have dependencies that pull from different private repository platforms.

  1. Create a personal access token you can use to reach the private repo and save the token string
    Note: Access tokens for PHP Composer only need read permissions for repos.
  2. Go to the PHP Composer tool
  3. Click the Specify button to add a new environment variable
  4. Enter in the variable name and value for passing in the credentials:
    • Name: COMPOSER_AUTH
    • Value: A JSON-formatted string listing your credentials in the same style as auth.json. For example, to add credentials for a personal access token for github.gatech.edu:

      {"github-oauth": {"github.gatech.edu": "MYTOKEN"}}

  5. Click the save/update button to confirm the new environment variable
  6. Add the private repo dependency to your composer.json file and test to confirm the credentials work
My Composer site project has a different web root than the default (httpdocs). How do I change the webroot?

You can now set your site's webroot via the Plesk control panel:

  1. Go to Websites & Domains > Hosting Settings
  2. Edit the 'Document root' field to set your site's webroot location (e.g. httpdocs/web)

Common Issues

 

Error: Allowed memory size exhausted

PHP Composer is allowed to use up to 2GB of memory to run. Complex site projects may end up running into this limit.

Suggested solutions:

  • Edit the composer.json file to remove dependencies you are no longer using
  • Move to local development with Composer CLI, to set your own PHP memory limits
  • If you have a Drupal 8 project, consider including the Composer Drupal Optimizations dependency, which significantly reduces memory and CPU overhead
    Note: This dependency needs to be included before it can take effect. You may need to first remove unnecessary dependencies or move to local development in order to add it.
Error: Credentials issue

If your composer.json includes packages from private repos or platforms, such as github.gatech.edu, you will need to pass in credentials so that Composer can access those packages (see above).

If the 'Specify' button is disabled when you try to add credentials:

This is a known Plesk UI bug that will be fixed in a future update.

Cause: The Composer UI needs to successfully scan the composer.json file at least once before it will enable you to add your credentials as an environment variable. If the composer.json file already contains references to assets that require credentials, the Composer UI's initial scan will fail, and the 'Specify' button to add your credentials as an environment variable will end up disabled.

Workaround:

Copy-paste the composer.json file contents into a plain text editor of your choice: you will need to copy-paste it again later

  1. Edit the hosted composer.json file to remove ALL references to assets that require credentials. Using the DX8 composer.json as an example:
    • Remove all the "Repositories" entries for the GT assets so that it looks like this:

      "repositories": [
          {
              "type": "composer",
              "url": "https://packages.drupal.org/8"
          }
      ],

    • Remove the "Require" entry lines for the GT assets, aka:

      "gt/gt_profile_curie"
      "gt/gt_theme"
      "gt/gt_tools"
      "gt/hg_reader"

  2. Navigate to the Composer UI: if you have edited the composer.json file correctly, it should scan successfully and the 'Specify' button should now be enabled
  3. Click the 'Specify' button to add your credentials as directed
  4. Edit the composer.json file to copy-paste the original contents back in
  5. The Composer UI should now be able to successfully scan and run Composer Install with your composer.json file

I've set my credentials correctly, but I'm still getting an error: Contact us with a copy of the error output and we can help troubleshoot.